Vitest (Testing Framework)

Overview

Vitest is a blazing fast unit test framework powered by Vite. Native TypeScript support, ESM by default, Jest-compatible API, and instant watch mode.

Version: v2.x (2024-2025)
Requirements: Node ≥18

Key Benefit: Zero config for TypeScript, uses Vite's transform pipeline, 10-20x faster than Jest.

When to Use This Skill

✅ Use Vitest when:

• Testing TypeScript code (tRPC, Zod, utilities)
• Working with Vite-based projects
• Need fast watch mode during development
• Want native ESM support
• Testing React components (with @testing-library)

❌ Consider Jest when:

• Existing Jest setup with many custom configs
• Need specific Jest ecosystem plugins
• Team unfamiliar with Vitest

Quick Start

Installation

npm install -D vitest @vitest/coverage-v8 vitest-mock-extended
npm install -D vite-tsconfig-paths  # For path aliases

Configuration

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import tsconfigPaths from 'vite-tsconfig-paths';

export default defineConfig({
  plugins: [tsconfigPaths()],
  test: {
    globals: true,              // Use describe, it, expect without imports
    environment: 'node',        // or 'jsdom' for React
    include: ['**/*.test.ts'],
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
      provider: 'v8',
      include: ['src/**/*.ts'],
      exclude: ['src/**/*.test.ts', 'src/test/**'],
    },
    mockReset: true,
    restoreMocks: true,
  },
});

TypeScript Config (for globals)

// tsconfig.json
{
  "compilerOptions": {
    "types": ["vitest/globals"]
  }
}

Scripts

// package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run",
    "test:coverage": "vitest run --coverage"
  }
}

Basic Test Structure

// src/utils/math.test.ts
import { describe, it, expect, beforeEach, afterEach } from 'vitest';
import { add, multiply } from './math';

describe('Math Utils', () => {
  describe('add', () => {
    it('should add two numbers', () => {
      expect(add(2, 3)).toBe(5);
    });

    it('should handle negative numbers', () => {
      expect(add(-1, 1)).toBe(0);
    });
  });

  describe('multiply', () => {
    it('should multiply two numbers', () => {
      expect(multiply(2, 3)).toBe(6);
    });
  });
});

Testing tRPC Procedures

Mock Context Setup

// src/test/context.ts
import { PrismaClient } from '@prisma/client';
import { mockDeep, DeepMockProxy } from 'vitest-mock-extended';

export type MockContext = {
  prisma: DeepMockProxy<PrismaClient>;
  user: { id: string; role: string } | null;
};

export const createMockContext = (user = null): MockContext => ({
  prisma: mockDeep<PrismaClient>(),
  user,
});

Testing with createCallerFactory

// src/server/routers/user.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createCallerFactory } from '../trpc';
import { userRouter } from './user';
import { createMockContext, MockContext } from '@/test/context';

describe('User Router', () => {
  let mockCtx: MockContext;
  const createCaller = createCallerFactory(userRouter);

  beforeEach(() => {
    mockCtx = createMockContext();
  });

  describe('getById', () => {
    it('should return user by id', async () => {
      const mockUser = { 
        id: '1', 
        email: 'test@example.com', 
        name: 'Test',
        role: 'USER',
        createdAt: new Date(),
        updatedAt: new Date(),
      };
      
      mockCtx.prisma.user.findUnique.mockResolvedValue(mockUser);

      const caller = createCaller(mockCtx);
      const result = await caller.getById({ id: '1' });

      expect(result).toEqual(mockUser);
      expect(mockCtx.prisma.user.findUnique).toHaveBeenCalledWith({
        where: { id: '1' },
      });
    });

    it('should throw NOT_FOUND for missing user', async () => {
      mockCtx.prisma.user.findUnique.mockResolvedValue(null);

      const caller = createCaller(mockCtx);
      
      await expect(caller.getById({ id: '1' }))
        .rejects.toThrow('NOT_FOUND');
    });
  });

  describe('create (protected)', () => {
    it('should reject unauthenticated requests', async () => {
      const caller = createCaller(mockCtx); // user is null
      
      await expect(caller.create({ 
        email: 'new@example.com', 
        name: 'New' 
      })).rejects.toThrow('UNAUTHORIZED');
    });

    it('should create user when authenticated', async () => {
      mockCtx = createMockContext({ id: 'admin', role: 'ADMIN' });
      const mockUser = { id: '2', email: 'new@example.com', name: 'New' };
      mockCtx.prisma.user.create.mockResolvedValue(mockUser);

      const caller = createCaller(mockCtx);
      const result = await caller.create({ 
        email: 'new@example.com', 
        name: 'New' 
      });

      expect(result).toEqual(mockUser);
    });
  });
});

Testing Zod Schemas

// src/schemas/user.schema.test.ts
import { describe, it, expect } from 'vitest';
import { CreateUserSchema, EmailSchema } from './user.schema';

