Jest

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Jest is attempting to run ES modules in a CommonJS context without proper configuration.
  fix Ensure your `package.json` has `"type": "module"` or configure Babel/TypeScript to transpile ES modules, and Jest to recognize your test files as modules.

• ReferenceError: describe is not defined

  cause Jest's global test functions (describe, it, expect) are not available in the current scope.
  fix Ensure Jest is correctly installed and configured, and that you're running your tests via the `jest` command (e.g., `npx jest`) rather than executing test files directly.

• Jest encountered an unexpected token '<' (or similar)

  cause Jest's transformer (often Babel or ts-jest) is not correctly configured to process modern JavaScript syntax, TypeScript, or JSX/TSX.
  fix Verify your `jest.config.js` includes the correct `transform` configuration for your project's syntax, e.g., `'^.+\.(ts|tsx)$': 'ts-jest'` or a Babel setup.

• Error: Jest: a "jest-environment-jsdom" package is required

  cause Your Jest configuration specifies `testEnvironment: 'jsdom'` but the `jest-environment-jsdom` package is not installed.
  fix Install the required environment: `npm install --save-dev jest-environment-jsdom` or `yarn add --dev jest-environment-jsdom`.

• Cannot find module './my-module' from 'my-test.js'

  cause Jest's module resolver cannot find a specified module, often due to custom path aliases or non-standard module locations.
  fix Configure `moduleNameMapper` in your `jest.config.js` to map module paths, especially for aliases (e.g., `"^@/(.*)$": "<rootDir>/src/$1"`).

Warnings

• breaking Jest v30.0.0 is a major release after three years, introducing a substantial number of changes that may require following the migration guide for existing projects.
  Fix: Consult the official migration guide for Jest 30.0.0 to update your configuration and tests.
• breaking Jest 30 requires Node.js v18.14.0, v20.0.0, v22.0.0, or >=v24.0.0. Older Node.js versions are no longer supported.
  Fix: Upgrade your Node.js environment to a supported version (e.g., using `nvm install 20` and `nvm use 20`).
• breaking The `jest-runner` package was deprecated and removed starting from Jest 30.0.1.
  Fix: If your project explicitly depended on `jest-runner`, review your setup to remove direct dependencies or migrate to alternative runner configurations if necessary.
• gotcha Previously, `unstable_mockModule` could have issues when attempting to mock `node:` prefixed core modules.
  Fix: Ensure you are using Jest v30.1.3 or newer to properly mock Node.js built-in modules with `unstable_mockModule`.

Install

• npm install jest npm
• yarn add jest yarn
• pnpm add jest pnpm

Imports

• defineConfig

  import { defineConfig } from 'jest';

• expect

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

Quickstart

This example shows a simple TypeScript function and its corresponding test using Jest's `describe` and `it` blocks with `expect` assertions.

// sum.ts
export function sum(a: number, b: number): number {
  return a + b;
}

// sum.test.ts
import { sum } from './sum';

describe('sum', () => {
  it('adds 1 + 2 to equal 3', () => {
    expect(sum(1, 2)).toBe(3);
  });
});

// To run: `npx jest sum.test.ts`