/vitest

Command Line Interface

Commands

vitest

Start Vitest in watch mode (dev) or run mode (CI):

vitest                    # Watch mode in dev, run mode in CI
vitest foobar             # Run tests containing "foobar" in path
vitest basic/foo.test.ts:10  # Run specific test by file and line number

vitest run

Run tests once without watch mode:

vitest run
vitest run --coverage

vitest watch

Explicitly start watch mode:

vitest watch

vitest related

Run tests that import specific files (useful with lint-staged):

vitest related src/index.ts src/utils.ts --run

vitest bench

Run only benchmark tests:

vitest bench

vitest list

List all matching tests without running them:

vitest list                    # List test names
vitest list --json             # Output as JSON
vitest list --filesOnly        # List only test files

v5: list parses test files statically instead of running them. Pass --no-static-parse to run them; tune with --static-parse-concurrency.

vitest doctor (v5)

Run the suite under alternative configs and recommend faster options (e.g. a different pool, isolate: false, fsModuleCache, lower maxWorkers). Needs a passing baseline; takes several times a normal run:

vitest doctor

vitest init

Initialize project setup:

vitest init browser            # Set up browser testing

vitest --list-tags

List tags defined in config without running tests:

vitest --list-tags             # Human-readable list
vitest --list-tags=json        # JSON output

Common Options

# Configuration
--config <path>           # Path to config file
--project, -p <name>      # Run specific project (v5 adds the -p shorthand)

# Filtering
--testNamePattern, -t     # Run tests matching pattern
--tagsFilter <expr>       # Run tests by tag expression, e.g. "db && !flaky"
--changed                 # Run tests for changed files
--changed HEAD~1          # Tests for last commit changes
--dir <path>              # Limit test discovery to a directory

# Reporters
--reporter <name>         # default, verbose, tree, dot, json, html, junit, minimal, blob
--reporter=json --outputFile=report.json

# Coverage
--coverage                # Enable coverage
--coverage.provider v8    # Use v8 provider
--coverage.reporter text,html

# Execution
--shard <index>/<count>   # Split tests across machines
--bail <n>                # Stop after n failures
--retry <n>               # Retry failed tests n times
--repeats <n>             # v5: repeat every test n times (hunt flaky tests)
--shuffle                 # Randomize test order
--no-file-parallelism     # Run test files one at a time

# Watch mode
--no-watch                # Disable watch mode
--standalone              # Start without running (v4: runs matched files if a filter is passed)

# Environment
--environment <env>       # jsdom, happy-dom, node
--globals                 # Enable global APIs

# Debugging
--inspect                 # Enable Node inspector
--inspect-brk             # Break on start

# Output
--silent                  # Suppress console output
--no-color                # Disable colors

Package.json Scripts

{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:ui": "vitest --ui",
    "coverage": "vitest run --coverage"
  }
}

Sharding for CI

Split tests across multiple machines. The blob reporter writes to .vitest/blob/ by default:

# Machine 1
vitest run --shard=1/3 --reporter=blob --outputFile=reports/blob-1.json

# Machine 2
vitest run --shard=2/3 --reporter=blob --outputFile=reports/blob-2.json

# Merge all blobs into a final report
vitest --merge-reports=reports --reporter=junit --reporter=default

Watch Mode Keyboard Shortcuts

In watch mode, press:

• a - Run all tests
• f - Run only failed tests
• u - Update snapshots
• p - Filter by filename pattern
• t - Filter by test name pattern
• q - Quit

Key Points

• Watch mode is default in dev, run mode in CI (when process.env.CI is set)
• Use --run flag to ensure single run (important for lint-staged)
• Both camelCase (--testTimeout) and kebab-case (--test-timeout) work
• Boolean options can be negated with --no- prefix
• Filter tests by tag with --tagsFilter (tags must be declared in config) — see features-test-tags
• --merge-reports and --reporter=blob do not work in watch mode (--merge-reports now handles non-sharded multi-environment runs)
• v5: use -p as shorthand for --project; vitest doctor suggests faster config