| | |

Jest 06 ๐Ÿƒ Running Tests โ€” jest CLI, Watch Mode, and –testPathPatterns in v30

โฑ๏ธ Estimated read: 9 min | |

Jest’s CLI is the interface between the test file and the execution environment. The bare jest command runs every test once and exits, the --watch flag keeps the process alive and reruns the tests related to the changed files, and the --testPathPatterns flag filters the run by file path. The last one changed in Jest 30: the v29 flag was --testPathPattern (singular), and the v30 flag is --testPathPatterns (plural), accepting multiple patterns instead of one . A script that still passes the singular form fails with an unknown-option error, and the migration is the first thing a v29 project notices when it upgrades.

This chapter covers the bare command and the watch modes, the --testPathPatterns rename and its multi-pattern form, and the CI behavior that determines whether the watcher starts. The sections that follow walk through the run modes, the path filtering, and the watch-mode keybindings that make a large suite usable during development.

Key point: jest runs once and exits; jest --watch reruns tests related to changed files; jest --watchAll reruns every test; and --testPathPatterns (plural, v30) accepts one or more regex patterns, replacing v29’s singular --testPathPattern.


a. The run modes: once, watch, and watchAll

The bare jest command runs every test once and exits with a non-zero code if any test fails. It is the command for CI, for a pre-commit check, and for any script that needs the process to terminate.

# Run all tests once
jest

# Run all tests once with coverage
jest --coverage

jest --watch keeps the process alive and reruns the tests related to the files that changed. It is the default for npm test in Create React App and many other scaffolds, and it is the mode a developer uses while writing code . The watcher uses the dependency graph to decide which tests to rerun, so a change to a utility module reruns the tests that import it, not the whole suite.

jest --watchAll reruns every test when any file changes. It is the mode for a project where the dependency graph is not reliable, or for a developer who wants the full suite on every save.

# Rerun tests related to changed files
jest --watch

# Rerun all tests on any change
jest --watchAll

The --no-watch and --no-watchAll flags disable the modes explicitly. The --watch=false and --watchAll=false forms are equivalent. In CI, Jest detects the environment and runs once even if --watch is passed, but the explicit --no-watch is the safer form for a script that runs in both environments .


b. --testPathPatterns and the v30 rename

The --testPathPatterns flag filters the run by matching a regular expression against the test file paths. It is the flag for “run only the tests in this directory” or “run only the tests whose path contains this string.”

# Run only tests in the unit directory
jest --testPathPatterns "unit/.*"

# Multiple patterns: v30 accepts them separated by spaces
jest --testPathPatterns "unit/.*" "integration/.*"

The v30 change is the plural form and the multi-pattern acceptance. The v29 flag was --testPathPattern (singular) and accepted a single regex. The v30 flag is --testPathPatterns (plural) and accepts multiple patterns, either space-separated or by repeating the flag . The TestPathPatterns object is the internal representation, and a programmatic caller that used the old testPathPattern must construct the new object .

The rename is a breaking change for any script, CI job, or tool that passes the singular flag. The Microsoft just task runner hit the incompatibility and documented it as a breaking change with no known workaround for filtering tests with the new flag . A project that upgrades to Jest 30 should search its scripts and CI configuration for --testPathPattern and replace it with --testPathPatterns.

The --testPathIgnorePatterns flag is the inverse: it excludes the paths that match the pattern. The pattern is a regex or an array, and the flag runs the tests whose paths do not match.

# Exclude the e2e directory
jest --testPathIgnorePatterns "/tests/e2e/"

The --testNamePattern (-t) flag is the other filter, and it matches against the test names rather than the file paths. It is the flag for “run only the tests whose name contains this string,” and it is the filter that narrows a run to one behavior.

# Run tests whose name matches "login"
jest -t "login"

c. Watch mode keybindings and the CI behavior

The watch mode is interactive. The watcher prints a “Watch Usage” menu after every run, and the keys control the next run.

KeyAction
aRun all tests
fRun only failed tests
pFilter by filename regex
tFilter by test name regex
qQuit watch mode
EnterTrigger a test run

The p and t filters are the interactive equivalents of --testPathPatterns and --testNamePattern. The a key runs the full suite, and the f key reruns only the tests that failed in the last run, which is the pattern for a long suite where the developer is fixing one failure at a time .

The CI behavior is the reason a npm test script works in both environments. Jest checks process.env.CI and runs once instead of starting the watcher. The --watchAll=false flag is the explicit override for a local script that wants the single run . The CI check is built in, but the explicit flag is the clearer form.

The --runTestsByPath flag is the performance optimization for a run that specifies exact paths. It skips the regex matching and runs the given files directly, which is faster than --testPathPatterns for a large suite and a specific list of files .

# Run exact files without regex matching
jest --runTestsByPath __tests__/t1.test.js __tests__/t2.test.js

Complete Example Session

# ============================================
# PART 1: THE RUN MODES
# ============================================
# Single run (CI)
jest

# Watch mode (development)
jest --watch

# Watch all (full suite on change)
jest --watchAll

# Explicit single run
jest --watch=false

# ============================================
# PART 2: THE PATH FILTER (v30)
# ============================================
# One pattern
jest --testPathPatterns "unit/.*"

# Multiple patterns
jest --testPathPatterns "unit/.*" "integration/.*"

# ============================================
# PART 3: THE NAME FILTER
# ============================================
jest -t "login"

# ============================================
# PART 4: THE EXACT PATH OPTIMIZATION
# ============================================
jest --runTestsByPath __tests__/t1.test.js

# ============================================
# PART 5: THE WATCH KEYBINDINGS
# ============================================
# a โ†’ all tests
# f โ†’ failed only
# p โ†’ filename filter
# t โ†’ test name filter
# q โ†’ quit

