jest-watcher

library30.3.0jsnpmunverified

Jest Watcher is a core sub-package of the Jest testing framework, providing the interactive command-line interface (CLI) for running tests in 'watch' mode. It enables developers to receive instant feedback on code changes by automatically re-running relevant tests, filtering by filename or test name, and focusing on failed tests. The current stable version is 30.3.0. While Jest v30's major release cycle was notably long (three years), the project aims for more frequent major releases going forward, with minor and patch versions released regularly. Key differentiators include its tight integration with the broader Jest ecosystem for features like snapshot testing and code coverage, offering a dynamic and responsive development workflow compared to static, manual test execution.

testing

npm install jest-watcher

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · JEST-WATCHER

jest-watcher

testingjavascriptv30.3.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.

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

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

✗ import { defineConfig } from 'jest';

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.

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);

jest --version

Debug

Known issues

breakingJest 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).

affects: >=30.0.0

breakingThe 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`.

affects: >=30.0.0

breakingSeveral 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.

affects: >=30.0.0

breakingSnapshot 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.

affects: >=30.0.0

breakingThe `--testPathPattern` CLI option has been renamed to `--testPathPatterns` for consistency.

fix

Update any scripts or CI configurations that use `--testPathPattern` to `--testPathPatterns`.

affects: >=30.0.0

gotchaJest 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.

affects: >=30.0.0

gotchaJest 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.

affects: >=30.0.0

Errors

Common errors & fixes

Jest encountered an unexpected token

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)

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

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.

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`.

Upgrade

Version history

30.3.0latest on npm

Audit

Dependencies

jestrequiredCore Jest functionality; jest-watcher is an internal package used by the main Jest runner.

jest-configrequiredFor defining and managing Jest's configuration, including watch plugins.

Agent activity

4 hits · last 30 days

node

Resources

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

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

homepagehttps://jestjs.io ↗