Jest Watch Mode

How Watch Mode Decides What to Re-Run

Running jest --watch starts Jest in an interactive mode that watches your file system for changes. Instead of re-running your entire suite on every save, Jest uses your project's dependency graph to figure out which test files are actually related to the changed source file, and re-runs only those.

--watch uses git to detect changed files (and only works well inside a git repository); --watchAll ignores git and simply watches every file, useful outside version control or when you want everything re-checked regardless of what changed.

npx jest --watch

Watch Usage
 › Press f to run only failed tests.
 › Press o to only run tests related to changed files.
 › Press p to filter by a filename regex pattern.
 › Press t to filter by a test name regex pattern.
 › Press q to quit watch mode.

Watch mode's interactive menu appears after the first run and stays available while it's running.

Watch Mode Keyboard Shortcuts

f — run only failed tests
o — run only tests related to changed files (default mode)
a — run all tests
p — filter by a filename pattern
t — filter by a test name pattern
q — quit watch mode

• Pressing f is useful right after a run with failures, to iterate quickly without noise from passing tests.
• p and t accept a regex, letting you narrow focus to a specific file or test name temporarily.
• Watch mode automatically re-runs the previous filtered scope after every file save.
• Exiting and restarting watch mode resets any active p/t filters.

Watch Mode Cheat Sheet

Commands and shortcuts for Jest's interactive watch mode.

How "Related to Changed Files" Detection Works

Jest builds a dependency graph from your import/require statements to determine which test files transitively depend on a changed source file. Editing mathUtils.js will re-run mathUtils.test.js and any other test file that imports it, directly or indirectly, without re-running unrelated tests elsewhere in the project.

Using Watch Mode for a Tight TDD Loop

Watch mode pairs naturally with test-driven development: write a failing test, save, watch it fail instantly, write the implementation, save again, and watch it pass — all without leaving your editor or manually re-running commands.

• Press f after a failure to focus exclusively on the broken test while fixing it.
• Press a periodically to confirm the full suite still passes, not just your filtered subset.
• Combine with --verbose if you want every individual test name printed during the loop.

Common Mistakes

• Running --watch outside a git repository, where change detection doesn't work as expected (use --watchAll instead).
• Forgetting an active p/t filter is still applied, wondering why a new test never seems to run.
• Never pressing a to confirm the whole suite still passes after a long focused editing session.
• Leaving watch mode running unintentionally in CI, where it would never exit.

Key Takeaways

• jest --watch re-runs only tests related to changed files, using git to detect changes.
• --watchAll watches everything, useful outside git or for a full re-check.
• Interactive shortcuts (f, o, p, t, a) let you filter and refocus without restarting Jest.
• Watch mode is ideal for a tight, fast test-driven development feedback loop.