Jest Testing Framework CLI

Common errors

• ReferenceError: test is not defined

  cause Jest's test globals are not available in the current scope. This typically happens if `globals: false` is configured in `jest.config.js` or if you are trying to run a test file without Jest's environment.
  fix Add `import { test, expect, describe } from '@jest/globals';` at the top of your test file, or ensure `globals: true` is set in your Jest configuration file.

• SyntaxError: Cannot use import statement outside a module

  cause This error occurs when Jest tries to process an ES module using CommonJS resolution rules, or vice versa, often due to misconfiguration of `type: 'module'` in `package.json` or incorrect `jest.config.js` settings for module resolution.
  fix Ensure your `jest.config.js` is correctly configured for your project's module system. If your project is ESM, ensure `type: 'module'` in `package.json` and use `jest.config.mjs` or `jest.config.ts` with `defineConfig`. If CJS, use `jest.config.js` and consider `transform` options for ESM imports.

• Your test suite must contain at least one test. (no tests found)

  cause Jest couldn't find any test files matching its `testMatch` or `testRegex` configuration, or the test files themselves do not contain any `test` or `it` blocks.
  fix Verify your `jest.config.js` `testMatch` or `testRegex` patterns are correct (e.g., `**/*.test.ts`, `**/*.spec.js`). Ensure your test files contain actual test definitions using `test('description', () => {...})` or `it('description', () => {...})`.

Warnings

• breaking Jest 30 is a major release with significant internal refactors and changes. While many tests might work without modification, a migration guide is provided, and specific behaviors related to resolvers, runners, and environments may have changed. Always consult the official migration guide when upgrading from Jest 29 or earlier.
  Fix: Review the official Jest 30 migration guide (jestjs.io/docs/upgrading-to-jest30) and adapt test files, configurations, and dependencies as needed. Pay close attention to changes in custom resolvers, environments, or reporters.
• breaking Node.js version requirements have been updated. Jest 30 now requires Node.js version 18.14.0 or higher. Running Jest with older Node.js versions will result in errors.
  Fix: Upgrade your Node.js environment to version 18.14.0, 20.x, 22.x, 24.x or later. Use a tool like `nvm` to manage Node.js versions if necessary.
• deprecated The `jest-runtime` package no longer supports `new Script` and now uses `compileFunction`. While largely an internal change, this might affect projects that heavily customized module loading or relied on specific `new Script` behaviors within their Jest environment.
  Fix: Most users will not need to do anything. If you have highly customized test environments or module loading, verify that your setup still functions correctly. If issues arise, consult the Jest documentation on custom environments or module resolution.
• gotcha Jest's globals (`jest`, `expect`, `test`, `describe` etc.) are enabled by default. If you use ESM or TypeScript and prefer explicit imports for better module hygiene and type inference, you might encounter 'is not defined' errors when `globals: false` is set in your config.
  Fix: Explicitly import globals: `import { test, expect, describe } from '@jest/globals';` in each test file. Alternatively, ensure `globals: true` is set in your Jest configuration file.

Install

• npm install jest-cli npm
• yarn add jest-cli yarn
• pnpm add jest-cli pnpm

Imports

• defineConfig
  wrong:

  const config = require('jest-config').defineConfig;

  correct:

  import { defineConfig } from 'jest-config';

  Introduced in Jest 30.3.0 for type-safe configuration files (e.g., jest.config.ts). This is the recommended way to define Jest configurations when using TypeScript or ESM.
• jest
  wrong:

  import jest from 'jest'; // This imports the CLI, not the globals

  correct:

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

  While `jest` is often available globally in test environments, explicitly importing from `@jest/globals` is recommended for better type safety and clarity, especially in ESM projects or when `globals: false` is set in config.
• expect
  wrong:

  import { expect } from 'jest-expect'; // Not the primary way

  correct:

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

  Similar to `jest`, `expect` is typically available globally. Explicitly importing from `@jest/globals` ensures type inference and is good practice, especially when `globals: false` is configured.

Quickstart

Demonstrates basic Jest test structure using `describe`, `test`, and `expect` with TypeScript, along with setup instructions for a minimal Jest project.

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

function sum(a: number, b: number): number {
  return a + b;
}

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

  test('object assignment', () => {
    const data = { one: 1 };
    data['two'] = 2;
    expect(data).toEqual({ one: 1, two: 2 });
  });

  test('null', () => {
    const n = null;
    expect(n).toBeNull();
    expect(n).toBeDefined();
    expect(n).not.toBeUndefined();
    expect(n).not.toBeTruthy();
    expect(n).toBeFalsy();
  });

  test('truthy or falsy', () => {
    const z = 0;
    const a = 1;
    expect(z).not.toBeTruthy();
    expect(a).toBeTruthy();
    expect(z).toBeFalsy();
  });
});

// To run this test:
// 1. Install Jest: npm install --save-dev jest typescript ts-jest @types/jest
// 2. Create a jest.config.ts:
//    import { defineConfig } from 'jest-config';
//    export default defineConfig({
//      preset: 'ts-jest',
//      testEnvironment: 'node',
//    });
// 3. Add to package.json scripts: "test": "jest"
// 4. Run: npm test