The parts covered the run modes, the v30 path filter, the name filter, the exact-path optimization, and the watch keybindings.


Quick Reference

Run Modes

CommandBehavior
jestRun once, exit
jest --watchRerun related tests
jest --watchAllRerun all tests
jest --watch=falseExplicit single run

Filters

FlagMatchesv30 Change
--testPathPatternsFile path regexPlural, multi-pattern
--testPathIgnorePatternsExclude path regexโ€”
--testNamePattern / -tTest name regexโ€”
--runTestsByPathExact pathsFaster than regex

Watch Keybindings

KeyAction
aAll tests
fFailed only
pFilename filter
tTest name filter
qQuit

Best Practices

โœ… Do This:

# Use the v30 plural flag
jest --testPathPatterns "unit/.*"                          # โœ…

# Use --watch for related tests
jest --watch                                               # โœ…

# Use --runTestsByPath for exact files
jest --runTestsByPath path/to/file.test.js                 # โœ…

โŒ Don’t Do This:

# Use the removed v29 singular flag
jest --testPathPattern "unit/.*" # unknown option in v30     # โŒ

# Rely on watch mode in CI
jest --watch # CI detection helps, but be explicit           # โŒ

# Use a regex for a single exact file
jest --testPathPatterns "file.test.js" # slower than by path # โŒ

Common Pitfalls

PitfallWhy It HappensFix
Unknown option errorv29 singular flagUse --testPathPatterns
Watch mode hangs in CINo CI env varUse --watch=false
Slow filter on large suiteRegex matchingUse --runTestsByPath
Test not found by name-t matches test name, not fileUse --testPathPatterns for file

Real-World Examples

1. Single run

jest

2. Watch mode

jest --watch

3. Watch all

jest --watchAll

4. Path filter (v30)

jest --testPathPatterns "unit/.*"

5. Multiple patterns

jest --testPathPatterns "unit/.*" "integration/.*"

6. Exclude path

jest --testPathIgnorePatterns "/e2e/"

7. Name filter

jest -t "login"

8. Exact path

jest --runTestsByPath __tests__/t1.test.js

9. Coverage

jest --coverage

10. CI single run

jest --watch=false

Visual

The Run Modes

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  jest              โ†’ run once, exit                     โ”‚
โ”‚  jest --watch      โ†’ rerun related                      โ”‚
โ”‚  jest --watchAll   โ†’ rerun all                          โ”‚
โ”‚  jest --watch=false โ†’ force single run                  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The v30 Rename

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  JEST 29                    JEST 30                     โ”‚
โ”‚  --testPathPattern          --testPathPatterns          โ”‚
โ”‚  (singular)                 (plural)                    โ”‚
โ”‚  one regex                  one or more regexes         โ”‚
โ”‚                                                         โ”‚
โ”‚  jest --testPathPattern=... jest --testPathPatterns ...  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Watch Menu

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  Watch Usage                                            โ”‚
โ”‚   โ€บ Press a to run all tests.                           โ”‚
โ”‚   โ€บ Press f to run only failed tests.                   โ”‚
โ”‚   โ€บ 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.                         โ”‚
โ”‚   โ€บ Press Enter to trigger a test run.                  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

CI Detection

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚  npm test                                               โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚         โ–ผ                                               โ”‚
โ”‚  CI env var set?                                        โ”‚
โ”‚         โ”‚                                               โ”‚
โ”‚    โ”Œโ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”                                          โ”‚
โ”‚    โ–ผ         โ–ผ                                          โ”‚
โ”‚   YES        NO                                         โ”‚
โ”‚    โ”‚         โ”‚                                          โ”‚
โ”‚    โ–ผ         โ–ผ                                          โ”‚
โ”‚  run once  watch mode                                   โ”‚
โ”‚  and exit  (if --watch)                                 โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Summary

ItemValue
Single runjest
Watch relatedjest --watch
Watch alljest --watchAll
Path filter (v30)--testPathPatterns
Name filter-t / --testNamePattern
Exact paths--runTestsByPath
Watch keysa, f, p, t, q

Key takeaways:

  • The run mode is the flag. jest runs once and exits, --watch reruns related tests, and --watchAll reruns everything. The CI environment detection runs once even with --watch, but the explicit --watch=false is the safer form.
  • --testPathPatterns is plural in v30. The v29 singular flag is removed, and a script that still uses it fails with an unknown-option error. The new flag accepts multiple patterns, separated by spaces or by repeating the flag .
  • The watch mode is interactive. The a, f, p, t, and q keys control the next run, and the p and t filters are the interactive versions of the path and name flags.
  • --runTestsByPath is the performance optimization. It runs the exact paths without regex matching, which is faster than --testPathPatterns for a specific list of files.
  • The CI detection is built in, but the explicit flag is clearer. A npm test script that works in both environments relies on the detection; a script that always runs once passes --watch=false.

Remember: The CLI is the interface between the test file and the execution. jest runs, --watch reruns, and the filters narrow. The v30 rename is the migration item that breaks a script silently until the run fails; search for the singular flag and replace it with the plural one. Use --watch for development, --watch=false for CI, and --runTestsByPath when the file list is exact.

Was this helpful?


Stop using slow, ad-bloated tool sites! ๐Ÿคฎ

๐Ÿ”Ž Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
โœ… Finance (Mortgage, Interest, Inflation)
โœ… Tech (Base64, JSON, Dev Suite, IP)
โœ… Health (BMI, BMR, TDEE)
โœ… Productivity (Timer, Workspace, QR)

โšก๏ธ Fast & Private
๐Ÿ”’ No data leaves your device
๐Ÿ’Ž 100% Free

๐Ÿ”— Use it now: https://tools.kandz.me
๐Ÿ”– Bookmark itโ€”youโ€™ll need it later!