jest-watch-typeahead

jest-watch-typeahead adds two watch plugins to Jest’s interactive watch mode: one that filters test files by a filename regex pattern, and one that filters by individual test name. Instead of re-running an entire suite, a developer presses a key to open a live prompt, types a partial pattern, and sees a highlighted, scrollable list of matching files or tests update as they type — then commits the pattern to instantly re-scope watch mode to just those matches.

The package ships as a pair of independently importable subpath exports (jest-watch-typeahead/filename and jest-watch-typeahead/testname) with zero required configuration, sensible default key bindings, and small per-plugin overrides for the activation key and prompt text. It is maintained under the jest-community GitHub organization and is one of the most widely used companion packages in the Jest ecosystem, downloaded millions of times a week.

What You Get

• Two Jest watch plugins — a filename filter and a test-name filter — exported as separate subpaths from one package.
• An interactive terminal prompt with live typeahead search, match-count feedback, and highlighted matching substrings.
• Zero-config defaults (key p for the filename plugin, t for the test-name plugin) with optional per-plugin key/prompt overrides.
• Automatic tracking of the active Jest projects on file changes so filtering stays scoped correctly in multi-project configs.

Common Use Cases

• Narrowing Jest’s watch mode to one file or a small group of files in a large monorepo test suite.
• Filtering down to a single failing it()/describe() block by test name instead of re-running the whole suite.
• Switching between filename and test-name filtering while iterating locally on a pull request.
• Exploring an unfamiliar codebase’s test coverage by typing partial names to see what tests exist.

Under The Hood

Architecture The package is a thin, focused implementation of Jest’s WatchPlugin interface, split into two parallel plugin classes (file_name_plugin/plugin.ts, test_name_plugin/plugin.ts) that each wire a Prompt instance from jest-watcher to a plugin-specific *PatternPrompt class in prompt.ts; shared formatting and matching logic lives in lib/pattern_mode_helpers.ts, lib/utils.ts, and lib/scroll.ts. Data flows from Jest’s onFileChange hook (captured active projects) through keystroke events (onKey → prompt.put()) into the prompt’s render loop, and back out via updateConfigAndRun with a computed testPathPatterns or testNamePattern. Because both plugins implement jest-watcher’s interface directly with minimal abstraction between them, a change to that upstream contract would require updating both plugin classes in lockstep.

Tech Stack Written in TypeScript (ESNext target, type: module, strict mode) and compiled with Babel (babel --extensions .js,.ts src -d build). Runtime dependencies are small, single-purpose terminal utilities — chalk, strip-ansi, ansi-escapes, string-length, slash — plus jest-watcher and jest-regex-util from the Jest monorepo, with jest itself as a peer dependency. Tooling includes ESLint 9’s flat config with typescript-eslint and eslint-plugin-jest, Prettier, Yarn 4 (Berry) as the package manager, and semantic-release for automated versioned publishing. CI runs the test matrix across Node 18, 20, 22, and 24 via GitHub Actions, alongside a separate commitlint job.

Code Quality Tests are colocated under __tests__ directories next to the source they cover, use @jest/globals explicit imports (injectGlobals: false), parameterized test.each cases, and snapshot assertions (jest-serializer-ansi-escapes for ANSI-safe snapshots). TypeScript strict mode plus noImplicitReturns and consistent file casing are enforced at the compiler level, and ESLint/Prettier are wired into CI. Coverage leans toward the pure formatting/matching helpers (utils.ts, pattern_mode_helpers.ts) and plugin construction; the interactive prompt’s terminal render loop itself has comparatively thinner direct test coverage.

API Design The public surface is deliberately tiny: two subpath exports that slot directly into Jest’s watchPlugins array with no required configuration, sane default key bindings, and an optional { key, prompt } override per plugin. Importing the package’s root entrypoint (rather than a subpath) throws a descriptive error pointing to the correct usage instead of failing silently or behaving unexpectedly — a small but deliberate developer-experience choice. The design isn’t conceptually novel — it’s a clean, well-scoped implementation of Jest’s own documented watch-plugin API — but it requires essentially no boilerplate to adopt.