describe('CreateUserSchema', () => {
  it('should validate correct input', () => {
    const result = CreateUserSchema.safeParse({
      email: 'test@example.com',
      name: 'Test User',
      password: 'SecurePass123',
    });
    
    expect(result.success).toBe(true);
    if (result.success) {
      expect(result.data.email).toBe('test@example.com');
    }
  });

  it('should reject invalid email', () => {
    const result = CreateUserSchema.safeParse({
      email: 'invalid-email',
      name: 'Test',
      password: 'SecurePass123',
    });
    
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(result.error.issues[0].path).toEqual(['email']);
    }
  });

  it('should reject short password', () => {
    const result = CreateUserSchema.safeParse({
      email: 'test@example.com',
      name: 'Test',
      password: '123',
    });
    
    expect(result.success).toBe(false);
    if (!result.success) {
      expect(result.error.issues[0].path).toEqual(['password']);
    }
  });
});

describe('EmailSchema', () => {
  it.each([
    ['test@example.com', true],
    ['user.name@domain.org', true],
    ['invalid', false],
    ['@missing.com', false],
    ['no-domain@', false],
  ])('should validate "%s" as %s', (email, expected) => {
    const result = EmailSchema.safeParse(email);
    expect(result.success).toBe(expected);
  });
});

Mocking Patterns

Mock Functions

import { vi, describe, it, expect } from 'vitest';

// Mock a function
const mockFn = vi.fn();
mockFn.mockReturnValue(42);
mockFn.mockResolvedValue(42);      // For async
mockFn.mockRejectedValue(new Error('fail'));

// Verify calls
expect(mockFn).toHaveBeenCalled();
expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
expect(mockFn).toHaveBeenCalledTimes(1);

Mock Modules

import { vi, describe, it, expect } from 'vitest';

// Mock entire module
vi.mock('@/lib/email', () => ({
  sendEmail: vi.fn().mockResolvedValue({ success: true }),
}));

import { sendEmail } from '@/lib/email';

it('should send email', async () => {
  await sendEmail('test@example.com', 'Subject', 'Body');
  expect(sendEmail).toHaveBeenCalled();
});

Spy on Methods

import { vi, describe, it, expect } from 'vitest';

const obj = {
  method: () => 'original',
};

const spy = vi.spyOn(obj, 'method');
spy.mockReturnValue('mocked');

expect(obj.method()).toBe('mocked');
expect(spy).toHaveBeenCalled();

spy.mockRestore(); // Restore original

Test Boundaries

Setup Files

// src/test/setup.ts
import { beforeAll, afterAll, afterEach } from 'vitest';

// Global setup
beforeAll(async () => {
  // Connect to test database, etc.
});

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

afterEach(() => {
  // Reset mocks between tests
});

Common Assertions

// Equality
expect(value).toBe(exact);           // ===
expect(value).toEqual(deepEqual);    // Deep equality
expect(value).toStrictEqual(strict); // Including undefined props

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

// Numbers
expect(value).toBeGreaterThan(3);
expect(value).toBeLessThanOrEqual(10);
expect(value).toBeCloseTo(0.3, 5);   // Float precision

// Strings
expect(value).toMatch(/regex/);
expect(value).toContain('substring');

// Arrays/Objects
expect(array).toContain(item);
expect(array).toHaveLength(3);
expect(object).toHaveProperty('key', 'value');

// Errors
expect(() => fn()).toThrow();
expect(() => fn()).toThrow('message');
await expect(asyncFn()).rejects.toThrow();

Rules

Do ✅

• Use describe blocks to organize related tests
• Use beforeEach for fresh mock context
• Mock external dependencies (DB, APIs)
• Test edge cases and error paths
• Use it.each for parameterized tests
• Keep unit tests fast and isolated

Avoid ❌

• Testing implementation details
• Skipping error case tests
• Sharing mutable state between tests
• Over-mocking (test real logic)
• Tests that depend on other tests

Troubleshooting

"Cannot find module":
  → Check vite-tsconfig-paths plugin
  → Verify path aliases in tsconfig
  → Restart Vitest

"Mock not working":
  → Ensure vi.mock() is at top level (hoisted)
  → Check mockReset/restoreMocks in config
  → Use vi.mocked() for type inference

"Async test timeout":
  → Increase timeout: it('test', async () => {}, 10000)
  → Check for unresolved promises
  → Verify mocks return resolved values

"Coverage not accurate":
  → Use v8 provider (faster, more accurate)
  → Exclude test files from coverage
  → Run with --coverage flag

File Structure

src/
├── server/routers/
│   ├── user.ts
│   └── user.test.ts      # Co-located tests
├── schemas/
│   ├── user.schema.ts
│   └── user.schema.test.ts
├── utils/
│   ├── helpers.ts
│   └── helpers.test.ts
└── test/
    ├── setup.ts          # Global setup
    └── context.ts        # Mock context factory

vitest.config.ts          # Vitest configuration

References

• https://vitest.dev — Official documentation
• https://vitest.dev/api — API reference
• https://vitest.dev/guide/mocking — Mocking guide