Jest Watcher

Common errors

• Jest encountered an unexpected token

  cause Jest's transformer (e.g., Babel, ts-jest) is not processing a file, often in `node_modules`, or a non-JavaScript file is being imported.
  fix Adjust `transformIgnorePatterns` in `jest.config.js` to transpile the problematic module, or use `moduleNameMapper` to mock non-JS assets. Ensure Babel/TypeScript configuration is correct.

• Determining Test Suites to Run (Watcher hangs or fails to find tests)

  cause Unresolvable `import`/`export` paths in modules, potentially due to bad merges or misconfigured module resolution.
  fix Inspect module resolution paths and ensure all imports are correct. Adding `console.error` in the resolver logic might help pinpoint the exact file causing the issue.

• Error: Cross origin http://localhost forbidden

  cause Jest's test environment is misconfigured, leading to unexpected browser-like security errors in Node.js tests.
  fix Explicitly set the `testEnvironment` in `jest.config.js` to `'node'` if testing server-side code, or ensure `'jsdom'` is correctly configured for browser environments.

• Jest did not exit one second after the test run completed. This usually means that there are asynchronous operations that weren't stopped in your tests.

  cause Open handles (timers, network connections, etc.) are left active after tests complete, preventing Jest from exiting cleanly.
  fix Run Jest with `--detectOpenHandles` to identify the source of the open handles. Ensure all asynchronous operations are properly awaited or cleaned up in your tests or `setupFilesAfterEnv`.

Warnings

• breaking Jest 30.x has dropped support for older Node.js versions. Ensure your environment is running Node.js 18.14.0, 20.x, 22.x, or 24.x and above.
  Fix: Upgrade Node.js to a compatible version (e.g., Node.js 20 LTS or later).
• breaking The minimum compatible TypeScript version is now 5.4. Projects using Jest's type definitions must update their TypeScript installation.
  Fix: Update TypeScript to version 5.4 or higher in your project's `devDependencies`.
• breaking Several deprecated `expect` matcher aliases (e.g., `toBeCalled` for `toHaveBeenCalled`) have been fully removed. These were deprecated since Jest 26.
  Fix: Update your tests to use the canonical matcher names. ESLint with `eslint-plugin-jest` can help automate this via the `no-alias-methods` rule.
• breaking Snapshot header formats have changed in Jest 30, requiring all existing snapshots to be regenerated.
  Fix: Run Jest with the `-u` or `--updateSnapshot` flag to regenerate all snapshots (e.g., `jest -u`). Review changes before committing.
• breaking The `--testPathPattern` CLI option has been renamed to `--testPathPatterns` for consistency.
  Fix: Update any scripts or CI configurations that use `--testPathPattern` to `--testPathPatterns`.
• gotcha Jest 30 bundles its modules into single files, which might break tools that relied on reaching into Jest's internal file structure.
  Fix: Avoid directly importing or referencing internal Jest paths. Use official APIs and exposed modules only.
• gotcha Jest 30 introduces `globalsCleanup` to detect and report global variables not cleaned up between test files, which can cause memory leaks. Default is 'soft'.
  Fix: Address reported global variable leaks by ensuring proper cleanup in test setups/teardowns. Configure `globalsCleanup: 'off'` in `jest.config.js` to disable, or `'on'` for strict enforcement.

Install

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

Imports

• BaseWatchPlugin

  import { BaseWatchPlugin } from 'jest-watcher';

  Used for creating custom interactive watch mode plugins. Extend this class to implement custom logic triggered by key presses in watch mode.
• Config

  import type { Config } from 'jest';

  The main Jest configuration type. Often imported for type-safe `jest.config.ts` files, particularly when using `defineConfig`.
• defineConfig
  wrong:

  import { defineConfig } from 'jest';

  correct:

  import { defineConfig } from 'jest-config';

  Introduced in Jest 30.3.0, this helper provides type-safe configuration for `jest.config.ts` files. It's exported from `jest-config`, not the top-level `jest` package.

Quickstart

Demonstrates how to create and register a basic custom Jest watch plugin using TypeScript, logging a message when its key is pressed.

import type { Config } from 'jest';
import { BaseWatchPlugin } from 'jest-watcher';
import type {
  JestHookSubscriber,
  WatchPlugin,
  UsageInfo,
  GlobalConfig,
  UpdateConfigCallback,
} from 'jest-watcher';

// A minimal custom watch plugin that just logs a message
class MyCustomWatchPlugin extends BaseWatchPlugin implements WatchPlugin {
  is);