Vitest 06 🧪 Running Tests — vitest run vs watch mode & CLI filtering
Vitest has two execution modes and a set of filters that determine which tests run. The mode is determined by the environment: an interactive terminal defaults to watch mode, and CI defaults to a single run . The filters are the CLI arguments, the -t test-name pattern, and the line-number selector that points at a specific test. The combination of mode and filter is what makes a large suite usable during development, and what makes a CI run deterministic.
This chapter covers the two modes, the environment detection that switches between them, and the filters that narrow a run without changing the mode. The sections that follow walk through vitest run and watch mode, the file and test-name filters, and the CI-specific behavior that prevents a watch-mode hang.
Key point: vitest run executes once and exits; bare vitest enters watch mode when stdin is a TTY and CI is not set; the -t pattern and file-path arguments narrow the run, but they still load every matching file unless a file path is passed alongside the filter.
a. vitest run and watch mode
vitest run performs a single run without watch mode . It is the command for CI, for a pre-commit check, and for any script that needs the process to exit when the tests finish. The --run flag is the equivalent for a bare vitest invocation, and the -w/--watch flag forces watch mode on .
Bare vitest enters watch mode by default in an interactive terminal. The default is !process.env.CI && process.stdin.isTTY, which means the mode depends on the environment, not on a flag . In watch mode, Vitest runs the tests, waits for file changes, and reruns the affected tests. The interactive keybindings (a for all, f for failed, p for filename filter, t for test-name regex, q to quit) are available while the watcher is running .
The AI-agent case is the newest addition to the default. When Vitest detects an AI coding agent, the default is watch: false . This addresses the failure mode where an agent runs vitest in a TTY, the process runs the tests, and then hangs indefinitely waiting for changes, preventing the agent from receiving the result . A developer in an interactive terminal still gets watch mode; an agent gets a single run.
# Single run (CI, scripts)
vitest run
# Watch mode (interactive development)
vitest
vitest watch
# Force single run from a bare invocation
vitest --run
b. Filtering by file, test name, and line number
The simplest filter is a positional argument. vitest basic runs every test file whose path contains basic . The match is a substring, not a regex or glob, and it is applied to the file path, not the test name.
The -t (or --testNamePattern) filter matches against the full test name, which is the chain of describe blocks and the it name joined by > . vitest -t "handles empty input" runs only the tests whose name contains the pattern. The filter is a regex, so a pattern with metacharacters needs escaping.
The combination is the important part. A -t filter on its own still loads every test file to discover which tests match, and in a large project that discovery cost is the bottleneck. Passing a file path alongside the filter restricts the discovery to the files that matter.
# Filter by file name
vitest basic
# Filter by test name (loads every file)
vitest -t "handles empty input"
# Filter by name within a file (recommended)
vitest utils.test.ts -t "handles empty input"
# Filter by line number (full filename required)
vitest basic/foo.test.ts:10
# Multiple line numbers
vitest basic/foo.test.ts:10 basic/foo.test.ts:25
The line-number selector runs the test that contains the given line. It requires the full filename with the extension; a partial name like foo:10 is rejected . Ranges are not supported, and multiple tests are selected by listing each line number separately.
The in-file markers are the other filtering layer. test.only runs only the marked tests in the file, test.skip skips a test, and test.todo marks a test as planned. In CI, Vitest fails the run if it encounters .only when process.env.CI is set, which prevents accidentally committing a focused test .
c. CI behavior and the exit contract
The CI behavior is the mode plus the exit code. In CI, vitest (without run) falls back to a single run because process.env.CI is set and stdin is not a TTY . The process exits when the tests finish, and the exit code is non-zero if any test fails. A CI step that runs vitest therefore behaves the same as one that runs vitest run, but the explicit run is clearer in the script.
The --last-failed flag is the CI and local debugging aid. It runs only the tests that failed in the last run, reading the failures from the results cache . It can be combined with a name filter (vitest run --last-failed -t login), and in watch mode only the first run is limited to the failed tests. If no test failed in the last run, the command prints “No failed tests found” and exits with code 1 unless --passWithNoTests is set.
The --changed flag runs the tests affected by changed files, and --since-last-run (experimental, 5.1.0) runs the tests whose dependencies were modified since the last run . Both are file-selection filters, not name filters, and both assume a cache that records the dependency graph.
# CI: single run, explicit
vitest run
# Rerun only the failures
vitest run --last-failed
# Failures matching a name
vitest run --last-failed -t login
Complete Example Session
# ============================================
# PART 1: THE TWO MODES
# ============================================
# Interactive terminal
vitest
# → watch mode, waits for changes
# CI or script
vitest run
# → single run, exits with code
# ============================================
# PART 2: FILTERING BY FILE
# ============================================
vitest basic
# → every file whose path contains "basic"
# ============================================
# PART 3: FILTERING BY TEST NAME
# ============================================
vitest -t "handles empty input"
# → loads every file, runs matching tests
# ============================================
# PART 4: FILE + NAME (RECOMMENDED)
# ============================================
vitest utils.test.ts -t "handles empty input"
# → loads only utils.test.ts, runs matching tests
# ============================================
# PART 5: LINE NUMBER
# ============================================
vitest basic/foo.test.ts:10
# → runs the test containing line 10
# ============================================
# PART 6: CI WITH LAST-FAILED
# ============================================
vitest run --last-failed
# → only the tests that failed in the last run
The parts covered the two modes, the file filter, the name filter, the file-plus-name combination, the line-number selector, and the --last-failed flag.
Quick Reference
Modes
| Command | Behavior |
|---|---|
vitest run | Single run, exits |
vitest | Watch mode in TTY, run in CI |
vitest watch | Explicit watch mode |
vitest --run | Force single run |
vitest -w | Force watch mode |
Filters
| Filter | Scope | Example |
|---|---|---|
| Positional path | File path substring | vitest basic |
-t / --testNamePattern | Test name regex | vitest -t "login" |
path:line | Test containing line | vitest foo.test.ts:10 |
--dir | Directory | vitest --dir ./packages/api |
CI Flags
| Flag | Effect |
|---|---|
--last-failed | Only last run’s failures |
--changed | Tests affected by changed files |
--since-last-run | Tests whose deps changed (experimental) |
--passWithNoTests | Exit 0 when no tests match |
Default Mode Detection
| Condition | Mode |
|---|---|
| CI + non-TTY | Run |
| TTY + no CI | Watch |
| AI agent detected | Run |
Best Practices
✅ Do This:
# Explicit run in CI
vitest run # ✅
# Combine file and name filters
vitest utils.test.ts -t "handles empty input" # ✅
# Use line numbers for a single test
vitest foo.test.ts:10 # ✅
❌ Don’t Do This:
# Assume bare vitest exits in a TTY
vitest # enters watch mode # ❌
# Use -t without a file path on a large suite
vitest -t "login" # loads every file # ❌
# Use a partial path with a line number
vitest foo:10 # rejected # ❌
Common Pitfalls
| Pitfall | Why It Happens | Fix |
|---|---|---|
| Process hangs in a script | Bare vitest in a TTY | Use vitest run or --run |
| Slow filter on large suite | -t loads every file | Add a file path |
| Line filter rejected | Partial filename | Use the full filename with extension |
CI skips .only unexpectedly | allowOnly default false in CI | Remove .only before committing |
Real-World Examples
1. Single run
vitest run
2. Watch mode
vitest
3. File filter
vitest utils
4. Name filter
vitest -t "login"
5. File + name
vitest utils.test.ts -t "login"
6. Line number
vitest utils.test.ts:42
7. Last failed
vitest run --last-failed
8. Changed files
vitest run --changed
9. Directory
vitest --dir ./packages/api
10. Pass with no tests
vitest run --passWithNoTests
Visual
Mode Selection
┌─────────────────────────────────────────────────────────┐
│ vitest (bare) │
│ │ │
│ ▼ │
│ CI set? ──yes──► single run │
│ │ │
│ no │
│ ▼ │
│ stdin TTY? ──no──► single run │
│ │ │
│ yes │
│ ▼ │
│ AI agent? ──yes──► single run │
│ │ │
│ no │
│ ▼ │
│ watch mode │
└─────────────────────────────────────────────────────────┘
Filter Scope
┌─────────────────────────────────────────────────────────┐
│ vitest basic │
│ → file path contains "basic" │
│ │
│ vitest -t "login" │
│ → loads ALL files, matches test names │
│ │
│ vitest utils.test.ts -t "login" │
│ → loads ONE file, matches test names │
│ │
│ vitest utils.test.ts:42 │
│ → runs the test containing line 42 │
└─────────────────────────────────────────────────────────┘
CI Flow
┌─────────────────────────────────────────────────────────┐
│ CI step: vitest run │
│ │ │
│ ▼ │
│ Run all tests (or filtered) │
│ │ │
│ ┌────┴────┐ │
│ ▼ ▼ │
│ pass fail │
│ │ │ │
│ ▼ ▼ │
│ exit 0 exit non-zero │
└─────────────────────────────────────────────────────────┘
Summary
| Item | Value |
|---|---|
| Single run | vitest run |
| Watch mode | vitest (TTY, no CI) |
| File filter | Positional path substring |
| Name filter | -t / --testNamePattern |
| Line selector | path/to/file.test.ts:10 |
| Last failed | --last-failed |
| CI fallback | Bare vitest runs once |
Key takeaways:
- The mode is environment-determined. Bare
vitestenters watch mode when stdin is a TTY andCIis not set; it runs once in CI, in a non-interactive shell, and when an AI agent is detected . vitest runis the explicit single-run command. It is the command for CI and scripts, and the--runflag is the equivalent for a bare invocation.- The
-tfilter matches test names, not file names. It loads every file to discover matching tests, so a file path alongside it is the recommended pattern for large suites . - The line-number selector requires the full filename.
vitest foo.test.ts:10works;vitest foo:10is rejected. Ranges are not supported . --last-failednarrows to the previous run’s failures. It reads from the results cache, can be combined with a name filter, and exits with code 1 when no failures are found unless--passWithNoTestsis set .
Remember: The mode is the environment, and the filter is the argument. Use vitest run in CI and scripts, bare vitest for watch mode in development, and -t with a file path to focus on one behavior. The line-number selector is the fastest way to run the test under the cursor. The filters do not change the mode; they change what the mode runs.
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!