Vitest Core Knowledge

Deep Knowledge: Use mcp__documentation__fetch_docs with technology: vitest for comprehensive documentation.

When NOT to Use This Skill

• E2E Testing - Use playwright or cypress for browser-based end-to-end tests
• React Component Testing - Combine this skill with testing-library for component tests
• Jest Migration - If project uses Jest, use jest skill instead (syntax is similar but not identical)
• API Integration Tests - Use framework-specific integration test skills (spring-boot-integration, etc.)

Basic Test

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { calculateTotal } from './utils';

describe('calculateTotal', () => {
  it('should sum array of numbers', () => {
    expect(calculateTotal([1, 2, 3])).toBe(6);
  });

  it('should return 0 for empty array', () => {
    expect(calculateTotal([])).toBe(0);
  });
});

Matchers

// Equality
expect(value).toBe(exact);
expect(value).toEqual(deepEqual);
expect(value).toMatchObject(partial);

// Truthiness
expect(value).toBeTruthy();
expect(value).toBeFalsy();
expect(value).toBeNull();
expect(value).toBeDefined();

// Numbers
expect(value).toBeGreaterThan(n);
expect(value).toBeCloseTo(0.3, 5);

// Strings
expect(str).toMatch(/pattern/);
expect(str).toContain('substring');

// Arrays
expect(arr).toContain(item);
expect(arr).toHaveLength(3);

// Errors
expect(() => fn()).toThrow();
expect(() => fn()).toThrowError('message');

Mocking

// Mock function
const mockFn = vi.fn();
mockFn.mockReturnValue(42);
mockFn.mockResolvedValue({ data: [] });

// Mock module
vi.mock('./api', () => ({
  fetchUsers: vi.fn().mockResolvedValue([])
}));

// Spy
const spy = vi.spyOn(object, 'method');
expect(spy).toHaveBeenCalledWith('arg');

// Reset
vi.clearAllMocks();
vi.resetAllMocks();

Async Tests

it('should fetch data', async () => {
  const data = await fetchUsers();
  expect(data).toHaveLength(3);
});

it('should reject', async () => {
  await expect(fetchFail()).rejects.toThrow('Error');
});

Config

// vitest.config.ts
export default defineConfig({
  test: {
    globals: true,
    environment: 'jsdom',
    coverage: { provider: 'v8', reporter: ['text', 'html'] }
  }
});

Production Readiness

Test Organization

// Proper test structure
describe('UserService', () => {
  // Setup/teardown at appropriate level
  let service: UserService;
  let mockDb: MockedObject<Database>;

  beforeAll(async () => {
    // Expensive setup once
    await setupTestDatabase();
  });

  beforeEach(() => {
    // Reset state before each test
    mockDb = vi.mocked(new Database());
    service = new UserService(mockDb);
    vi.clearAllMocks();
  });

  afterAll(async () => {
    // Cleanup
    await teardownTestDatabase();
  });

  describe('create', () => {
    it('should create user with valid data', async () => {
      // Arrange
      const input = { name: 'John', email: 'john@example.com' };
      mockDb.insert.mockResolvedValue({ id: '1', ...input });

      // Act
      const result = await service.create(input);

      // Assert
      expect(result).toMatchObject(input);
      expect(mockDb.insert).toHaveBeenCalledWith('users', input);
    });

    it('should throw on duplicate email', async () => {
      mockDb.insert.mockRejectedValue(new UniqueConstraintError());
      await expect(service.create(input)).rejects.toThrow('Email already exists');
    });
  });
});

Coverage Configuration

// vitest.config.ts
export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html', 'lcov'],
      exclude: [
        'node_modules/',
        'test/',
        '**/*.d.ts',
        '**/*.config.*',
        '**/types/**',
      ],
      thresholds: {
        lines: 80,
        functions: 80,
        branches: 75,
        statements: 80,
      },
    },
  },
});

CI Configuration

# GitHub Actions
- name: Run tests
  run: npm run test:ci

- name: Upload coverage
  uses: codecov/codecov-action@v3
  with:
    files: ./coverage/lcov.info
    fail_ci_if_error: true

// package.json scripts
{
  "scripts": {
    "test": "vitest",
    "test:ci": "vitest run --coverage --reporter=junit --outputFile=test-results.xml",
    "test:watch": "vitest --watch"
  }
}

Monitoring Metrics

Metric	Target
Line coverage	> 80%
Branch coverage	> 75%
Test execution time	< 60s
Flaky test rate	0%

Checklist

• Arrange-Act-Assert pattern
• Isolated tests (no shared state)
• Meaningful test descriptions
• Coverage thresholds enforced
• CI/CD integration
• No console.log in tests
• Mocks reset between tests
• Async tests properly awaited
• Edge cases covered
• Error paths tested

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Testing implementation details	Tests break on refactor	Test behavior, not internals
Sharing state between tests	Flaky, order-dependent tests	Use beforeEach, isolated setup
Arbitrary waits (setTimeout)	Slow, unreliable tests	Use waitFor or async utilities
Not resetting mocks	Previous test affects next	vi.clearAllMocks() in beforeEach
Testing private methods	Tight coupling to implementation	Test through public API
One giant test	Hard to debug failures	One assertion per test (ideally)
No error case tests	Production bugs slip through	Test happy path AND error paths

Quick Troubleshooting

Problem	Likely Cause	Solution
"Cannot find module"	Missing mock setup	Check vi.mock() path matches import
Test timeout	Async not awaited	Ensure all async operations use await
"Expected 0 calls, received 1"	Mock not cleared	Add vi.clearAllMocks() in beforeEach
Flaky tests	Shared state or timing	Isolate setup, avoid setTimeout
Coverage not updating	Cache issue	Run with --no-cache flag
"TypeError: vi.fn is not a function"	Missing import	Import { vi } from 'vitest'

Reference Documentation

• Mocking
• Coverage