TypeScript 测试策略：单元测试、类型测试与测试替身实战

pnpm add -D vitest
# 无需额外配置，vitest 直接识别 TS

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

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

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

// package.json
{
  "scripts": {
    "test": "vitest",
    "test:run": "vitest run"   // CI 一次性运行
  }
}

co-located（推荐）：测试与被测文件同目录
  src/sum.ts
  src/sum.test.ts
集中式：__tests__/ 目录

Vitest 默认匹配 *.test.ts / *.spec.ts

类型检查（tsc）只保证「代码和类型一致」，不保证「类型符合业务预期」
例：一个泛型函数本该返回「输入对象去掉 id 字段」，但实现可能返回了多余字段——
    tsc 不报错，因为实现自己定义了自己的返回类型
类型测试 = 断言「这个类型恰好等于那个类型」，把类型错误也变成测试

import { expectTypeOf, expect } from 'vitest'

// 断言函数返回类型
const result = processUser({ id: 1, name: 'Alice' })
expectTypeOf(result).toEqualTypeOf<{ name: string }>()  // 恰好相等

// 断言泛型推导
expectTypeOf(pick<{ a: number; b: string }, 'a'>({ a: 1, b: 'x' }))
  .toEqualTypeOf<{ a: number }>()

// 断言可赋值性（宽松）
expectTypeOf(value).toMatchTypeOf<number>()

import { expectTypeOf } from 'vitest'

// 验证自定义工具类型行为
type MyReturnType<T extends (...args: any[]) => any> =
  T extends (...args: any[]) => infer R ? R : never

expectTypeOf<MyReturnType<() => string>>().toEqualTypeOf<string>()
expectTypeOf<MyReturnType<(x: number) => boolean>>().toEqualTypeOf<boolean>()

1. 自定义工具类型 / 类型体操（泛型、条件类型）
2. 公共 API 的类型契约（库作者）
3. 复杂的泛型推导（如类型安全 API）
4. 重构类型定义时防止回归

// index.test-d.ts
import { expectType, expectError, expectAssignable } from 'tsd'
import { processUser } from '.'

// 断言类型恰好
expectType<string>(processUser({ id: 1 }).name)
// 断言「应报错」的用法
expectError(processUser({ id: 'not-number' }))
// 断言可赋值
expectAssignable<{ name: string }>(processUser({ id: 1 }))

// 测试一个「只读类型」工具
import { expectType, expectError } from 'tsd'

type ReadonlyDeep<T> = {
  readonly [K in keyof T]: T[K] extends object ? ReadonlyDeep<T[K]> : T[K]
}

type Source = { a: number; nested: { b: string } }
type Readonly = ReadonlyDeep<Source>

expectType<Readonly<Readonly>>(readonlyValue)   // 可赋值
expectError(readonlyValue.a = 2)                 // 只读属性不可写 → 编译失败

expect-type（Vitest 内嵌）：适合「项目内类型断言」，与测试无缝
tsd：面向「库作者」，验证对外 .d.ts 契约，含 expectError（反例断言）
组合：项目内用 expectTypeOf，发布库用 tsd

describe('checkout', () => {
  it('calculates total with shipping', () => {
    // Arrange：准备输入与依赖
    const cart = buildCart({ items: 2, weight: 5 })
    // Act：执行被测单元
    const total = calculateTotal(cart)
    // Assert：断言结果
    expect(total).toBe(price(2) + shipping(5))
  })
})

// 精确匹配（优先）
expect(result).toBe(42)
expect(result).toEqual({ id: 1, tags: ['a'] })
// 对象部分匹配
expect(customer).toMatchObject({ name: 'Alice' })
// 数组/集合
expect(tags).toContain('ts')
expect(users).toHaveLength(3)
// 异常
expect(() => parse('bad')).toThrowError('invalid json')

坏：一个 it 里测了「校验+计算+落库」三个行为
好：拆成 3 个 it，失败时精确定位
命名：it('throws when amount is negative')（行为描述而非实现）

import { vi } from 'vitest'

