{"id":10396,"library":"jest","title":"Jest Testing Framework","description":"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.","status":"active","version":"30.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/jestjs/jest","tags":["javascript","ava","babel","coverage","easy","expect","facebook","immersive","instant","typescript"],"install":[{"cmd":"npm install jest","lang":"bash","label":"npm"},{"cmd":"yarn add jest","lang":"bash","label":"yarn"},{"cmd":"pnpm add jest","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for desktop notifications during test runs.","package":"node-notifier","optional":true},{"reason":"Required for transforming TypeScript files in Jest, enabling testing of TypeScript projects without prior compilation.","package":"ts-jest","optional":true},{"reason":"Provides 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.","package":"@types/jest","optional":true}],"imports":[{"note":"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.","wrong":"import { expect, test, describe } from 'jest';","symbol":"expect, test, describe","correct":"import { expect, test, describe } from '@jest/globals';"},{"note":"The `jest` global object for mocking, spying, and controlling test environment. Explicitly importing it is good practice, especially in TypeScript.","symbol":"jest","correct":"import { jest } from '@jest/globals';"},{"note":"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.","wrong":"import type { Config } from '@jest/types'; const config: Config = { /* ... */ };","symbol":"defineConfig","correct":"import { defineConfig } from 'jest-config';"},{"note":"For type-checking Jest configuration objects directly. Note the use of `type` keyword for importing only types. Consider `defineConfig` for most configuration files.","symbol":"Config.InitialOptions","correct":"import type { Config } from '@jest/types'; const jestConfig: Config.InitialOptions = { /* ... */ };"}],"quickstart":{"code":"import { add } from './src/utils/add';\n\ndescribe('add function', () => {\n  test('should correctly add two positive numbers', () => {\n    expect(add(2, 3)).toBe(5);\n  });\n\n  test('should correctly add a positive and a negative number', () => {\n    expect(add(5, -3)).toBe(2);\n  });\n\n  test('should handle zero correctly', () => {\n    expect(add(0, 0)).toBe(0);\n    expect(add(0, 7)).toBe(7);\n  });\n\n  test('should mock a dependency correctly', () => {\n    const mockSubtract = jest.fn(() => 10);\n    jest.mock('./src/utils/subtract', () => ({\n      subtract: mockSubtract,\n    }));\n\n    const { subtract } = require('./src/utils/subtract'); // Needs require for hoisted mock\n    subtract();\n    expect(mockSubtract).toHaveBeenCalledTimes(1);\n    expect(subtract()).toBe(10);\n  });\n});\n\n// --- File: src/utils/add.ts ---\nexport function add(a: number, b: number): number {\n  return a + b;\n}\n\n// --- File: src/utils/subtract.ts ---\nexport function subtract(a: number, b: number): number {\n  return a - b;\n}","lang":"typescript","description":"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."},"warnings":[{"fix":"Ensure your development and CI environments use Node.js version 18.14.0 or higher.","message":"Jest 30 drops support for Node.js versions 14, 16, 19, and 21. The minimum supported Node.js version is now 18.x.","severity":"breaking","affected_versions":">=30.0.0"},{"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.","message":"Jest 30 removed several deprecated `expect` matcher aliases (e.g., `toBeCalled` is now `toHaveBeenCalled`). Using these aliases will result in test failures.","severity":"breaking","affected_versions":">=30.0.0"},{"fix":"Upgrade your project's TypeScript dependency to version 5.4 or newer.","message":"The minimum compatible TypeScript version is now 5.4. Older TypeScript versions may cause compilation errors or type mismatches with Jest 30.","severity":"breaking","affected_versions":">=30.0.0"},{"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.","message":"Jest 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')`).","severity":"breaking","affected_versions":">=30.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=24.0.0"},{"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.","message":"Performance can be significantly slower on Windows due to slower file system crawling. This is particularly noticeable in large projects or monorepos.","severity":"gotcha","affected_versions":">=20.0.0"}],"env_vars":null,"search_vec":"'30.3.0':37 'adopt':21 'aim':53 'angular':26 'applic':123 'ava':125 'babel':126 'browser':111 'browser-lik':110 'built':89 'built-in':88 'came':46 'capabl':75 'code':91 'comprehens':18 'config':67 'coverag':92,127 'current':33 'custom':106 'data':79 'delight':9 'differenti':62 'easi':128 'ecosystem':97 'effici':86 'end':122 'environ':108 'expect':129 'extens':101 'facebook':130 'featur':19 'forward':60 'framework':3,12 'frequent':56 'front':121 'front-end':120 'gap':44 'histor':41 'immers':131 'includ':63 'instant':132 'interact':82 'javascript':10,30,124 'jest':1,4 'jsdom':107 'key':61 'known':13 'like':112 'long':43 'major':39,57 'make':116 'mani':70 'matcher':99 'mode':84 'move':59 'node.js':27,115 'popular':7 'power':72 'project':31,52,71 'react':24 'releas':40,58 'report':93 'rich':96 'setup':68 'ship':103 'simplic':16 'snapshot':73 'stabl':34 'structur':80 'suitabl':118 'tdd':87 'test':2,11,23,74,113 'three':47 'typescript':133 'ui':77 'v29':50 'v30':45 'version':35 'vue':25 'watch':83 'wide':20 'year':48 'zero':66 'zero-config':65","created_at":"2026-04-18T08:58:36.044513+00:00","updated_at":"2026-04-19T05:46:53.368846+00:00","problems":[{"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.","cause":"`expect` (and `test`, `describe`) are not globally available or explicitly imported in a non-Jest context.","error":"ReferenceError: expect is not defined"},{"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.","cause":"Attempting to use ES Modules (`import`/`export`) in a CommonJS (`require`/`module.exports`) environment, or vice-versa, without proper configuration.","error":"SyntaxError: Cannot use import statement outside a module"},{"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.","cause":"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.","error":"Error: Jest: a test should not return a Promise. (See https://jestjs.io/docs/en/asynchronous)"},{"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.","cause":"`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.","error":"jest.mock() must be called out of a describe block."},{"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`.","cause":"The `ts-jest` transformer is specified in `jest.config.js` but `ts-jest` is not installed or incorrectly configured.","error":"Configuration error: Cannot find module 'ts-jest'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.0.0","cli_name":"jest","cli_version":null,"type":"library","homepage":"https://jestjs.io","github":"https://github.com/jestjs/jest","docs":null,"changelog":null,"pypi":null,"npm":"https://www.npmjs.com/package/jest","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-17","next_check":"2026-07-18","install_tag":null}}