vitest

Vitest Testing Framework

Instructions

1. Assess the project: Vitest is ideal for Vite-based projects and ESM-first codebases.
2. Follow Vitest conventions:
   • Test files: *.test.ts, *.spec.ts
   • API is Jest-compatible but with modern ESM imports
   • Leverages Vite's transform pipeline for fast tests
3. Provide complete examples: Include proper ESM imports and TypeScript types.
4. Highlight Vitest features: In-source testing, browser mode, UI.
5. Guide on migration: Help users migrating from Jest.

Test Structure

import { describe, it, expect, beforeEach, vi } from 'vitest';
import { myFunction } from './myModule';

describe('myFunction', () => {
  beforeEach(() => {
    vi.clearAllMocks();
  });

  it('should return expected value', () => {
    expect(myFunction('input')).toBe('output');
  });

  it('should handle async operations', async () => {
    const result = await myFunction('async');
    expect(result).toBe('done');
  });
});

Mocking with vi

Mock a module

vi.mock('./database', () => ({
  query: vi.fn().mockResolvedValue([{ id: 1 }]),
}));

Mock a function

const mockFn = vi.fn((x: number) => x + 1);
expect(mockFn(1)).toBe(2);
expect(mockFn).toHaveBeenCalledWith(1);

Spy on methods

const spy = vi.spyOn(object, 'method');
object.method();
expect(spy).toHaveBeenCalled();
spy.mockRestore();

Mock timers

vi.useFakeTimers();
setTimeout(callback, 1000);
vi.advanceTimersByTime(1000);
expect(callback).toHaveBeenCalled();
vi.useRealTimers();

Mock globals

vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
  json: () => Promise.resolve({ data: 'mocked' }),
}));

In-Source Testing

Vitest supports tests directly in source files:

// src/utils.ts
export function add(a: number, b: number): number {
  return a + b;
}

if (import.meta.vitest) {
  const { describe, it, expect } = import.meta.vitest;

  describe('add', () => {
    it('adds two numbers', () => {
      expect(add(1, 2)).toBe(3);
    });
  });
}