Jest Admin & Architecture Guide

This guide is for engineers who integrate Jest deeply, operate it in CI at scale, extend it with custom runners/environments/reporters, or contribute to Jest itself. It documents Jest's monorepo architecture, the end-to-end test-run pipeline, the complete configuration reference (every option with its default and scope), the extension points, and operational concerns like performance tuning, caching, and CI integration.

For day-to-day test authoring — writing tests, matchers, mocking, snapshots — see the User Guide. This guide assumes that material and goes beneath it.

Note

Jest is distributed as a single installable package (jest) but built as a monorepo of ~45 cooperating packages under packages/. Understanding which package owns which responsibility is the key to operating and extending Jest effectively.

1. Executive Summary

Jest is a batteries-included JavaScript/TypeScript testing framework. Architecturally it is a pipeline of specialized packages orchestrated by jest-core:

1. The CLI (jest-cli) parses arguments and hands off to jest-core.
2. jest-config resolves and normalizes configuration into a frozen global config plus one project config per project.
3. jest-core builds a SearchSource over a jest-haste-map file index to find test files, orders them with a test sequencer, then dispatches them.
4. A runner (jest-runner by default) executes each test file — in-process or across a jest-worker pool.
5. For each file, a jest-runtime sandbox provides module loading, mocking, and the test environment (jest-environment-node or jest-environment-jsdom).
6. The test framework (jest-circus by default) runs the describe/test blocks; assertions go through expect.
7. Results flow back through jest-test-result to the reporters (jest-reporters).

2. Architecture

2.1 The test-run pipeline

        $ jest --coverage src/
                │
                ▼
┌──────────────────────────────┐
│ jest-cli                      │  parse argv (args.ts), validate, build Config.Argv
│  run() → @jest/core runCLI()  │
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ jest-config                   │  resolve config file, apply preset, normalize,
│  readConfigs()                │  split into GlobalConfig + ProjectConfig[]
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ jest-core                     │  orchestration: createContext per project
│  runJest() / watch()          │
│   ├─ jest-haste-map  ─────────┼─► crawl + index files (watchman or node fs)
│   ├─ SearchSource    ─────────┼─► select test files (testMatch / changed / patterns)
│   ├─ @jest/test-sequencer ────┼─► order tests (failed-first, slowest-first)
│   └─ TestScheduler   ─────────┼─► dispatch to runner(s)
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ jest-runner                   │  per-file execution; spawns jest-worker pool
│  (one worker per CPU slot)    │  sets JEST_WORKER_ID per worker
└──────────────┬───────────────┘
               ▼  (inside each worker, per test file)
┌──────────────────────────────┐
│ jest-runtime                  │  sandboxed module registry: require/import,
│  + jest-environment-node/jsdom│  jest.mock, transform via jest-transform,
│  + jest-resolve               │  resolve via jest-resolve
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ jest-circus (test framework)  │  run describe/test/hooks; assertions via `expect`
│  + expect + jest-snapshot     │  pretty-format + jest-diff for output
└──────────────┬───────────────┘
               ▼
┌──────────────────────────────┐
│ jest-test-result → jest-reporters │  aggregate + render (default, summary,
│                                    │  coverage, GitHub Actions, JSON, custom)
└────────────────────────────────────┘

2.2 Package inventory

The monorepo ships these packages (selected high-priority ones). All are published under the @jest/ scope or as jest-*.

Tip

When debugging unexpected behavior, identify which package owns the concern. A resolution failure belongs to jest-resolve; a transform problem to jest-transform/babel-jest; a snapshot mismatch to jest-snapshot; a parallelism issue to jest-runner/jest-worker.

2.3 Global config vs. project config

jest-config splits the normalized options into two frozen objects:

• GlobalConfig — settings that apply to the whole run: bail, coverageReporters, maxWorkers, watch, reporters, testPathPatterns, testNamePattern, verbose, silent, forceExit, shard, seed, etc. These are global-only and cannot be set inside an individual project.
• ProjectConfig — settings that apply per project: testEnvironment, transform, moduleNameMapper, setupFiles, setupFilesAfterEnv, roots, testMatch, snapshotSerializers, automock, clearMocks, coveragePathIgnorePatterns, etc.

This split is why multi-project setups (the projects option) let each project define its own environment and transforms while the global flags (workers, reporters, watch) are shared.

Important

If you put a global-only option (e.g. coverageReporters, maxWorkers) inside an entry of projects, Jest emits: "Option … is not supported in an individual project configuration. Move it to the root configuration." Global options belong at the top level.

2.4 The Haste module map and caching

jest-haste-map crawls your files once per run and builds an in-memory map of modules, mocks, and (for React Native) platform-specific files. It can crawl with Watchman (fast, incremental) when available, falling back to a Node.js filesystem crawl.

The transform cache and haste map live under the cache directory, which defaults to your OS temp dir under jest/ (suffixed per-UID on POSIX). Override with cacheDirectory. Clear it with jest --clearCache.

