Jest Testing Configuration Reference

TL;DR

• Bottom line: Configure Jest in jest.config.ts using ts-jest preset for TypeScript; set testEnvironment to "jsdom" for React or "node" for backend.
• Key tool/command: npx jest --config jest.config.ts
• Watch out for: Forgetting to install ts-node — Jest cannot read jest.config.ts without it.
• Works with: Jest 29.x–30.x, TypeScript 5.4+, Node.js 18+, React 18+/19.

Constraints

• Jest 30 requires Node.js 18+
• TypeScript config files require ts-node installed
• ESM support requires --experimental-vm-modules flag
• jest-environment-jsdom is separate since Jest 28
• transform must match file types — .ts/.tsx need ts-jest or @swc/jest

Quick Reference

Decision Tree

START
├── TypeScript? → ts-jest preset
├── React/DOM? → testEnvironment: 'jsdom'
├── ESM (type: module)? → ESM preset + --experimental-vm-modules
├── Need speed? → @swc/jest (3-5x faster)
├── Path aliases? → moduleNameMapper
└── DEFAULT → ts-jest + node environment

Step-by-Step Guide

1. Install Jest and TypeScript support

[src4]

npm install --save-dev jest ts-jest @types/jest
# For React: npm install --save-dev jest-environment-jsdom @testing-library/react @testing-library/jest-dom

2. Create jest.config.ts

[src1]

import type { Config } from 'jest';

const config: Config = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  testMatch: ['**/__tests__/**/*.test.ts', '**/*.spec.ts'],
  verbose: true,
};

export default config;

3. Configure path aliases

[src1]

moduleNameMapper: {
  '^@/(.*)$': '<rootDir>/src/$1',
},

4. Configure coverage

collectCoverage: true,
coverageThreshold: {
  global: { branches: 80, functions: 80, lines: 80, statements: 80 },
},

Code Examples

Node.js + TypeScript backend

import type { Config } from 'jest';

const config: Config = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src'],
  moduleNameMapper: { '^@/(.*)$': '<rootDir>/src/$1' },
  collectCoverage: true,
  coverageThreshold: { global: { branches: 80, functions: 80, lines: 80, statements: 80 } },
  clearMocks: true,
  restoreMocks: true,
};
export default config;

@swc/jest (faster transforms)

const config: Config = {
  testEnvironment: 'node',
  transform: {
    '^.+\\.(t|j)sx?$': ['@swc/jest', {
      jsc: { parser: { syntax: 'typescript', tsx: true } },
    }],
  },
};

Monorepo (project-based)

const config: Config = {
  projects: [
    { displayName: 'api', preset: 'ts-jest', testEnvironment: 'node', roots: ['<rootDir>/packages/api/src'] },
    { displayName: 'web', preset: 'ts-jest', testEnvironment: 'jsdom', roots: ['<rootDir>/packages/web/src'] },
  ],
};

Anti-Patterns

Wrong: Not installing jest-environment-jsdom

// ❌ BAD — jsdom NOT bundled since Jest 28
{ testEnvironment: 'jsdom' }  // Error: Cannot find module

Correct: Install separately

# ✅ GOOD
npm install --save-dev jest-environment-jsdom

Wrong: Not handling CSS/image imports

// ❌ BAD — Jest crashes on CSS imports
// No moduleNameMapper for static assets

Correct: Map static assets to mocks

// ✅ GOOD
moduleNameMapper: {
  '\\.(css|less|scss)$': 'identity-obj-proxy',
  '\\.(jpg|png|svg)$': '<rootDir>/__mocks__/fileMock.ts',
}

Common Pitfalls

• jest.config.ts not loading: Fix: npm install --save-dev ts-node. [src1]
• Tests pass locally, fail in CI: Fix: pin Node version. [src3]
• Slow tests: ts-jest type-checks. Fix: use @swc/jest. [src4]
• Jest 30 type errors: Stricter toHaveBeenCalledWith. Fix: use expect.any(). [src3]
• Coverage missing files: Fix: collectCoverageFrom: ['src/**/*.ts']. [src1]
• Cannot use import: Fix: add ts-jest transform. [src4]

Diagnostic Commands

# Show resolved config
npx jest --showConfig

# Run matching tests
npx jest --testPathPattern="auth"

# Watch mode
npx jest --watch

# Coverage report
npx jest --coverage

# List tests
npx jest --listTests

Version History & Compatibility

When to Use / When Not to Use

Important Caveats

• Jest 30 bundles internals — unofficial deep imports will break
• @swc/jest is faster but does not type-check — run tsc --noEmit separately
• ESM support requires --experimental-vm-modules flag
• jest.config.ts on Node 24+ with CJS may have issues