// 替换模块（模块级 Mock）
vi.mock('./payment-service', () => ({
  charge: vi.fn().mockResolvedValue({ success: true })
}))

// 单函数 Mock
const chargeMock = vi.fn().mockResolvedValue({ success: true })

// Spy 真实对象
const dbSpy = vi.spyOn(db, 'save').mockImplementation(async () => {})

// 断言调用
expect(chargeMock).toHaveBeenCalledTimes(1)
expect(chargeMock).toHaveBeenCalledWith(99.9, 'card-1')

过度 Mock 的坏处：测试「证明 Mock 行为」而非「真实逻辑」
原则：
  1. 只 Mock 边界（网络/数据库/时间）
  2. 业务逻辑尽量真实执行
  3. 集成测试（真实依赖）与单元测试（Mock 边界）分层

// 测试数据工厂：默认值 + 可覆盖
export function makeUser(overrides: Partial<User> = {}): User {
  return {
    id: 1,
    name: 'Alice',
    email: 'alice@example.com',
    role: 'user',
    ...overrides,          // 覆盖默认
  }
}

// 使用
const admin = makeUser({ role: 'admin' })
const weird = makeUser({ name: '', email: 'bad' })  // 构造边界数据

class UserBuilder {
  private user: User = makeUser()
  withName(name: string) { this.user = { ...this.user, name }; return this }
  withEmail(email: string) { this.user = { ...this.user, email }; return this }
  build(): User { return this.user }
}

const u = new UserBuilder().withName('Bob').withEmail('bob@x.com').build()

1. 默认值让「只改关心的字段」
2. 集中管理构造，字段变更一处改
3. 类型安全（overrides 用 Partial<User> 限制）
4. 边界数据可复现

it('fetches user', async () => {
  const user = await fetchUser(1)
  expect(user.name).toBe('Alice')
})

// 多个异步并行
it('loads parallel', async () => {
  const [a, b] = await Promise.all([fetchA(), fetchB()])
  expect(a + b).toBe(3)
})

import { vi } from 'vitest'

it('debounces', () => {
  vi.useFakeTimers()
  const fn = vi.fn()
  const debounced = debounce(fn, 500)
  debounced()
  vi.advanceTimersByTime(500)
  expect(fn).toHaveBeenCalledTimes(1)
  vi.useRealTimers()
})

并发测试（test.concurrent）共享状态 → 小心全局/模块级状态
原则：测试间不共享可变状态；用 beforeEach 重置

vitest run --coverage

// vitest.config.ts
export default defineConfig({
  test: {
    coverage: {
      provider: 'v8',          // 或 istanbul
      include: ['src/**'],
      thresholds: { lines: 80, functions: 80, branches: 70 }
    }
  }
})

覆盖率是「探索盲区」的线索，不是质量目标本身
  高覆盖率 + 弱断言 ≠ 好测试
更重要的指标：关键路径覆盖、异常分支覆盖、类型契约测试

# GitHub Actions 示例
name: test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - run: pnpm install
      - run: pnpm typecheck       # 类型检查
      - run: pnpm test:run         # 测试
      - run: pnpm test:run --coverage  # 覆盖率门禁

CI 中「tsc 类型检查」与「vitest 测试」分开跑
  typecheck：防类型回归（快）
  test      ：防逻辑回归（较慢）
合并示例：pnpm typecheck && pnpm test:run

先用类型定义「函数契约」→ 类型即测试蓝图
  1. 写函数签名（参数类型、返回类型）
  2. 写类型测试断言（expectTypeOf）
  3. 再实现逻辑 + 行为测试
类型契约先行 → 行为测试围绕契约写

type Result<T> = { ok: true; data: T } | { ok: false; error: string }

// 类型收窄后测试每种分支
expectTypeOf(result).toEqualTypeOf<Result<number>>()

function unwrap<T>(r: Result<T>): T {
  if (r.ok) return r.data
  throw new Error(r.error)
}
// 测试：ok 分支返回 data，error 分支抛错

良好的类型契约（判别联合、泛型约束、字面量类型）本身就是「可编译的文档」
测试验证：契约符合预期 + 行为符合契约