ReferenceError: Node is not defined

[thinkasany]

• @testing-library/jest-dom version:
• node version:
• jest (or vitest) version:
• npm (or yarn) version:

Relevant code or config:

var your => (code) => here;

What you did:

Upgrading from 6.8.0 to 6.9.0

What happened:

Encountering an error

Run bun run test:node
$ bun run version && jest --config .jest.node.js --no-cache
$ tsx scripts/generate-version.ts
  console.log
    Current React Version: 19.1.1

      at Object.<anonymous> (tests/setup.ts:31:9)

FAIL components/__tests__/node.test.tsx
  ● Test suite failed to run

    ReferenceError: Node is not defined

    > 1 | import '@testing-library/jest-dom';
        | ^
      2 |
      3 | import { toHaveNoViolations } from 'jest-axe';
      4 | import jsdom from 'jsdom';

      at Object.<anonymous> (node_modules/@testing-library/jest-dom/dist/matchers-0a2a9889.js:1986:4)
      at Object.<anonymous> (node_modules/@testing-library/jest-dom/dist/index.js:3:16)
      at Object.require (tests/setupAfterEnv.ts:1:1)

Test Suites: 1 failed, 1 total
Tests:       0 total
Snapshots:   0 total
Time:        1.163 s
Ran all test suites.
error: script "test:node" exited with code 1

Reproduction:

.jest.node.js

const { moduleNameMapper, transformIgnorePatterns } = require('./.jest');

// jest config for server render environment
module.exports = {
  setupFiles: ['./tests/setup.ts'],
  setupFilesAfterEnv: ['./tests/setupAfterEnv.ts'],
  moduleFileExtensions: ['ts', 'tsx', 'js', 'md'],
  moduleNameMapper,
  transform: {
    '\\.tsx?$': './node_modules/@ant-design/tools/lib/jest/codePreprocessor',
    '\\.js$': './node_modules/@ant-design/tools/lib/jest/codePreprocessor',
    '\\.md$': './node_modules/@ant-design/tools/lib/jest/demoPreprocessor',
    '\\.(jpg|png|gif|svg)$': './node_modules/@ant-design/tools/lib/jest/imagePreprocessor',
  },
  testRegex: 'node\\.test\\.(j|t)sx$',
  testEnvironment: 'node',
  transformIgnorePatterns,
  // bail: true,
};

Problem description:

Our repository doesn't lock packages. To promptly identify issues with upstream repositories, we encountered this issue during the 6.9.0 release. However, looking at the release changelog, it's unclear what adjustments were needed.

https://github.com/testing-library/jest-dom/releases/tag/v6.9.0

Suggested solution:

Avoid breaking changes in minor versions

[gcko]

@thinkasany @gnapse @nossbigg I believe the issue is because of the use of Node in src/to-appear-before.js: v6.8.0...v6.9.0#diff-433b49cbc94570a3ed23bd48f950a003bd0feb5be36a53f84ba2d04f7adcc27bR5-R10

Specifically, the error states, "ReferenceError: Node is not defined" <--- Note the capital "N" on node

--EDIT--

Looking into it more, I see the issue: Node is a Web API interface that's only available in browser environments, not in Node.js - DOM API's don't exist in that context.

Because those are numerical constants, they could just be defined in code:

const DOCUMENT_POSITIONS = {
  DISCONNECTED: 1,
  PRECEDING: 2,
  FOLLOWING: 4,
  CONTAINS: 8,
  CONTAINED_BY: 16,
  IMPLEMENTATION_SPECIFIC: 32
};

