jestjs/jest
github.com/jestjs/jest ↗ · 3401 files · 9.6 MB
🃏 Delightful JavaScript Testing 👩🏻💻 Developer Ready: A comprehensive JavaScript testing solution.
Overview
Jest is a JavaScript testing platform for application and library developers, combining test discovery, parallel execution, assertions, mocking, coverage, snapshots, and interactive watch mode. At commit 61050e9323e742539dc2360236671110e37329e6, its TypeScript packages separate orchestration from per-file environments, module loading, and test-framework execution; the runtime includes both asynchronous ESM loading and capability-gated synchronous require(esm). This brief follows CLI execution, module loading, and snapshot persistence through source and tests, with a bounded inspection of the separate Docusaurus website and repository automation.
System map
The executable product is a collection of Node packages with a CLI and programmatic orchestration API. Configuration and file indexing establish project contexts before runners execute individual test files in configured environments. Persistence consists of filesystem caches, snapshots, and report artifacts. The documentation website has its own build and deployment boundary.
- The private root workspace includes packages, website, and examples, pins yarn@4.18.0, and declares Node support as ^18.14.0 || ^20.0.0 || ^22.0.0 || >=24.0.0.
- The jest-cli package exposes the jest executable and CJS/ESM package exports; bin/jest.js delegates to import-local before invoking run().
- runCLI is the orchestration boundary: it loads configurations, selects projects, builds Haste contexts, and branches into watch or one-shot execution.
- TestScheduler loads configured runners, partitions tests by runner path and runnerOptions, and determines serial execution using shouldRunInBand or runner.isSerial.
- jest-runner executes files directly in serial mode or through a jest-worker pool with optional worker threads, serialized resolver maps, piped output, and explicit worker cleanup.
- Runtime composes ModuleRegistries, Resolution, MockState, TransformCache, JestGlobals, EsmLoader, ModuleExecutor, and CjsLoader for each test-file execution.
- The build script bundles packages with Webpack and generates .mjs wrappers from CJS exports; yarn build additionally builds and bundles declarations, while Lerna tracks package version 30.5.2.
- The website uses Docusaurus and React, reads documentation from ../docs, fetches Open Collective supporter data, and publishes website/build through Netlify production or preview commands.
Feature catalog
The inspected user surface spans test selection, execution, assertions, mocks, snapshots, coverage, and diagnostic output. Selection can operate on paths, dependency relationships, project names, cached failures, or sequencer shards. Watch mode and declaration collection provide different workflows over the same orchestration machinery. The catalog groups related APIs and options rather than claiming an exhaustive listing of every matcher or flag.
- Test selection supports roots, testMatch, testRegex, ignore patterns, direct paths, related source files, and onlyChanged dependency selection; CLI project selection also supports selectProjects and ignoreProjects.
- runJest supports sequencer-based sharding, sorting, and onlyFailures selection; --listTests emits unique selected file paths as text or JSON, optionally to outputFile.
- --collectTests schedules files with silent output, disabled coverage, and an empty reporter list, then returns declaration trees or JSON; Circus loads setup and test modules before skipping test-body execution.
- Watch mode loads built-in and third-party plugins, reacts to Haste file changes, reruns tests, emits completion hooks, and retains failed test results for subsequent selection.
- expect(actual) constructs ordinary, negated, resolves, and rejects matcher surfaces; expect.extend and addEqualityTesters register custom behavior alongside built-in assertion, spy, and throw matchers.
- Mock APIs include fn, method/accessor spyOn, replaceProperty, module mock dispatch, and module isolation; clearAllMocks, resetAllMocks, and restoreAllMocks have distinct state-reset operations.
- Snapshot APIs support external and inline matching, custom serializers, and custom path resolvers; update modes control additions, replacements, obsolete-key removal, and empty-file deletion.
- Execution supports per-file environment docblocks, setup hooks, globally enabled fake timers, and V8 coverage; output options include default/verbose, agent, GitHub Actions, summary, custom, coverage, notification, and JSON reporting.
Data flow
Arguments and configuration enter through separate parsing and normalization stages before becoming execution settings. Indexed files and dependency relationships become selected Test objects, which runners consume locally or across worker boundaries. Per-file Runtime objects own module and transform state, while snapshot state owns assertion persistence. Results flow back into aggregation, sequencing caches, reporters, and optional JSON files.
- buildArgv parses process arguments through the args option table and check function, validates CLI options, removes dashed duplicate keys, and passes normalized argv plus project paths to runCLI.
- readConfig calls readInitialOptions, normalize, and groupOptions; inline JSON --config receives a default rootDir, while configuration files resolve relative rootDir against their containing directory.
- HasteMap.build converts crawled file data into HasteFS and HasteModuleMap, persisting rebuilt maps when changes are unknown or files changed; CLI context construction consumes the completed map.
- SearchSource resolves inverse dependencies for related-test selection and intersects custom filter results with already discovered tests; invalid filter output without a filtered array raises TypeError.
- Parallel execution serializes each project's module map and converts changed-file Sets into arrays; worker calls receive project/global configuration and a test path, then emit file success or failure events.
- runTestInternal seeds cacheFS with test source and constructs Runtime; ModuleExecutor transforms and compiles loaded JS, while ScriptTransformer reads cached code or invokes a configured transformer and writes cache artifacts.
- Snapshot matcher context supplies test name and identity to SnapshotState.match; serialized received values update state under the selected update mode, and save writes external snapshot files or rewrites inline source files.
- Completed TestResults determine aggregate success, populate sequencer failure/timing caches, and optionally pass through testResultsProcessor before formatted JSON reaches stdout or a cwd-resolved outputFile.
Behavior traces
Three concrete flows were followed through implementation: CLI startup and execution, module loading, and snapshot persistence. The execution trace includes the distinction between suite runners and the in-environment framework. Module loading branches on mocks, registry state, file type, and VM capabilities. Snapshot persistence includes retry rollback and cleanup of unchecked keys.
- Startup: bin/jest.js first attempts importLocal; otherwise it defaults NODE_ENV to test, calls run(), then buildArgv → getProjectListFromCLIArgs → runCLI → readConfigs.
- One-shot orchestration: runCLI → _run10000 → buildContextsAndHasteMaps; each project creates a cache directory, calls Runtime.createHasteMap().build(), and constructs a context before runWithoutWatch.
- Primary execution: runJest selects tests, shards before sorting, applies onlyFailures, runs globalSetup, schedules tests, caches results, runs globalTeardown, then processes results; listTests and collectTests return through earlier branches.
- Per-file execution: runTest → runTestInternal reads source/docblocks, loads environment and framework, constructs Runtime, executes setupFiles, calls environment.setup(), then invokes testFramework; runtime and environment teardown occur on the guarded completion path.
- Circus execution: jestAdapter loads jestAdapterInit through requireInternalModule, calls initialize, registers reset/mock cleanup in beforeEach, loads setupFilesAfterEnv and the test module, then calls runAndTransformResultsToJestFormat → run.
- CJS loading: Runtime.requireModuleOrMock checks teardown and mock decisions, then dispatches to a mock, framework singleton, or requireModule; CjsLoader resolves paths, returns registry hits, pre-registers fresh modules for cycles, and removes failed loads.
- ESM loading: EsmLoader.loadAndEvaluate resolves an ESM path, calls loadEsmModule, then linkAndEvaluateModule; synchronous loading requires VM and resolver capabilities, while the asynchronous path links imports, validates attributes, and shares evaluation promises.
- Snapshot persistence: initialize resolves the snapshot path and constructs SnapshotState; _toMatchSnapshot calls match, retry events call clear(test), and jestAdapter's _addSnapshotData protects failed/skipped tests, removes eligible unchecked keys, calls save, and transfers counters into TestResult.
Testing signals
Tests and CI definitions were inspected, not executed; no passing result or measured coverage is asserted. The repository tests itself with Jest, using package-level tests, subprocess-based e2e drivers, and separate type checks. Inspected tests exercise collection semantics, CJS dispatch, and snapshot retry persistence, with explicit runner-specific conditions. This is a bounded inventory of evidence, not exhaustive coverage.
- The main suite transforms JS/TS with babel-jest, includes root and example projects, and excludes fixture directories from direct discovery; root scripts expose focused Jest, coverage, Jasmine, VM-module, and type-test commands.
- Package unit tests live under __tests__, while e2e/__tests__ drivers execute fixture projects; e2e/runJest.ts launches the repository CLI with process.execPath and asserts captured subprocess results.
- CjsLoader unit tests stub resolution, registries, and execution, checking core-module routing, cached exports without re-execution, manual mock selection, and recursion avoidance; these tests alone do not establish real VM integration.
- Collection e2e tests assert tree/JSON output, wouldRun flags, load-error reporting, no test-body execution, and parity with focused execution; test.failing parity cases explicitly skip Jasmine.
- SnapshotState tests use temporary files to check retry rollback, preservation of other tests' inline/file writes, and no write after complete rollback; another test records the hint-separator ownership ambiguity.
- Retry e2e tests inspect beforeAll describe recovery, snapshot restoration, and concurrent describe retries, but the entire inspected retry suite calls skipSuiteOnJasmine.
- Node CI invokes sharded Ubuntu, macOS, and Windows jobs across Node 18/20/22/24/25/26; test jobs build JavaScript and use retries with three attempts and ten-minute timeouts, while separate jobs cover declarations, lint, VM modules, Watchman, and coverage.
- Coverage collection excludes bin, cli, e2e, tests, builds, and vendor paths; TypeScript integration uses a separate configuration, and CI reporting emits JSON coverage plus GitHub Actions, JUnit, silent, and summary reports. These inspected definitions do not prove execution or comprehensive behavioral coverage.
Risk map
The following risks are source observations and maintenance limits, not confirmed vulnerabilities. Jest deliberately executes project code and extensibility modules, so configuration and snapshot inputs carry executable authority. Filesystem outputs and worker execution cross the repository-root boundary. Source comments and tests expose specific cache, validation, and ownership limitations without establishing their frequency in practice.
- getSnapshotData executes snapshot contents with new Function('exports', snapshotContents) before header validation and swallows evaluation errors; snapshot files must therefore be treated as executable trusted project inputs.
- Configuration files can execute modules or async exported functions, and orchestration loads custom filter/reporting modules; these paths run before or outside individual test bodies.
- --clearCache recursively removes configured cache directories, outputFile resolves against cwd and is written directly, and inline snapshots rewrite paths derived from captured stack frames; these operations are not confined by a repository-root check in the inspected functions.
- The VM environment is not a complete security boundary: CjsLoader routes core modules through CoreModuleProvider and loads .node files with native require, while runTest wraps process.exit for diagnostics and still calls the real exit.
- Changed-file detection launches Git subprocesses with project cwd and argument arrays; parallel runners cross process/thread boundaries with serialized configuration and module maps and can force workers to exit during cleanup.
- ScriptTransformer explicitly documents that independently cached code and source maps can become mismatched under concurrent writes; code checksums and atomic writes protect code artifacts but do not establish code/map pairing.
- Snapshot ownership has known compatibility limits: clear() without identity does not roll back file data or unchecked keys, and keys using ': ' cannot distinguish a hint from a longer test name, potentially retaining obsolete snapshots.
- Configuration normalization validates before preset merging, with a TODO stating preset-contributed options escape that validation; multiple projects without explicit --config also inherit global settings from the first project's configuration as a documented compatibility fallback.
Extension points
Jest exposes extension seams at configuration, discovery, execution, module resolution, transformation, assertion, snapshot, and reporting boundaries. Most external implementations are loaded by configured module paths rather than a centralized plugin registry. Several seams carry distinct synchronous and asynchronous contracts. Runtime composition also preserves public dispatch callbacks for alternate runtime implementations.
- CLI options are declared in args.options and checked by args.check before validateCLIOptions; configuration normalization merges argv and presets, making flag additions a coordinated CLI/configuration change.
- Configured transformer modules may export a transformer or createTransformer factory; loadTransformers validates process/processAsync and stores implementations by pattern and module path.
- Custom resolver modules can be functions or objects with sync and async hooks, receiving basedir, conditions, extensions, paths, rootDir, and default resolver helpers; synchronous require(esm) rejects an async-only resolver.
- Configured runners are instantiated with globalConfig, change context, and runnerOptions; per-file environment, framework, and optional runtime modules are independently loaded by runTestInternal.
- Custom testSequencer implementations supply sort and cacheResults, with shard required when sharding is requested; discovery filters expose optional async setup and return a filtered path array.
- Watch plugins receive config/stdin/stdout, can apply hook subscriptions, and are checked for key conflicts; custom reporters receive globalConfig/options/context, while testResultsProcessor can asynchronously replace aggregate results.
- Assertion extensions use expect.extend and addEqualityTesters; snapshot serializers prepend to the plugin list, and custom snapshot resolvers must implement both path transforms plus a round-trip consistency example.
- Runtime supplies public-method callbacks to RequireBuilder, EsmLoader, and JestGlobals rather than directly binding all internal loaders; repository guidance explicitly identifies requireModule and related methods as subclass override seams.
Contributor handoff
Tests and CI were inspected, not executed, and this brief does not certify a passing checkout. Start from the relevant package source and preserve contracts at configuration, Runtime, runner, and persistence boundaries. Small focused changes must account for cross-package imports loading built artifacts and for separately checked declarations. Future execution requires authorization appropriate to that task; this investigation performed only source reads and searches.
- Read root/package manifests, jest.config.mjs, and the implementing package first; build exports point to build artifacts, while root scripts distinguish JavaScript bundling, declaration build, and declaration bundling.
- For an authorized change, use the existing yarn jest <path> workflow first; rebuild JavaScript when e2e or other workspaces consume the edit, and use the full build when declarations or cross-package type checks change.
- Runtime edits must retain public dispatch seams and capability conditions; nodeCapabilities detects SyntheticModule and SourceTextModule.prototype.hasAsyncGraph, while ESM loading also checks resolver capabilities.
- Preserve runTestInternal as a separate closure for leak detection and keep runtime teardown before environment teardown; its setupFiles execution occurs before the later guarded framework-execution block.
- Snapshot edits should read State, matcher dispatch, adapter persistence, and snapshot utilities together; preserve identity-based retry rollback and the CI normalization that selects none unless updateSnapshot is explicitly requested.
- Add e2e behavior through fixture files rather than jest.fn/mock/spyOn in driver tests; the subprocess helper strips agent-detection variables and disables colors, so output assertions depend on that controlled environment.
- Follow strict TypeScript and repository formatting constraints, use graceful-fs/globalThis in the governed source, and preserve bare built-in imports in browser-compatible packages where node: imports are explicitly prohibited.
- Tests and CI were inspected, not executed: future validation should select the relevant existing package/e2e/type scripts and report actual results. Keep release/deployment separate because pkg-pr-new publishes packages and website production preparation performs supporter fetches and Crowdin upload/download.
Languages
| Language | Files | Share of source |
|---|---|---|
| JavaScript | 1298 | 57% |
| TypeScript | 963 | 43% |
| JSON | 550 | docs/config |
| Markdown | 275 | docs/config |
| YAML | 23 | docs/config |
| CSS | 11 | docs/config |
| Sass | 1 | 0% |
| Shell | 1 | 0% |
Start reading here
Probable source entrypoint: packages/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
packages/ (1388 files)
Repository structure
| Top-level path | Files |
|---|---|
e2e/ | 1567 |
packages/ | 1388 |
website/ | 222 |
examples/ | 105 |
docs/ | 38 |
.github/ | 22 |
scripts/ | 15 |
benchmarks/ | 5 |
Docs found: CLAUDE.mdCONTRIBUTING.mdREADME.mddocs/Architecture.mddocs/BypassingModuleMocks.mddocs/CLI.mddocs/CodeTransformation.mddocs/Configuration.mddocs/DynamoDB.mddocs/ECMAScriptModules.md
Package
package.json — @jest/monorepo v0.0.0, 78 declared dependencies.
@babel/core@babel/plugin-transform-modules-commonjs@babel/preset-env@babel/preset-react@babel/preset-typescript@babel/register@crowdin/cli@eslint-community/eslint-plugin-eslint-comments@eslint/js@eslint/markdown@jest/globals@jest/test-utils
CI & config entrypoints
README.md— Repository readmeCLAUDE.md— Claude instructions.github/workflows/prepare-cache.yml— GitHub Actions workflow.github/workflows/pkg-pr-new.yml— GitHub Actions workflow.github/workflows/nodejs.yml— GitHub Actions workflow.github/workflows/nightly.yml— GitHub Actions workflow.github/workflows/test.yml— GitHub Actions workflow.github/workflows/require-changelog.yml— GitHub Actions workflow.github/workflows/check-changelog.yml— GitHub Actions workflow.github/workflows/issues.yml— GitHub Actions workflow
Structural health signals
Average score 7.2/10 across 96 analyzed source files; 22 hotspots surfaced.
packages/jest-reporters/src/CoverageReporter.ts— 548 lines, score 4.5 (Large file, Deep nesting)packages/jest-core/src/__tests__/watch.test.js— 1031 lines, score 5 (Large file, Deep nesting)packages/jest-haste-map/src/crawlers/__tests__/node.test.js— 468 lines, score 5.2 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
61050e9323e72026-10-02 — chore(deps): update dependency eslint-plugin-jsdoc to v65 (#16480)202dd8a147772026-09-18 — v30.5.215c3d19dc2802026-09-18 — chore: prepare for v30.5.2f2e2aa285f002026-09-18 — chore(deps): lock file maintenance (#16410)4685157f782c2026-09-18 — chore: update ts-eslint (#16440)