jsdom vs happy-dom

Not specified by the original author.

TL;DR

Pick happy-dom when you want speed and your tests only touch common DOM APIs. Pick jsdom when you need fuller browser API coverage (like full getComputedStyle behavior or layout-adjacent APIs). Most unit suites run fine on happy-dom and finish noticeably faster; switch to jsdom only when a test fails because an API is missing or behaves differently. You can even mix them: run the fast environment by default and jsdom for the few files that need it.

The query

vitest happy-dom vs jsdom: which to pick

Use this when

• Setting up a new vitest project and choosing the DOM environment
• Tests pass in one environment but fail in the other
• You want to speed up a slow DOM test suite
• Deciding whether per-file environment overrides are worth it

Not for

• Browser E2E testing (use playwright, cypress, or similar)
• React Testing Library render questions unrelated to the environment
• Node-only tests with no DOM at all (use environment: 'node')

Steps

1. List the browser APIs your tests actually use (DOM traversal, events, localStorage, matchMedia, layout reads) and note which ones are exotic. Expected output: a short list of APIs; anything beyond basic DOM/events is a jsdom candidate.
2. Start with happy-dom (environment: 'happy-dom') since it is the faster default. Expected output: suite runs green and completes faster than under jsdom.
3. If a test fails on a missing or divergent API, confirm the same test passes under jsdom by setting // @vitest-environment jsdom at the top of that file. Expected output: the file passes under jsdom, proving the failure is environment-specific, not a code bug.
4. Keep per-file overrides only for files that need them; leave the fast default for everything else. Expected output: vitest --project (or the normal run) is green with the default environment plus a handful of jsdom-annotated files.

Provenance

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

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

Thread query: vitest happy-dom vs jsdom: which to pick

TL;DR: Pick happy-dom when you want speed and your tests only touch common DOM APIs. Pick jsdom when you need fuller browser API coverage (like full getComputedStyle behavior or layout-adjacent APIs). Most unit suites run fine on happy-dom and finish noticeably faster; switch to jsdom only when a test fails because an API is missing or behaves differently. You can even mix them: run the fast environment by default and jsdom for the few files that need it.

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.

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: