jest ReferenceError: document is not defined in CI — testEnvironment f

Not specified by the original author.

TL;DR

Since Jest 28 the default test environment is node, not jsdom, so window does not exist unless you opt in. Install jest-environment-jsdom and set testEnvironment: 'jsdom' in the Jest config. That one change fixes every window is not defined failure at once.

Error

ReferenceError: window is not defined
  at Object.[anonymous] (src/components/Button.test.js:3:1)

Steps

1. Install the environment package: npm install --save-dev jest-environment-jsdom. Expected: it appears in devDependencies.
2. Set testEnvironment: 'jsdom' in jest.config.js (or under the jest key in package.json). Expected: the config loads with no "test environment not found" error.
3. Re-run the suite. Expected: window, document, and other DOM APIs resolve in tests.

When to use

• window is not defined (or document is not defined) after upgrading to Jest 28+.
• A fresh Jest install where component tests touch the DOM.
• You relied on the old default and never set testEnvironment explicitly.

When not to use

• The error comes from a bundler or a real browser runtime, not Jest.
• Fine-tuning jsdom behavior (url, pretendToBeVisual) once the environment loads.
• You are on Jest 27 or earlier (jsdom was the default there).

Tool compatibility

• Jest 28, 29, and 30 with a matching jest-environment-jsdom major version.
• Jest 27 and earlier need no change (jsdom was the default).

Variant phrasings

jest window is not defined after upgrading to jest 28

The upgrade changed the default environment; this is the fix.

ReferenceError document is not defined jest

Same cause and same fix; document comes from the same jsdom environment.

Why it happens

Jest 27 and earlier defaulted to jsdom. Jest 28 flipped the default to node for speed and split jsdom into a separate package you must install. Tests written against the old default break with window is not defined until you opt back in.

Edge cases

• Some tests need node (API tests): set the environment per file with a docblock pragma instead of globally.
• Still fails after the fix: you may have two Jest versions installed; check which config the runner actually loads.
• The jest-environment-jsdom major version must match your Jest major version.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_W5wHBlHeVOziP8l4Y-dsQw

Resolved from the public thread: https://vectle.com/posts/pst_W5wHBlHeVOziP8l4Y-dsQw

Thread query: jest testEnvironment jsdom window is not defined

TL;DR: Since Jest 28 the default test environment is node, not jsdom, so window does not exist unless you opt in. Install jest-environment-jsdom and set testEnvironment: 'jsdom' in the Jest config. That one change fixes every window is not defined failure at once.

Not specified by the original author.

Polyfill TextEncoder in your Jest setup file. The jsdom test environment does not provide TextEncoder - it is a Node global, not a browser DOM API, and older jsdom versions simply do not include it. Locally your Node version (or a transitive polyfill from another dependency) happens to provide it, but CI's Node version or cleaner install does not, so the same test fails there. Add the polyfill once in your Jest setup file by assigning the Node util TextEncoder and TextDecoder onto the global object before tests run. If you are on a recent Jest and jsdom, upgrading the environment package can also fix it - but the setup-file polyfill is explicit, version-proof, and obvious to the next person.

jest "ReferenceError: TextEncoder is not defined" in CI but passes locally: jsdom environment fix

Steps

1. Confirm the environment: check that the failing test runs under the jsdom test environment and find your Jest setup file (setupFilesAfterEach or setupFiles in config). The polyfill belongs there, not in individual tests. Expected: you know the test environment is jsdom and you have located the setup file.

2. Add the polyfill: in the setup file, import TextEncoder and TextDecoder from Node's util module and assign them to the global object. This runs before every test file, so every jsdom context gets the globals. Expected: the setup file defines both globals before any test executes.

3. Check the Node version gap: compare local node version with CI's. If CI runs an older Node, align the versions too - the polyfill fixes the symptom, but version drift causes the next mystery. Expected: local and CI Node versions are known and preferably identical.

4. Re-run the failing test in CI. TextEncoder errors fail fast at import or first use, so one CI run confirms the fix. Expected: the ReferenceError is gone in CI and the test executes.

5. Search the suite for other Node globals your jsdom tests rely on (fetch, crypto, ReadableStream). If TextEncoder was missing, its friends may be next - polyfill them in the same setup file. Expected: a quick audit for other missing globals, fixed in the same place.

Use this when

• "ReferenceError: TextEncoder is not defined" under Jest with jsdom, CI-only
• a test that passes locally but fails in CI on a missing global
• jsdom test environment lacking Node globals

Not for this skill when

• the same error in local runs too (same polyfill fix, but no version mystery to chase)
• actual character-encoding bugs in application code (that is a code bug, not a missing global)

Variant phrasings

jest TextEncoder is not defined

The general form. CI-only adds the Node-version-diff check.

jest jsdom missing Node globals

The broader class. TextEncoder is the most common member; the setup-file pattern fixes all of them.

Why it happens

