⚙️ Jest Configuration

Where Config Lives

Jest reads its configuration from one of three places, in order of what teams usually prefer as a project grows:

1. A "jest" key in package.json — fine for a couple of options.
2. A jest.config.js file — the sweet spot: it's real JavaScript, so you can add comments and compute values.
3. A jest.config.ts file — the same, with TypeScript type-checking on the config itself.

Generate a documented starter with the built-in wizard, then trim it to what you use:

npx jest --init

A modern CommonJS config exports a plain object. The @type comment gives you editor autocomplete without any extra tooling:

// jest.config.js
/** @type {import('jest').Config} */
const config = {
  testEnvironment: 'node',          // where tests run (see next section)
  roots: ['<rootDir>/src'],          // where to look for tests
  testMatch: ['**/*.test.js'],      // which files are tests
  clearMocks: true,                 // reset mock state before every test
  verbose: true,                    // print each test name as it runs
};

module.exports = config;

The Test Environment

The single most important option is testEnvironment. It decides which global APIs exist inside your tests. Pick the wrong one and you'll hit confusing errors like document is not defined or slow tests that load a fake DOM you never use.

Since Jest 28, jsdom ships as a separate package so server projects don't pay for it. Install it only when you need browser globals:

npm install --save-dev jest-environment-jsdom

// jest.config.js — for front-end code
/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: 'jsdom',
};

You don't have to pick one globally. A magic comment at the top of a single test file overrides the environment just for that file — handy in a mostly-server project with a few DOM tests:

/**
 * @jest-environment jsdom
 */
test('renders a greeting into the DOM', () => {
  document.body.innerHTML = '<div id="app"></div>';
  mount(document.getElementById('app'));
  expect(document.querySelector('#app').textContent).toContain('Hello');
});

Setup & Teardown Files

Some preparation needs to happen outside individual tests — extending the assertion library, loading environment variables, or starting a shared service once. Jest gives you four hooks, and choosing correctly matters for speed and isolation.

The one you'll use constantly is setupFilesAfterEnv — it runs at the point where Jest globals like expect already exist, so you can add custom matchers. Configure it like so:

// jest.config.js
/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
};

// jest.setup.js — runs before every test file
// Add the extra DOM matchers used across the whole suite:
require('@testing-library/jest-dom');

// A global cleanup that applies to every test:
afterEach(() => {
  jest.clearAllMocks();
});

Module Resolution & Transforms

Real projects import things Node can't natively run in a test: path aliases like @/utils, CSS files, images, or modern/TypeScript syntax. Two options bridge the gap.

moduleNameMapper — rewrite imports

It maps import paths (via regex) to something Jest can load. The two everyday uses are aliases and non-JS asset stubs:

// jest.config.js
/** @type {import('jest').Config} */
module.exports = {
  moduleNameMapper: {
    // 1. Path alias: "@/utils/math" -> "<rootDir>/src/utils/math"
    '^@/(.*)$': '<rootDir>/src/$1',

    // 2. Stub out styles & images so importing them doesn't crash
    '\\.(css|scss|less)$': '<rootDir>/test/styleMock.js',
    '\\.(png|jpg|svg)$': '<rootDir>/test/fileMock.js',
  },
};

// test/styleMock.js  → an import like `import './Button.css'` becomes {}
module.exports = {};

transform — compile before running

Jest runs on CommonJS. To test TypeScript or the newest ESM syntax, a transformer compiles files first. The lightest modern choice is Babel (Jest wires it up automatically if a babel.config.js is present) or ts-jest for TypeScript:

// jest.config.js — TypeScript via ts-jest preset
/** @type {import('jest').Config} */
module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
};

Coverage & Thresholds

Code coverage measures how much of your source ran while the tests executed — reported as four numbers: statements, branches, functions, and lines. Jest has it built in; no extra tools required.

npx jest --coverage

