| | |

Vitest 06 🧪 Running Tests — vitest run vs watch mode & CLI filtering

⏱️ Estimated read: 9 min | |

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

CommandBehavior
vitest runSingle run, exits
vitestWatch mode in TTY, run in CI
vitest watchExplicit watch mode
vitest --runForce single run
vitest -wForce watch mode

Filters

FilterScopeExample
Positional pathFile path substringvitest basic
-t / --testNamePatternTest name regexvitest -t "login"
path:lineTest containing linevitest foo.test.ts:10
--dirDirectoryvitest --dir ./packages/api

CI Flags

FlagEffect
--last-failedOnly last run’s failures
--changedTests affected by changed files
--since-last-runTests whose deps changed (experimental)
--passWithNoTestsExit 0 when no tests match

Default Mode Detection

ConditionMode
CI + non-TTYRun
TTY + no CIWatch
AI agent detectedRun

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

PitfallWhy It HappensFix
Process hangs in a scriptBare vitest in a TTYUse vitest run or --run
Slow filter on large suite-t loads every fileAdd a file path
Line filter rejectedPartial filenameUse the full filename with extension
CI skips .only unexpectedlyallowOnly default false in CIRemove .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

ItemValue
Single runvitest run
Watch modevitest (TTY, no CI)
File filterPositional path substring
Name filter-t / --testNamePattern
Line selectorpath/to/file.test.ts:10
Last failed--last-failed
CI fallbackBare vitest runs once

Key takeaways:

  • The mode is environment-determined. Bare vitest enters watch mode when stdin is a TTY and CI is not set; it runs once in CI, in a non-interactive shell, and when an AI agent is detected .
  • vitest run is the explicit single-run command. It is the command for CI and scripts, and the --run flag is the equivalent for a bare invocation.
  • The -t filter 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:10 works; vitest foo:10 is rejected. Ranges are not supported .
  • --last-failed narrows 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 --passWithNoTests is 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.

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!