jest

library1.0.0jsnpmunverified

Jest is a popular and delightful JavaScript testing framework known for its simplicity and comprehensive features, widely adopted for testing React, Vue, Angular, Node.js, and other JavaScript projects. The current stable version is 30.3.0. While major releases historically had long gaps (v30 came three years after v29), the project aims for more frequent major releases moving forward. Key differentiators include its "zero-config" setup for many projects, powerful snapshot testing capabilities for UI and data structures, an interactive watch mode for efficient TDD, built-in code coverage reporting, and a rich ecosystem of matchers and extensions. It ships with a custom JSDOM environment for browser-like testing in Node.js, making it suitable for front-end applications.

testing

npm install jest

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JEST

jest

testingjavascriptv1.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

expect, test, describe

✓ import { expect, test, describe } from '@jest/globals';

✗ import { expect, test, describe } from 'jest';

Jest provides these functions globally in test files, so explicit imports are optional but recommended for TypeScript and clear dependency management. `@jest/globals` is the correct explicit import path for type inference.

jest

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

The `jest` global object for mocking, spying, and controlling test environment. Explicitly importing it is good practice, especially in TypeScript.

defineConfig

✓ import { defineConfig } from 'jest-config';

✗ import type { Config } from '@jest/types'; const config: Config = { /* ... */ };

A type helper added in v30.3.0 to provide type-safe Jest configuration directly in `jest.config.ts` or `jest.config.js`. It's preferred over direct type assertion for configurations.

Config.InitialOptions

✓ import type { Config } from '@jest/types'; const jestConfig: Config.InitialOptions = { /* ... */ };

For type-checking Jest configuration objects directly. Note the use of `type` keyword for importing only types. Consider `defineConfig` for most configuration files.

Demonstrates a basic Jest test suite for a utility function, including setup with `describe` and `test`, using `expect` matchers, and a simple example of `jest.mock` for dependency mocking.

import { add } from './src/utils/add'; describe('add function', () => { test('should correctly add two positive numbers', () => { expect(add(2, 3)).toBe(5); }); test('should correctly add a positive and a negative number', () => { expect(add(5, -3)).toBe(2); }); test('should handle zero correctly', () => { expect(add(0, 0)).toBe(0); expect(add(0, 7)).toBe(7); }); test('should mock a dependency correctly', () => { const mockSubtract = jest.fn(() => 10); jest.mock('./src/utils/subtract', () => ({ subtract: mockSubtract, })); const { subtract } = require('./src/utils/subtract'); // Needs require for hoisted mock subtract(); expect(mockSubtract).toHaveBeenCalledTimes(1); expect(subtract()).toBe(10); }); }); // --- File: src/utils/add.ts --- export function add(a: number, b: number): number { return a + b; } // --- File: src/utils/subtract.ts --- export function subtract(a: number, b: number): number { return a - b; }

jest --version

Debug

Known issues

breakingJest 30 drops support for Node.js versions 14, 16, 19, and 21. The minimum supported Node.js version is now 18.x.

fix

Ensure your development and CI environments use Node.js version 18.14.0 or higher.

affects: >=30.0.0

breakingJest 30 removed several deprecated `expect` matcher aliases (e.g., `toBeCalled` is now `toHaveBeenCalled`). Using these aliases will result in test failures.

fix

Update deprecated matcher names to their canonical forms (e.g., `toBeCalled()` to `toHaveBeenCalled()`). An ESLint plugin with autofixers (`eslint-plugin-jest`) or codemods like `jest30-matcher-upgrade` can automate this.

affects: >=30.0.0

breakingThe minimum compatible TypeScript version is now 5.4. Older TypeScript versions may cause compilation errors or type mismatches with Jest 30.

fix

Upgrade your project's TypeScript dependency to version 5.4 or newer.

affects: >=30.0.0

breakingJest 30 bundles itself into a single file per package for performance, which may break tools or setups that rely on reaching into Jest's internal modules (e.g., `require('jest-runner/build/testWorker')`).

fix

Migrate to using only Jest's public APIs and documented interfaces. If you were using internal modules, check if a public alternative exists or open an issue/PR to request one.

affects: >=30.0.0

gotchaWhen using `jest.mock()` for modules, ensure that the module under test is `require()`'d *after* `jest.mock()` has been called to ensure the mock is applied. Jest hoists `jest.mock()` calls, but not imports of the module being mocked if they occur before the mock.

fix

For modules with dynamic mocks, wrap the module import in a function that is called after `jest.mock()`, or use `require()` for the module under test if `jest.mock()` is defined after top-level `import` statements.

affects: >=24.0.0

gotchaPerformance can be significantly slower on Windows due to slower file system crawling. This is particularly noticeable in large projects or monorepos.

fix

Consider running tests within Windows Subsystem for Linux (WSL2) for improved performance on Windows machines. Optimize module imports to avoid large 'barrel files' that cause Jest to load unnecessary dependencies.

affects: >=20.0.0

Errors

Common errors & fixes

ReferenceError: expect is not defined

`expect` (and `test`, `describe`) are not globally available or explicitly imported in a non-Jest context.

fix

Ensure your test file is executed by Jest, and if using TypeScript or explicit imports, add `import { expect, test, describe } from '@jest/globals';` to the top of your test file.

SyntaxError: Cannot use import statement outside a module

Attempting to use ES Modules (`import`/`export`) in a CommonJS (`require`/`module.exports`) environment, or vice-versa, without proper configuration.

fix

If your project uses ES Modules, ensure your `package.json` has `"type": "module"` and configure Jest to handle ESM, potentially with a Babel or `ts-jest` setup that targets ESM. If using CJS, stick to `require()` syntax or configure Jest to transpile ESM to CJS.

Error: Jest: a test should not return a Promise. (See https://jestjs.io/docs/en/asynchronous)

An asynchronous test function returns a promise but doesn't properly signal Jest to wait for it, or mixes `async/await` with a `done` callback.

fix

For `async/await` tests, simply mark the `test` callback as `async`. For promise-based tests, return the promise. Avoid mixing `done` with `async/await` or returning promises.

jest.mock() must be called out of a describe block.

`jest.mock` calls are hoisted by Babel, but only if they are in the top scope of a module or directly within a `describe` block. Nesting them deeper prevents hoisting.

fix

Move `jest.mock()` calls to the top-level of your test file or immediately inside `describe` blocks to allow Jest's auto-hoisting mechanism to work correctly.

Configuration error: Cannot find module 'ts-jest'

The `ts-jest` transformer is specified in `jest.config.js` but `ts-jest` is not installed or incorrectly configured.

fix

Install `ts-jest` as a dev dependency (`npm install --save-dev ts-jest`) and ensure your Jest config's `preset` or `transform` property correctly points to `ts-jest`.

Upgrade

Version history

1.0.0latest on npm

Audit

Dependencies

node-notifieroptionalPeer dependency for desktop notifications during test runs.

ts-jestoptionalRequired for transforming TypeScript files in Jest, enabling testing of TypeScript projects without prior compilation.

@types/jestoptionalProvides TypeScript type definitions for Jest globals and API. While Jest ships its own types with `@jest/globals` since v29, `@types/jest` is still common, especially for older setups.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/jestjs/jest ↗

packagehttps://www.npmjs.com/package/jest ↗

homepagehttps://jestjs.io ↗