jest SyntaxError: Cannot use import statement outside a module in CI

Not specified by the original author.

TL;DR

Jest runs in CommonJS by default, so import in your test files fails without a transform. Configure babel-jest or ts-jest to transform your sources, or run Jest in ESM mode deliberately.

Error

SyntaxError: Cannot use import statement outside a module
    at Runtime.createScriptFromCode

Steps

1. Check for a babel config that handles ESM-to-CJS. Expected: @babel/preset-env present, or the error explains its absence.
2. If using TypeScript, ensure ts-jest or babel-jest with preset-typescript processes the test files. Expected: .ts tests transform.
3. Verify transform in jest config covers your file extensions. Expected: no gaps for .ts, .tsx, .jsx.
4. As an alternative, run Jest as ESM (NODE_OPTIONS=--experimental-vm-modules), but only if the whole toolchain is ESM-ready. Expected: a deliberate choice, not an accident.
5. Re-run. Expected: imports work.

When to use

• The error names your own test or source file.
• A fresh Jest setup or a TS migration.

When not to use

• The error names a file in node_modules (transformIgnorePatterns skill).
• You are on Vitest (native ESM; different setup).

Tool compatibility

• Jest 27 through 30; babel-jest, ts-jest.

Variant phrasings

Jest SyntaxError import statement

The short form; transform configuration is the fix.

Cannot use import statement in Jest with TypeScript

ts-jest or babel typescript preset missing.

Why it happens

Node-style ESM import is not valid CommonJS. Jest's default runtime is CJS, so something must compile the syntax away.

Edge cases

• Mixed CJS/ESM codebases need per-file transform decisions; keep the config explicit.
• jest.mock() hoisting interacts with ESM transforms; keep mocks at the top.
• ESM mode in Jest is still rough; CJS transform remains the pragmatic default.

Provenance

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

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

Thread query: jest cannot use import statement outside a module

TL;DR: Jest runs in CommonJS by default, so import in your test files fails without a transform. Configure babel-jest or ts-jest to transform your sources, or run Jest in ESM mode deliberately.

Not specified by the original author.

TL;DR

Jest says it cannot find a module in CI, but the same test passes on every developer machine. The import path's letter casing does not match the file on disk: macOS and Windows filesystems ignore case, so the wrong casing resolves locally, while Linux CI resolves paths literally and fails. Diff the import specifier against the real filename with git ls-files, fix the casing in the import statement, then add a CI check so a case-only rename can never slip through again.

The query

jest Cannot find module in CI but passes locally  -  case-sensitive import how to find

Use this when

• jest reports Cannot find module only in CI, never locally
• someone recently renamed a file or moved it between directories
• the team develops on macOS or Windows and CI runs Linux
• the error names a relative import, not a node_modules package

Not for

• the module is missing everywhere, including locally (it was never installed or the file does not exist)
• a path alias like @/ is misconfigured (that is a moduleNameMapper problem, not casing)
• the error is a TypeScript type error with no jest failure

Steps

1. Copy the exact module specifier from the CI log

Open the failing CI log and copy the module string jest tried to resolve, exactly as printed, including the relative path and any alias prefix.

Cannot find module './components/Header' from 'src/pages/Dashboard.test.js'

Expected output: you have the literal specifier jest failed on, not a paraphrase of it.

2. Compare the specifier against the real filename on disk

List the tracked files with git and compare letter by letter. The mismatch is usually one capital letter, often from a file that was renamed without git noticing the case change.

git ls-files | grep -i "components/header"
# shows: src/components/header.tsx   (lowercase h)
# test imports: './components/Header' (uppercase H)

Expected output: the casing difference between the import and the tracked file is visible.

3. Reproduce it on a case-sensitive filesystem

The bug is invisible on macOS and Windows. Reproduce it in a Linux container before fixing, so you know the fix is real and not another local illusion.

docker run --rm -v "$PWD":/app -w /app node:20 npx jest src/pages/Dashboard.test.js

Expected output: the same Cannot find module error appears inside the container.

4. Fix the casing in the import statement

Change the import to match the tracked filename exactly. Do not rename the file to match the import unless the whole team agrees, because every other importer may use the other casing.

// before
import Header from './components/Header';
// after
import Header from './components/header';

Expected output: jest resolves the module and the test runs in the container.

5. Add a guard so it cannot regress

For TypeScript, enable forceConsistentCasingInFile in tsconfig. For plain JS, add a CI step that fails when any import's casing differs from the tracked file, for example a small script over git ls-files.

{
  "compilerOptions": { "forceConsistentCasingInFile": true }
}

Expected output: a future case-only mismatch fails fast in CI instead of shipping.

Tool compatibility

• jest 26 - 30
• Node 16 - 22
• Linux CI runners (GitHub Actions, CircleCI, Jenkins, GitLab CI)

Variant phrasings

• Cannot find module './Components/Header' from 'src/...' (CI only)
• TS2307: Cannot find module './utils/foo' after a rename
• jest Cannot find module '@/components/Bar' on GitHub Actions but not on Mac

Why it happens

Local filesystems on macOS (APFS default) and Windows (NTFS) are case-insensitive but case-preserving: they happily open header.tsx when you ask for Header.tsx. Linux ext4 is case-sensitive and treats them as different files. Git with core.ignorecase=true will not even record a case-only rename, so the repo looks fine while the import is wrong.

Edge cases / pitfalls

• git may silently ignore case-only renames: use git mv -f old new or set core.ignorecase=false to make them explicit
• barrel files (index.ts re-exports) hide the real filename, so check the re-export chain too
• in monorepos, the same file can be imported through two different aliases with different casing; fix all of them
• some editors auto-import with the wrong casing on save; the guard in step 5 is what actually ends the cycle

Provenance

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

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

Thread query: jest Cannot find module in CI but passes locally - case-sensitive import how to find

TL;DR: Jest says it cannot find a module in CI, but the same test passes on every developer machine. The import path's letter casing does not match the file on disk: macOS and Windows filesystems ignore case, so the wrong casing resolves locally, while Linux CI resolves paths literally and fails. Diff the import specifier against the real filename with git ls-files, fix the casing in the import statement, then add a CI check so a case-only rename can never slip through again.

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.