<os-tmp>/jest_<uid>/      ← default cache directory
  haste-map-*             ← serialized module map
  jest-transform-cache-*  ← transformed source cache, keyed by content + config

Note

The transform cache key incorporates the transformer, its config, and the file content. Changing your Babel/transform config invalidates the cache automatically. The haste map respects modulePathIgnorePatterns and (in watch mode) watchPathIgnorePatterns.

3. System Requirements

Warning

Odd-numbered Node releases (19, 21, 23) are intentionally excluded from the supported engines range. CI images must use 18.14+, 20, 22, or 24+.

4. Complete Configuration Reference

Every option below is a real Jest configuration key. Default is the value Jest ships (from jest-config's Defaults.ts); blank means there is no default (the feature is off / unset unless you set it). Scope indicates whether the option is global (whole run) or project-level.

4.1 Core / discovery

4.2 Environment & execution

4.3 Setup & teardown

4.4 Mocking & modules

4.5 Transformation

4.6 Coverage

4.7 Reporting & output

4.8 Watch & change detection

4.9 Misc runtime flags

4.10 Deprecated options

These options are still parsed but emit a deprecation warning (and throw under errorOnDeprecated). Migrate to the replacement.

5. Extension Points

Jest is designed to be extended at every stage of the pipeline. Each extension is a module path you reference in configuration.

5.1 Custom transformer

A transformer converts source files Jest cannot run natively. It implements process (and optionally processAsync) plus a getCacheKey:

// my-transformer.js
module.exports = {
  process(sourceText, sourcePath, options) {
    return {code: compile(sourceText)};
  },
  getCacheKey(sourceText, sourcePath, options) {
    return createHash(sourceText + options.configString);
  },
};

// jest.config.js
module.exports = {
  transform: {'\\.custom$': '<rootDir>/my-transformer.js'},
};

Transformers can take options via the array form: transform: {'\\.js$': ['babel-jest', {presets: [...]}]}. Use jest-create-cache-key-function to build robust cache keys.

5.2 Custom test environment

An environment provides the global sandbox (global, timers, the module context). Extend the abstract base:

const NodeEnvironment = require('jest-environment-node').default;

class CustomEnvironment extends NodeEnvironment {
  async setup() {
    await super.setup();
    this.global.MY_GLOBAL = await connect();
  }
  async teardown() {
    await this.global.MY_GLOBAL.close();
    await super.teardown();
  }
  handleTestEvent(event, state) { /* circus events */ }
}
module.exports = CustomEnvironment;

Select it with testEnvironment: '<rootDir>/CustomEnvironment.js' or a per-file docblock.

Note

Environment teardown() throwing surfaces as a test-environment error (e.g. "teardown error from custom environment"). Always await super.teardown() last.

5.3 Custom runner

runner swaps the top-level execution strategy (useful for non-test workloads like linting through Jest). The default is jest-runner. A custom runner exposes a class with a runTests method and may declare itself serial or parallel.

5.4 Custom reporter

Reporters receive lifecycle callbacks and render results:

class MyReporter {
  onRunStart(results, options) {}
  onTestStart(test) {}
  onTestResult(test, testResult, aggregatedResult) {}
  onRunComplete(contexts, results) {}
}
module.exports = MyReporter;

// jest.config.js
module.exports = {
  reporters: ['default', ['<rootDir>/MyReporter.js', {verbose: true}]],
};

Built-in reporters include default, the summary reporter, the coverage reporter, the JSON reporter, and a GitHub Actions reporter that emits annotations in CI.

Important

A reporter entry must be a string or a [path, options] tuple. Anything else throws "Reporter at index N must be of type: array or string".

5.5 Custom resolver

resolver replaces module resolution — needed for unusual package layouts, custom conditions, or PnP. It receives a request and options and returns an absolute path.

5.6 Custom test sequencer

testSequencer controls file ordering. The default @jest/test-sequencer runs previously-failed and slowest tests first to surface failures quickly and balance the worker pool. Extend @jest/test-sequencer and override sort/shard.

5.7 Watch plugins

watchPlugins add interactive watch-mode commands (e.g. jest-watch-typeahead). Each plugin can register a key, a prompt, and hooks into the watch run.

6. Multi-Project Configuration

A single Jest invocation can run several configurations using projects. Each entry is a path or an inline config; each gets its own environment, transforms, and roots, while global options (workers, reporters, watch) are shared.

// jest.config.js
module.exports = {
  projects: [
    {
      displayName: 'node',
      testEnvironment: 'node',
      testMatch: ['<rootDir>/packages/**/*.test.ts'],
    },
    {
      displayName: 'dom',
      testEnvironment: 'jsdom',
      testMatch: ['<rootDir>/ui/**/*.test.tsx'],
    },
  ],
};

Run or skip individual projects from the CLI:

jest --selectProjects node
jest --ignoreProjects dom

Warning

Two projects must not resolve to the same config path. Jest aborts with "Whoops! Two projects resolved to the same config path" — usually caused by a projects glob that includes a directory with no Jest config.

7. CI Integration

7.1 CI mode

Jest auto-detects CI via the ci-info package and most CI providers set CI=true. In CI mode, Jest refuses to write new snapshots so a missing/obsolete snapshot fails the build rather than silently passing. Force it with --ci.

jest --ci --coverage --reporters=default --reporters=jest-junit

7.2 Sharding across machines

For large suites, split the run across parallel CI jobs with --shard:

# job 1 of 4
jest --shard=1/4
# job 2 of 4
jest --shard=2/4

Each shard runs a deterministic, disjoint subset. Combine coverage afterward with a merge step (e.g. nyc merge / istanbul).

7.3 Recommended CI invocation

jest --ci \
     --runInBand=false \
     --maxWorkers=2 \
     --coverage \
     --coverageReporters=lcov --coverageReporters=text-summary \
     --reporters=default --reporters=github-actions

Tip

On constrained CI runners, an explicit --maxWorkers=2 (or a low percentage) often beats the default 50% because CI containers frequently misreport CPU count. Measure both.

Caution

The JEST_WORKER_ID environment variable is set by Jest inside each worker (starting at 1). Use it to give each worker an isolated resource (e.g. a database schema test_db_${JEST_WORKER_ID}) and avoid cross-worker collisions.

8. Performance Tuning

Note

maxWorkers accepts a percentage. getMaxWorkers resolves "50%" to floor(0.5 × CPUs) (minimum 1). In watch mode Jest deliberately uses about half the CPUs to stay responsive.

Important

--detectOpenHandles implies --runInBand and is slow — use it to diagnose, not in normal runs. --detectLeaks is explicitly experimental and can produce false positives.

9. ECMAScript Modules (ESM)

Jest supports native ESM with caveats. Enable it by:

1. Running Node with the VM-modules flag:

   node --experimental-vm-modules node_modules/jest/bin/jest.js
   

2. Marking files as ESM — via "type": "module" in package.json, a .mjs extension, or extensionsToTreatAsEsm:

   // jest.config.js
   module.exports = {extensionsToTreatAsEsm: ['.ts']};
   

Inside ESM tests, the jest object is imported rather than global:

import {jest} from '@jest/globals';

Warning

Native ESM support is still evolving. Mixed CJS/ESM graphs, named imports from CommonJS, and some transform interop edge cases remain rough. If you hit "can't import named imports from cjs modules", prefer default imports or a transform that produces interop shims.

10. Security Considerations

Jest executes your test code (and the modules it imports) with full Node.js privileges. Treat it as you would any code-execution tool.

• Untrusted code: Never run Jest over test files or node_modules you do not trust. globalSetup, setupFiles, transformers, reporters, resolvers, and environments are all arbitrary modules executed by Jest.
• Environment variables: Jest sets NODE_ENV=test if unset. babel-jest reads BABEL_ENV/NODE_ENV. Avoid leaking secrets into test logs (--silent suppresses console output).
• No network sandbox: The node environment has unrestricted network/filesystem access. Mock external calls; do not let tests hit production services.
• Snapshot review: Snapshots are committed code. Review snapshot diffs in PRs — a malicious or accidental snapshot update can mask a regression.
• Coverage of secrets: collectCoverageFrom globs can pull files into reports; ensure config/secret files are excluded via coveragePathIgnorePatterns.

Caution

Custom transformers and environments run before your test code and can read anything the Node process can. Pin and audit third-party Jest plugins like any other dependency.

11. Operations & Internal Troubleshooting

Diagnosing a stuck or non-exiting run

jest --detectOpenHandles --runInBand

Surfaces timers, sockets, and handles left open. Pair with teardown hooks. If Jest still hangs, --forceExit is a blunt last resort (it masks the underlying leak).

Inspecting resolved configuration

jest --showConfig

Prints the fully-merged GlobalConfig and per-project ProjectConfig — the ground truth for "why is Jest doing X". --debug prints a smaller diagnostic subset.

Clearing a corrupt cache

jest --clearCache

Deletes the configured cache directory. Do this after upgrading Jest or changing transform config if you see stale-transform symptoms.

Common internal errors

Memory growth across runs

Reported for some Jest 29→30 upgrades (issue #15743). Mitigations: --workerIdleMemoryLimit to recycle heavy workers, --logHeapUsage to find the offending suite, drop large globals in afterEach, and consider --runInBand to isolate.

12. Building & Contributing

Jest is a Yarn-workspaces monorepo. The published jest binary is node ./packages/jest-cli/bin/jest.js.

# clone and install
git clone https://github.com/jestjs/jest
cd jest
yarn

# build all packages (TypeScript → CommonJS + d.ts)
yarn build

# run Jest's own test suite
yarn jest

# type-check
yarn typecheck

Note

Each package compiles independently. The typecheck:tests script type-checks a curated set of package test trees. When adding a public API, update both the implementation and the jest-types definitions so consumers get correct typings.

13. Quick Reference

Default values at a glance

Config file precedence

1. --config <path|json> (CLI)
2. jest.config.{js,ts,mjs,mts,cjs,cts,json}
3. jest key in package.json

Key environment variables