// jest.config.js
/** @type {import('jest').Config} */
module.exports = {
  collectCoverage: true,
  // Only measure YOUR source, and skip barrel/index files:
  collectCoverageFrom: [
    'src/**/*.js',
    '!src/**/index.js',
    '!src/**/*.stories.js',
  ],
  coverageDirectory: 'coverage',
  coverageReporters: ['text', 'lcov'], // console summary + HTML report
};

The output is a per-file table with a summary row:

-----------------|---------|----------|---------|---------|
File             | % Stmts | % Branch | % Funcs | % Lines |
-----------------|---------|----------|---------|---------|
All files        |   88.4  |   76.2   |   90.0  |   88.1  |
 cart.js         |   95.0  |   88.9   |  100.0  |   95.0  |
 discount.js     |   72.7  |   50.0   |   66.7  |   72.7  |
-----------------|---------|----------|---------|---------|

Enforcing a floor with coverageThreshold

To stop coverage from silently sliding over time, set minimums. If any number falls below, Jest exits non-zero — which fails the CI build. You can set a global floor and stricter rules for critical files:

// jest.config.js
/** @type {import('jest').Config} */
module.exports = {
  coverageThreshold: {
    global: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80,
    },
    // Hold the money-handling module to a higher bar:
    './src/billing/': {
      branches: 90,
    },
  },
};

Jest or Vitest?

Jest is the long-standing default and everything above is battle-tested. But if your app is built with Vite (as most new React/Vue projects are), there's a compelling alternative: Vitest. It reuses your existing Vite config and transform pipeline, so ESM and TypeScript work out of the box with no separate Babel/ts-jest setup.

The good news: the concepts transfer almost verbatim. A Vitest config looks like this, and the test block accepts the same environment and coverage ideas you just learned:

// vitest.config.js
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    environment: 'jsdom',           // same idea as Jest's testEnvironment
    setupFiles: ['./vitest.setup.js'],
    globals: true,                  // use describe/test without importing
    coverage: {
      provider: 'v8',
      thresholds: { lines: 80, functions: 80, branches: 75 },
    },
  },
});

💡 Rule of thumb: New Vite-based front-end project? Start with Vitest. Node/Express backend or an established Jest codebase? Stay with Jest. Everything you know about environments, setup files, and coverage carries across either way.

Practice & Quiz

/** @type {import('jest').Config} */
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  moduleNameMapper: {
    '\\.(css|scss)$': '<rootDir>/test/styleMock.js',
  },
  collectCoverageFrom: ['src/**/*.{js,jsx}', '!src/**/index.js'],
  coverageThreshold: {
    global: { lines: 80 },
  },
};

// jest.setup.js
require('@testing-library/jest-dom');

/**
 * @jest-environment jsdom
 */

Best Practices & Pitfalls

✅ Do

• Keep config in a jest.config.js with the /** @type {import('jest').Config} */ comment for autocomplete
• Default to testEnvironment: 'node'; opt into jsdom only where you touch the DOM
• Put shared matcher extensions and global hooks in a setupFilesAfterEnv file
• Scope coverage to your source with collectCoverageFrom, excluding barrels and generated files
• Use coverageThreshold as a ratchet against regressions, not a number to game
• Anchor every path with <rootDir>

❌ Don't

• Ship jsdom in a pure backend project — it's a needless dependency and slowdown
• Put matcher extensions in setupFiles (too early — expect doesn't exist yet)
• Set a 100% threshold and reward assertion-free tests that only chase the number
• Measure coverage on node_modules, mocks, or config files

Summary

📚 Additional Resources

• Jest — Configuring Jest (all options)
• Jest — testEnvironment
• Vitest — Getting Started
• Vitest — Migrating from Jest

🚀 What's Next?

Your runner is dialed in. Now the real craft: Writing Effective Unit Tests — the Arrange-Act-Assert structure, testing behavior instead of implementation, test.each for table-driven cases, and how to spot a brittle test before it wastes your team's time.