references/perf-run-mode-ci.md
GitHubUse Run Mode in CI Environments
Vitest's default watch mode is designed for development, continuously watching files and providing an interactive UI. In CI, this overhead is wasted. Use --run to execute tests once and exit.
Incorrect (watch mode in CI):
# .github/workflows/test.yml
jobs:
test:
steps:
# Watch mode starts, hangs waiting for file changes
- run: npx vitest
Correct (run mode in CI):
# .github/workflows/test.yml
jobs:
test:
steps:
# Runs tests once and exits
- run: npx vitest run
Automatic detection:
// vitest.config.ts
export default defineConfig({
test: {
// Vitest automatically uses run mode when CI=true
// But explicit configuration is clearer
watch: !process.env.CI,
},
})
Additional CI optimizations:
jobs:
test:
env:
CI: true
steps:
- run: npx vitest run --reporter=github-actions
CI-specific reporters:
// vitest.config.ts
export default defineConfig({
test: {
reporters: process.env.CI
? ['default', 'github-actions']
: ['default'],
},
})
Package.json scripts:
{
"scripts": {
"test": "vitest",
"test:ci": "vitest run --coverage"
}
}
Benefits:
- No hanging processes in CI
- Faster startup without watch setup
- Clear exit codes for CI systems
Reference: Vitest CLI