🚨 CRITICAL GUIDELINES

Windows File Path Requirements

MANDATORY: Always Use Backslashes on Windows for File Paths

When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).

Examples:

❌ WRONG: D:/repos/project/file.tsx
✅ CORRECT: D:\repos\project\file.tsx

This applies to:

Edit tool file_path parameter
Write tool file_path parameter
All file operations on Windows systems

Documentation Guidelines

NEVER create new documentation files unless explicitly requested by the user.

Priority: Update existing README.md files rather than creating new documentation
Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
User preference: Only create additional .md files when user specifically asks for documentation

Vitest 3.x Features and Best Practices (2025)

Overview

Vitest 3.0 was released in January 2025 with major improvements to reporting, browser testing, watch mode, and developer experience. This skill provides comprehensive knowledge of Vitest 3.x features and modern testing patterns.

Major Features in Vitest 3.0+

1. Annotation API (Vitest 3.2+)

The annotation API allows you to add custom metadata, messages, and attachments to any test, visible in UI, HTML, JUnit, TAP, and GitHub Actions reporters.

Usage:

import { test, expect } from 'vitest';

test('user authentication', async ({ task }) => {
  // Add custom annotation
  task.meta.annotation = {
    message: 'Testing OAuth2 flow with external provider',
    attachments: [
      { name: 'config', content: JSON.stringify(oauthConfig) }
    ]
  };

  const result = await authenticateUser(credentials);
  expect(result.token).toBeDefined();
});

Use Cases:

Document complex test scenarios
Attach debug information
Link to external resources (tickets, docs)
Add performance metrics
Track test metadata for reporting

2. Line Number Filtering

Run specific tests by their line number in the file, enabling precise test execution from IDEs.

CLI Usage:

# Run test at specific line
vitest run tests/user.test.js:42

# Run multiple tests by line
vitest run tests/user.test.js:42 tests/user.test.js:67

# Works with ranges
vitest run tests/user.test.js:42-67

IDE Integration:

VS Code: Click line number gutter
JetBrains IDEs: Run from context menu
Enables "run test at cursor" functionality

3. Enhanced Watch Mode

Smarter and more responsive watch mode with improved change detection.

Features:

Detects changes more accurately
Only re-runs affected tests
Faster rebuild times
Better file watching on Windows
Reduced false positives

Configuration:

export default defineConfig({
  test: {
    watch: true,
    watchExclude: ['**/node_modules/**', '**/dist/**'],
    // New in 3.0: More intelligent caching
    cache: {
      dir: '.vitest/cache'
    }
  }
});

4. Improved Test Reporting

Complete overhaul of test run reporting with reduced flicker and clearer output.

Reporter API Changes:

// Custom reporter with new lifecycle
export default class CustomReporter {
  onInit(ctx) {
    // Called once at start
  }

  onTestStart(test) {
    // More reliable test start hook
  }

  onTestComplete(test) {
    // Includes full test metadata
  }

  onFinished(files, errors) {
    // Final results with all context
  }
}

Benefits:

Less terminal flicker during test runs
Clearer test status indicators
Better error formatting
Improved progress tracking

5. Workspace Configuration Simplification

No need for separate workspace files - define projects directly in config.

Old Way (Vitest 2.x):

// vitest.workspace.js
export default ['packages/*'];

New Way (Vitest 3.0):

// vitest.config.js
export default defineConfig({
  test: {
    workspace: [
      {
        test: {
          name: 'unit',
          include: ['tests/unit/**/*.test.js']
        }
      },
      {
        test: {
          name: 'integration',
          include: ['tests/integration/**/*.test.js']
        }
      }
    ]
  }
});

6. Enhanced Browser Testing

Improved browser mode with better performance and caching.

Multiple Browser Instances:

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      instances: [
        { browser: 'chromium', name: 'chrome' },
        { browser: 'firefox', name: 'ff' },
        { browser: 'webkit', name: 'safari' }
      ]
    }
  }
});

Benefits:

Single Vite server for all browsers
Cached file processing
Parallel browser execution
Reduced startup time

7. Improved Coverage

Automatic exclusion of test files from coverage reports.

Automatic Exclusions (Vitest 3.0):

export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      // Test files automatically excluded
      // No need to manually exclude *.test.js
      exclude: [
        // Only need to specify custom exclusions
        '**/node_modules/**',
        '**/dist/**'
      ]
    }
  }
});

8. Enhanced Mocking

New spy reuse and powerful matchers.

Spy Reuse:

const spy = vi.fn();

// Vitest 3.0: Reuse spy on already mocked method
vi.spyOn(obj, 'method').mockImplementation(spy);
vi.spyOn(obj, 'method'); // Reuses existing spy

New Matchers:

// toHaveBeenCalledExactlyOnceWith
expect(mockFn).toHaveBeenCalledExactlyOnceWith(arg1, arg2);

// Ensures called exactly once with exact arguments
// Fails if called 0 times, 2+ times, or with different args

9. Project Exclusion Patterns

Exclude specific projects using negative patterns.

CLI Usage:

# Run all except integration tests
vitest run --project=!integration

# Run all except multiple projects
vitest run --project=!integration --project=!e2e

# Combine inclusion and exclusion
vitest run --project=unit --project=!slow

10. UI Improvements

Significantly enhanced test UI with better debugging and navigation.

New UI Features:

