Running Vitest Tests Safely

This skill ensures Vitest tests run safely without creating hung processes that consume system resources indefinitely.

Pre-Flight Check

ALWAYS check for existing Vitest processes before starting new tests:

pgrep -f "vitest" && echo "WARNING: Existing vitest processes found"

If processes exist, either:

1. Wait for them to complete
2. Kill them if they appear stuck: pkill -f "vitest"

Required Flags for Safe Execution

1. Disable Watch Mode (Critical)

Always use --run to ensure tests exit after completion:

# Correct - will exit after tests complete
pnpm vitest --run

# NEVER use in automated contexts (will hang indefinitely)
pnpm vitest          # Bad - defaults to watch mode
pnpm vitest --watch  # Bad - explicit watch mode

2. Set Timeouts (Critical)

Always set timeouts to prevent infinite hangs:

# Set per-test timeout (default: 5000ms, recommended: 30000ms for safety)
pnpm vitest --run --testTimeout=30000

# Set hook timeout for beforeAll/afterAll
pnpm vitest --run --hookTimeout=30000

3. Fail Fast with --bail

Stop on first failure to avoid wasting resources:

# Stop after first test failure
pnpm vitest --run --bail

# Or stop after N failures
pnpm vitest --run --bail=3

Recommended Command Pattern

Combine all safety flags:

pnpm vitest --run --testTimeout=30000 --hookTimeout=30000 --bail

For running specific test files:

pnpm vitest --run --testTimeout=30000 path/to/test.test.ts

Process Isolation

For better stability, consider using forks pool:

pnpm vitest --run --pool=forks --testTimeout=30000

Post-Run Verification

After tests complete, verify no processes remain:

pgrep -f "vitest" || echo "Clean: No vitest processes running"

Handling Stuck Processes

If Vitest processes are stuck:

# Graceful termination
pkill -f "vitest"

# Force kill if needed (wait a few seconds first)
pkill -9 -f "vitest"

# Find and kill specific PIDs
ps aux | grep vitest | grep -v grep
kill <PID>

Configuration File Alternative

For projects using vitest.config.ts, add default timeouts:

export default defineConfig({
  test: {
    testTimeout: 30000,
    hookTimeout: 30000,
    // Disable watch mode by default
    watch: false,
  },
})

Summary Checklist

Before running tests, ensure:

• No existing vitest processes running (pgrep -f vitest)
• Using --run flag (no watch mode)
• Timeout set (--testTimeout=30000)
• Consider --bail for early failure detection

Quick Reference