Running Jest from the CLI
Running npx jest (or npm test if wired to a script) executes every test file Jest discovers and prints a summary of passed, failed, and skipped tests along with total run time. You can target a subset by passing a filename or pattern as an argument, e.g. npx jest sum.test.js or npx jest src/utils, which matches against file paths using a substring/regex match rather than requiring an exact path. The --verbose flag prints every individual test name and its pass/fail status instead of just the per-file summary, which is useful in CI logs where you want a full record of what ran.
Cricket analogy: Running npx jest for the whole suite is like an entire domestic season's fixture list being played out, while npx jest sum.test.js targeting one file is like calling up just a single team's match highlights instead of the whole season's results.
Watch Mode
Running npx jest --watch starts an interactive session that reruns tests automatically as you save files, and by default only reruns tests related to files changed since your last git commit, which keeps feedback fast even in a large codebase. Inside watch mode, pressing p lets you filter by a filename pattern, t filters by test name pattern, f reruns only tests that failed in the previous run, and a reruns the entire suite — --watchAll runs the same interactive mode but always reruns every test regardless of git changes, useful outside a git repository or when you want a full check every save.
Cricket analogy: Watch mode automatically rerunning only tests related to changed files is like a coach only re-reviewing footage of the specific batter who just changed their stance, instead of rewatching the entire team's five-day match footage after every net session.
# Run the whole suite once
npx jest
# Run only files matching a pattern
npx jest src/utils
# Interactive watch mode (git-aware)
npx jest --watch
# Watch mode that always reruns everything
npx jest --watchAll
# Filter by test name (matches the string passed to test()/describe())
npx jest -t "adds two numbers"
# Generate a coverage report
npx jest --coverageWatch mode's git-aware filtering (--watch) requires the project to be inside a Git or Mercurial repository — outside of one, Jest falls back to behaving like --watchAll automatically.
Filtering Tests
Beyond file-path arguments, the -t (or --testNamePattern) flag filters by test/describe name using a regex, e.g. npx jest -t "user login" runs only tests whose full name (including parent describe blocks) matches that string. Inside a file, test.only() and describe.only() restrict execution to just that block for the current run, which is handy while debugging a single failing test, while test.skip() and describe.skip() do the opposite and exclude a block — both are meant as temporary local tools, not something to commit long-term, since a forgotten .only() silently disables the rest of your suite in CI.
Cricket analogy: test.only() restricting a run to one block is like a net session focused entirely on one batter's technique against short-pitched bowling, deliberately excluding the rest of the squad's drills for that session.
A test.only() or describe.only() left in committed code will silently skip every other test in that file when the suite runs in CI, potentially masking real regressions. Consider an ESLint rule like jest/no-focused-tests to catch this before it merges.
Reading Coverage Reports
Running npx jest --coverage produces a terminal table with four percentage columns — Statements, Branches, Functions, and Lines — plus, by default, an HTML report written to coverage/lcov-report/index.html that you can open in a browser to see exactly which lines of each file were and weren't executed, highlighted in red for uncovered code. High coverage numbers indicate code was executed during tests, but they say nothing about whether the right assertions were made — a test that calls a function without ever checking its return value still counts toward coverage, so coverage percentage is a signal to investigate untested code paths, not proof of correctness.
Cricket analogy: High test coverage without strong assertions is like a batter who faces every ball in an over (coverage) but the scorer never actually records whether each shot connected or missed — presence at the crease isn't the same as a verified outcome.
- npx jest runs the full suite; passing a file path or pattern argument narrows it to matching files.
- --verbose prints every individual test's name and pass/fail status instead of just a per-file summary.
- --watch reruns only tests related to files changed since the last commit (git-aware); --watchAll always reruns everything.
- Inside watch mode: p filters by filename, t filters by test name, f reruns only failures, a reruns all.
- -t/--testNamePattern filters by test/describe name using regex; test.only/describe.only restrict a single run to one block.
- A forgotten .only() in committed code silently skips the rest of the suite in CI — never merge it.
- --coverage reports Statements/Branches/Functions/Lines percentages and an HTML report, but high coverage doesn't guarantee correct assertions.
Practice what you learned
1. What does npx jest --verbose do differently from a plain npx jest run?
2. By default, what does npx jest --watch rerun when you save a file?
3. Inside watch mode, what does pressing 'f' do?
4. Why is committing a test.only() risky?
5. What does a high code coverage percentage guarantee?
Was this page helpful?
You May Also Like
test() and describe() Blocks
How to organize related tests using describe() blocks, and the setup/teardown hooks that run alongside them.
Writing Your First Test
A hands-on walkthrough of writing, running, and understanding your first Jest test file.
Installing and Configuring Jest
How to add Jest to a JavaScript or TypeScript project, and the key configuration options in jest.config.js.