josiahsiegel 🚨 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
}
}
]
}
});