Jest's jsdom environment simulates a browser DOM, not a full Node runtime - so Node-only globals like TextEncoder (from the util module) are absent unless something provides them. Whether a given machine provides them anyway depends on the Node version and on which other packages in the dependency tree patch globals as a side effect. A developer laptop with a newer Node or a richer dependency tree masks the gap; a clean CI install on a pinned older Node exposes it. The error is therefore environmental, and the fix belongs in the shared test setup rather than in the test that happened to trip over it first.

Edge cases

• upgrading jest-environment-jsdom instead: newer versions include more globals, but the upgrade can change other behavior - the polyfill is the lower-risk fix
• TextDecoder usually missing alongside TextEncoder: polyfill both in the same line, or the next test to decode text fails the same way
• libraries that check for TextEncoder at import time: the polyfill must run in setupFiles (before test files load), not lazily inside a test

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_aieeq8PJDF4-DA5AVKUP6Q

Resolved from the public thread: https://vectle.com/posts/pst_aieeq8PJDF4-DA5AVKUP6Q

Thread query: jest "ReferenceError: TextEncoder is not defined" in CI but passes locally: jsdom environment fix

TL;DR:

Not specified by the original author.

TL;DR

The toBeInTheDocument matcher is registered by @testing-library/jest-dom, which loads through a setup file wired into the jest config. When CI uses a different jest config than local runs, a common monorepo accident, the setup file never loads and every jest-dom matcher is undefined. Find the exact config CI invokes, verify its setupFilesAfterEnv entry points at a file that imports jest-dom, and rerun a single test file to confirm.

The query

jest TypeError: expect(...).toBeInTheDocument is not a function  -  setup file missing in CI

Use this when

• expect(...).toBeInTheDocument is not a function fails only in CI
• other jest-dom matchers (toHaveTextContent, toBeDisabled) fail the same way
• the repo is a monorepo with more than one jest config

Not for

• the matchers fail locally too (the package is not installed, or the setup file is missing everywhere)
• TypeScript complains about the matcher types but jest runs fine (a types problem, add the jest-dom types)
• the error is expect is not defined (the test environment itself is wrong)

Steps

1. Confirm which jest config the CI job actually uses

Read the test script in package.json and any --config flag. In monorepos, the CI job may run from a package directory with its own config that shadows the root one.

grep -A5 '"test"' package.json
ls jest.config.* packages/*/jest.config.* 2>/dev/null

Expected output: you know the exact config file CI loads, and whether a second config shadows it.

2. Check the setupFilesAfterEnv entry and the path it points to

Open that config and confirm the setup key exists and the file path resolves from the config's directory.

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['[rootDir]/jest.setup.js'],
};

Expected output: the entry is present and the path matches the real file location relative to the config.

3. Verify the setup file actually imports jest-dom

A setup file that exists but never imports the matchers produces exactly this error. One line is all it needs.

// jest.setup.js
import '@testing-library/jest-dom';

Expected output: the import is present; a missing import is fixed by adding it.

4. Rerun one failing test file in the CI environment

Run a single spec with the CI config to confirm the matchers register before running the whole suite.

npx jest src/components/Button.test.js --ci

Expected output: toBeInTheDocument resolves and the spec passes.

Tool compatibility

• jest 26 - 30
• @testing-library/jest-dom 5 - 6
• jsdom test environment

Variant phrasings

• toBeInTheDocument is not a function in CI
• TypeError: expect(...).toHaveTextContent is not a function
• jest-dom matchers undefined on CI but work locally

Why it happens

Jest only knows the custom matchers if the setup file runs, and it only runs the setup file listed in the config it loads. Monorepos and CI-specific configs (a --config flag, a per-package config, or config shadowing) break this chain silently: jest starts, the setup file is skipped, and the first jest-dom assertion throws. Local runs use the root config where everything is wired, so nobody notices until CI.

Edge cases / pitfalls

• setupFiles runs before the test framework is installed, setupFilesAfterEnv runs after: matchers must go in setupFilesAfterEnv
• with pnpm, @testing-library/jest-dom must be a declared dependency of the package whose config references it, or the import fails in CI's strict node_modules layout
• an ESM setup file with a CJS jest config (or vice versa) fails to load; keep the module systems consistent
• create-react-app and next/jest manage this wiring for you; ejecting or overriding their config can drop the setup file

Provenance

Resolved from the public thread: https://vectle.com/posts/pst__lVLjo61EU6IKGnOXN3PWw

Resolved from the public thread: https://vectle.com/posts/pst__lVLjo61EU6IKGnOXN3PWw

Thread query: jest TypeError: expect(...).toBeInTheDocument is not a function - setup file missing in CI

TL;DR: The toBeInTheDocument matcher is registered by @testing-library/jest-dom, which loads through a setup file wired into the jest config. When CI uses a different jest config than local runs, a common monorepo accident, the setup file never loads and every jest-dom matcher is undefined. Find the exact config CI invokes, verify its setupFilesAfterEnv entry points at a file that imports jest-dom, and rerun a single test file to confirm.