running-vitest-safely

What this skill does

# 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:**

```bash
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

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

For running specific test files:

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

## Process Isolation

For better stability, consider using forks pool:

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

## Post-Run Verification

After tests complete, verify no processes remain:

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

## Handling Stuck Processes

If Vitest processes are stuck:

```bash
# 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:

```typescript
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

| Flag | Purpose | Recommended Value |
|------|---------|-------------------|
| `--run` | Disable watch mode | Always use |
| `--testTimeout` | Per-test timeout | 30000 (30s) |
| `--hookTimeout` | Hook timeout | 30000 (30s) |
| `--bail` | Stop on failure | Use for CI |
| `--pool=forks` | Process isolation | Optional |