typescript-vitest

name	typescript-vitest
description	Use when writing tests, setting up test infrastructure, creating mocks, or configuring Vitest in TypeScript projects. Covers test organization, mocking patterns, assertions, and test utilities.

Vitest Testing

Use Vitest as the test runner for all TypeScript projects.

Setup

Dependencies

npm install -D vitest @vitest/coverage-v8

Configuration (vitest.config.ts)

import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    pool: 'forks',
    poolOptions: {
      forks: {
        singleFork: true,
      },
    },
    maxConcurrency: 2,
    testTimeout: 20_000,
    slowTestThreshold: 10_000,
    bail: 1,
    coverage: {
      provider: 'v8',
    },
    expandSnapshotDiff: true,
  },
})

With Path Aliases

If the project uses TypeScript path aliases (e.g., ~/), add resolve:

import { defineConfig } from 'vitest/config'
import { resolve } from 'path'

export default defineConfig({
  resolve: {
    alias: {
      '~': resolve(__dirname, 'src'),
    },
  },
  test: {
    // ...
  },
})

Test File Organization

Naming Convention

• Unit tests: *.test.ts — colocated next to the source file
• Integration/E2E tests: *.e2e.test.ts or placed in a tests/ directory

Directory Structure

src/
  feature/
    feature.ts
    feature.test.ts        # unit test next to source
  tests/
    mocks/                 # shared mock utilities
      mock-server.ts
      mock-data.ts
    helpers/               # test helpers
      setup.ts
    integration/           # integration tests
      api.e2e.test.ts

Writing Tests

Basic Structure

import { describe, it, expect, beforeEach, afterEach } from 'vitest'

describe('FeatureName', () => {
  beforeEach(() => {
    // setup
  })

  afterEach(() => {
    // cleanup
  })

  it('should do expected behavior', () => {
    const result = doSomething()
    expect(result).toBe(expected)
  })

  it('should handle edge case', () => {
    expect(() => doSomething(badInput)).toThrow('Expected error message')
  })
})

Test Naming

Use descriptive names that explain the behavior, not the implementation:

// Good
it('should return empty array when no items match filter')
it('should throw when connection string is invalid')
it('should retry failed requests up to 3 times')

// Bad
it('test filter')
it('error case')
it('works')

Assertions

Prefer Specific Matchers

// Equality
expect(value).toBe(exact)              // strict ===
expect(obj).toEqual(expected)          // deep equality
expect(obj).toMatchObject(partial)     // partial match

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

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

// Strings
expect(str).toContain('substring')
expect(str).toMatch(/regex/)

// Arrays
expect(arr).toHaveLength(3)
expect(arr).toContain(item)
expect(arr).toEqual(expect.arrayContaining([a, b]))

// Errors
expect(() => fn()).toThrow()
expect(() => fn()).toThrow('specific message')
expect(() => fn()).toThrow(CustomError)

// Async
await expect(asyncFn()).resolves.toBe(value)
await expect(asyncFn()).rejects.toThrow('error')

Inline Snapshots

Use inline snapshots for complex output verification:

expect(formatOutput(data)).toMatchInlineSnapshot(`
  "expected output here"
`)

Mocking

Module Mocks

import { vi } from 'vitest'

// Mock entire module
vi.mock('./database', () => ({
  query: vi.fn().mockResolvedValue([]),
  connect: vi.fn(),
}))

// Mock with factory (auto-mocked)
vi.mock('./config')

Function Spies

const spy = vi.fn()
spy.mockReturnValue(42)
spy.mockResolvedValue(data)
spy.mockImplementation((x) => x * 2)

expect(spy).toHaveBeenCalled()
expect(spy).toHaveBeenCalledWith('arg1', 'arg2')
expect(spy).toHaveBeenCalledTimes(3)

Mock HTTP Server (Integration Tests)

For testing HTTP clients or APIs, create a mock server utility:

import { createServer, Server, IncomingMessage, ServerResponse } from 'http'

type MockResponse =
  | { statusCode: 200; body: unknown }
  | { statusCode: 204 }
  | { statusCode: 400 | 404 | 500 | 503; body?: unknown }

export function createMockServer(responses: MockResponse[]) {
  let callIndex = 0
  const calls: { method: string; url: string; body: string }[] = []

  const server = createServer(async (req: IncomingMessage, res: ServerResponse) => {
    const body = await readBody(req)
    calls.push({ method: req.method!, url: req.url!, body })

    const mock = responses[callIndex++]
    if (!mock) {
      res.writeHead(500)
      res.end('No more mock responses')
      return
    }

    res.writeHead(mock.statusCode, { 'Content-Type': 'application/json' })
    if ('body' in mock && mock.body !== undefined) {
      res.end(JSON.stringify(mock.body))
    } else {
      res.end()
    }
  })

  return {
    start: () => new Promise<string>((resolve) => {
      server.listen(0, () => {
        const addr = server.address() as { port: number }
        resolve(`http://localhost:${addr.port}`)
      })
    }),
    close: () => new Promise<void>((resolve) => server.close(() => resolve())),
    calls,
  }
}

Timer Mocks

beforeEach(() => {
  vi.useFakeTimers()
})

afterEach(() => {
  vi.useRealTimers()
})

it('should debounce calls', async () => {
  trigger()
  vi.advanceTimersByTime(500)
  expect(handler).toHaveBeenCalledTimes(1)
})

Test Utilities

Shared Setup

Create reusable test fixtures:

// tests/helpers/setup.ts
export function createTestContext() {
  const logger = pino({ level: 'silent' })
  const db = createTestDatabase()

  return {
    logger,
    db,
    async cleanup() {
      await db.close()
    },
  }
}

Database Test Patterns

describe('UserRepository', () => {
  let ctx: TestContext

  beforeEach(async () => {
    ctx = await createTestContext()
  })

  afterEach(async () => {
    await ctx.cleanup()
  })

  it('should create user', async () => {
    const user = await ctx.db.users.create({ name: 'Test' })
    expect(user.id).toBeDefined()
  })
})

Environment Variables in Tests

import { vi } from 'vitest'

beforeEach(() => {
  vi.stubEnv('DATABASE_URL', 'postgres://localhost:5432/test')
})

afterEach(() => {
  vi.unstubAllEnvs()
})

Package.json Scripts

{
  "scripts": {
    "test": "vitest run",
    "test:watch": "vitest",
    "test:coverage": "vitest run --coverage"
  }
}