const DOCUMENT_POSITIONS_STRINGS = {
  [DOCUMENT_POSITIONS.DISCONNECTED]: 'Node.DOCUMENT_POSITION_DISCONNECTED',
  [DOCUMENT_POSITIONS.PRECEDING]: 'Node.DOCUMENT_POSITION_PRECEDING',
  [DOCUMENT_POSITIONS.FOLLOWING]: 'Node.DOCUMENT_POSITION_FOLLOWING',
  [DOCUMENT_POSITIONS.CONTAINS]: 'Node.DOCUMENT_POSITION_CONTAINS',
  [DOCUMENT_POSITIONS.CONTAINED_BY]: 'Node.DOCUMENT_POSITION_CONTAINED_BY',
  [DOCUMENT_POSITIONS.IMPLEMENTATION_SPECIFIC]: 'Node.DOCUMENT_POSITION_IMPLEMENTATION_SPECIFIC',
};

These values are part of the DOM specification and won't change, so it is a fairly clean approach.

[gnapse]

Thank you for reporting this issue. I've investigated this and can confirm that the ReferenceError: Node is not defined occurs when using Bun as the JavaScript runtime.

However, I need to clarify a few important points:

Runtime support scope

This project officially supports Node.js with standard DOM testing libraries (jsdom). We don't currently test against or officially support Bun. While Bun aims for Node.js compatibility, there are differences in how it handles DOM APIs and global interfaces.

The issue stems from Bun not providing the global Node interface that's available in browser environments or Node.js with DOM libraries like jsdom. The code references Node.DOCUMENT_POSITION_* constants, which are standard DOM API constants.

Regarding "Breaking Changes"

The characterization of this as a "breaking change in a minor version" needs context (and it also is not a helpful "suggested solution").

The new .toAppearBefore / .toAppearAfter matchers work correctly in all officially supported environments (Node.js + DOM libraries, browsers). A feature that works in supported environments but fails in an unsupported runtime doesn't constitute a breaking change by semantic versioning standards.

Path forward

While this isn't technically a breaking change, I understand the impact on Bun users. We can consider making the code more runtime-agnostic by using hardcoded constants instead of relying on the Node interface. This would improve compatibility across different JavaScript runtimes.

Would you be interested in contributing a fix that replaces the Node.DOCUMENT_POSITION_* references with their numeric constant values? This would solve the Bun compatibility issue without affecting functionality in supported environments.

Bonus point

Bonus point if you can contribute anything else needed to make sure something like this does not happen again. What would be needed? A Github workflow that would run the tests in a Bun environment?

[gcko]

@gnapse I am using Node 20.11.0 and this happens for me as well.

[nossbigg]

@gnapse @thinkasany @gcko

• As per MDN, Node and compareDocumentPosition() aren't available in NodeJS, owing to the fact that both of them belong to the Web APIs

  • https://developer.mozilla.org/en-US/docs/Web/API/Node#browser_compatibility
  • https://developer.mozilla.org/en-US/docs/Web/API/Node/compareDocumentPosition

• This issue wasn't caught in our tests, because of a (possible) misconfig on jest.config.node.js? (ie. ...config is squashing testEnvironment: 'node')

  • https://github.com/testing-library/jest-dom/blob/v6.9.0/tests/jest.config.node.js#L7-L8

• Given that the Node.-related constants are standardized by the DOM WHATWG spec, I think it's safe for us to replace those references with hex constants (as per suggested by @gcko )

  • It is highly unlikely for the constants to be changed upstream, unless the spec itself changes? 😅

[aaschlote]

I have faced the same issue in my PR to update the version 6.9.0. I could fix adding the setupFile only for the component tests. However, the Changelog for this version doesn't mention any changes related it.

[omridevk]

see this PR:
#707

[gnapse]

Ok, fair enough. I thought this was Bun-specific because of how the original report mentioned it, and since it does not fail for some of us that do not use Bun. Let's go with the constants instead. I approved #707 and will merge it soon.

[arvinxx]

we meet the same issue with v6.9.0 as here : https://github.com/lobehub/lobe-chat/actions/runs/18119663964/job/51642651389?pr=9474

hope the patch can be merged ASAP.

[gnapse]

Merged. should be released soon.

[gnapse]

Closed in #707