Run individual tests from UI
Automatic scroll to failed tests
Toggleable node_modules visibility
Improved filtering and search
Better test management controls
Module graph visualization

Launch UI:

vitest --ui

Best Practices for Vitest 3.x

1. Use Annotation API for Complex Tests

test('complex payment flow', async ({ task }) => {
  task.meta.annotation = {
    message: 'Tests Stripe webhook integration',
    attachments: [
      { name: 'webhook-payload', content: JSON.stringify(payload) },
      { name: 'ticket', content: 'https://jira.company.com/TICKET-123' }
    ]
  };

  // Test implementation
});

2. Leverage Line Filtering in Development

# Quick iteration on single test
vitest run src/auth.test.js:145 --watch

3. Organize with Workspace Projects

export default defineConfig({
  test: {
    workspace: [
      {
        test: {
          name: 'unit-fast',
          include: ['tests/unit/**/*.test.js'],
          environment: 'node'
        }
      },
      {
        test: {
          name: 'unit-dom',
          include: ['tests/unit/**/*.dom.test.js'],
          environment: 'happy-dom'
        }
      },
      {
        test: {
          name: 'integration',
          include: ['tests/integration/**/*.test.js'],
          setupFiles: ['tests/setup.js']
        }
      }
    ]
  }
});

4. Use toHaveBeenCalledExactlyOnceWith for Strict Testing

test('should call API exactly once with correct params', () => {
  const apiSpy = vi.spyOn(api, 'fetchUser');

  renderComponent({ userId: 123 });

  // Strict assertion - fails if called 0, 2+ times or wrong args
  expect(apiSpy).toHaveBeenCalledExactlyOnceWith(123);
});

5. Optimize Watch Mode for Large Projects

export default defineConfig({
  test: {
    watch: true,
    watchExclude: [
      '**/node_modules/**',
      '**/dist/**',
      '**/.git/**',
      '**/coverage/**'
    ],
    // Run only related tests
    changed: true,
    // Faster reruns
    isolate: false // Use with caution
  }
});

6. Custom Reporters for CI/CD

// reporters/junit-plus.js
export default class JUnitPlusReporter {
  onFinished(files, errors) {
    const results = files.map(file => ({
      name: file.name,
      tests: file.tasks.length,
      failures: file.tasks.filter(t => t.result?.state === 'fail').length,
      // Add annotations from tests
      annotations: file.tasks
        .map(t => t.meta?.annotation)
        .filter(Boolean)
    }));

    // Export to CI system
    exportToCI(results);
  }
}

// vitest.config.js
export default defineConfig({
  test: {
    reporters: ['default', './reporters/junit-plus.js']
  }
});

Migration from Vitest 2.x to 3.x

Breaking Changes

Workspace Configuration:
- Move workspace projects into main config
- Update project references
Reporter API:
- Update custom reporters to new lifecycle
- Check reporter method signatures
Browser Mode:
- Update provider syntax if using browser mode
- Review browser configuration

Migration Steps

# Update Vitest
npm install -D vitest@^3.0.0

# Update related packages
npm install -D @vitest/ui@^3.0.0
npm install -D @vitest/coverage-v8@^3.0.0

# Run tests to check for issues
npm test

# Update configs based on deprecation warnings

Performance Optimization Tips

1. Use Workspace Projects for Isolation

// Separate fast unit tests from slower integration tests
workspace: [
  {
    test: {
      name: 'unit',
      include: ['tests/unit/**'],
      environment: 'node' // Fastest
    }
  },
  {
    test: {
      name: 'integration',
      include: ['tests/integration/**'],
      environment: 'happy-dom',
      setupFiles: ['tests/setup.js']
    }
  }
]

2. Parallelize Test Execution

# Run projects in parallel
vitest run --project=unit --project=integration

# Exclude slow tests during development
vitest run --project=!e2e --project=!slow

3. Use Line Filtering for TDD

# Rapid iteration on single test
vitest run src/feature.test.js:42 --watch

4. Optimize Browser Testing

export default defineConfig({
  test: {
    browser: {
      enabled: true,
      // Reuse context for speed (less isolation)
      isolate: false,
      // Single instance for development
      instances: [{ browser: 'chromium' }]
    }
  }
});

Common Patterns

Test Annotation for Debugging

test('payment processing', async ({ task }) => {
  const startTime = Date.now();

  try {
    const result = await processPayment(data);

    task.meta.annotation = {
      message: `Completed in ${Date.now() - startTime}ms`,
      attachments: [
        { name: 'result', content: JSON.stringify(result) }
      ]
    };

    expect(result.success).toBe(true);
  } catch (error) {
    task.meta.annotation = {
      message: 'Payment processing failed',
      attachments: [
        { name: 'error', content: error.message },
        { name: 'payload', content: JSON.stringify(data) }
      ]
    };
    throw error;
  }
});

Multi-Project Testing Strategy

export default defineConfig({
  test: {
    workspace: [
      // Fast feedback loop
      {
        test: {
          name: 'unit-critical',
          include: ['tests/unit/critical/**'],
          environment: 'node'
        }
      },
      // Standard tests
      {
        test: {
          name: 'unit-standard',
          include: ['tests/unit/**'],
          exclude: ['tests/unit/critical/**'],
          environment: 'happy-dom'
        }
      },
      // Slow integration tests
      {
        test: {
          name: 'integration',
          include: ['tests/integration/**'],
          testTimeout: 30000
        }
      }
    ]
  }
});

vitest-3-features