Unit vs Integration Tests

// math.ts
export function clamp(value: number, min: number, max: number): number {
  return Math.min(Math.max(value, min), max)
}

// math.test.ts
import { describe, it, expect } from 'vitest'
import { clamp } from './math'

describe('clamp', () => {
  it('returns value when in range', () => expect(clamp(5, 1, 10)).toBe(5))
  it('clamps to min', () => expect(clamp(-5, 1, 10)).toBe(1))
  it('clamps to max', () => expect(clamp(15, 1, 10)).toBe(10))
})

// userService.ts — depends on DB and email service
export async function registerUser(email: string, password: string) {
  const user = await db.users.create({ email, password: hash(password) })
  await emailService.sendWelcome(user.email)
  return user
}

// userService.integration.test.ts
import { describe, it, expect, beforeAll, afterAll } from 'vitest'
import { db } from './db'
import { registerUser } from './userService'

// Uses a real test DB, mocks only the email service
vi.mock('./emailService', () => ({ sendWelcome: vi.fn() }))

beforeAll(async () => { await db.migrate() })
afterAll(async () => { await db.destroy() })

describe('registerUser integration', () => {
  it('persists user to DB', async () => {
    const user = await registerUser('alice@test.com', 'pass')
    const found = await db.users.findByEmail('alice@test.com')
    expect(found).toMatchObject({ email: 'alice@test.com' })
  })
})

src/
  services/
    userService.ts
    userService.unit.test.ts        # mocks DB, tests logic
    userService.integration.test.ts # real DB, tests wiring
  utils/
    format.ts
    format.test.ts                  # pure — always unit

src/
tests/
  unit/
    userService.test.ts
  integration/
    userService.test.ts

// vitest.config.ts
export default defineConfig({
  test: {
    include: ['src/**/*.unit.test.ts'],
  },
})

// vitest.integration.config.ts
export default defineConfig({
  test: {
    include: ['src/**/*.integration.test.ts'],
    testTimeout: 30_000,
    globalSetup: './tests/globalSetup.ts',
  },
})

// package.json
{
  "scripts": {
    "test:unit":        "vitest run",
    "test:integration": "vitest run --config vitest.integration.config.ts"
  }
}

// vitest.config.ts
import { defineConfig } from 'vitest/config'

export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'unit',
          include: ['**/*.unit.test.ts'],
          environment: 'node',
        },
      },
      {
        test: {
          name: 'integration',
          include: ['**/*.integration.test.ts'],
          testTimeout: 30_000,
          globalSetup: './tests/db-setup.ts',
        },
      },
    ],
  },
})

vi.mock('../db')
vi.mock('../emailService')
vi.mock('axios')

it('calls db.create with hashed password', async () => {
  vi.mocked(db.users.create).mockResolvedValue({ id: '1', email: 'a@a.com' })
  const user = await registerUser('a@a.com', 'plain')
  expect(db.users.create).toHaveBeenCalledWith(
    expect.objectContaining({ email: 'a@a.com' })
  )
})

// Don't mock the DB — that's what we're testing
// DO mock: external APIs, email, payment processors, file system
vi.mock('../emailService')
vi.mock('../stripe')

        /\
       /E2E\       — few, slow, expensive (Playwright/Cypress)
      /------\
     /Integr. \    — moderate, test wiring
    /----------\
   /   Unit     \  — many, fast, test logic
  /--------------\

// vitest.config.ts
export default defineConfig({
  test: {
    projects: [
      {
        test: {
          name: 'unit-dom',
          environment: 'jsdom',
          include: ['**/*.unit.test.tsx'],
        },
      },
      {
        test: {
          name: 'integration-node',
          environment: 'node',
          include: ['**/*.integration.test.ts'],
        },
      },
    ],
  },
})