测试与代码质量

1.1 没有测试的代码，只证明「当前能跑」

软件的本质是「变化」。需求会变、框架会升、人会走。没有测试保护的代码，每改一行都要靠手动点页面验证，改动越大、回归成本越高，最后所有人都不敢动老代码——代码就「腐烂」了。测试的核心价值有三条：

• 回归保护：重构、升级依赖、加功能时，测试替你确认「旧的没坏」。
• 设计反馈：写测试时发现代码难以测试，往往是耦合过深、职责不清的信号——测试是免费的设计评审。
• 文档作用：一个测试就是一份「这个函数/组件应该怎么用、什么输入什么输出」的可执行文档。

1.2 测试金字塔（以及它的进化版：测试奖杯）

经典金字塔主张「底层多、顶层少」。Kent C. Dodds 提出「测试奖杯」：把集成测试放在最重要的位置——因为用户交互的大多数 bug 出在「模块协作」这一层，而不是单个函数内部。两种模型不冲突：你的绝大多数业务逻辑应该用单元测试兜底，但「这个页面能不能正常完成一次操作」必须靠组件/集成测试覆盖。

1.3 测试替身（Test Double）：Dummy / Fake / Stub / Spy / Mock

测试时我们要隔离外部依赖（网络、数据库、定时器）。「替身」有五种，用错会写出脆弱的测试：

2.1 环境搭建（Vitest 为例，Vite 项目原生友好）

# 安装
npm i -D vitest @vitest/coverage-v8

// vite.config.ts 里加配置
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',        // 组件测试需要 DOM 环境
    globals: true,            // 直接写 describe/it，不用 import
    setupFiles: ['./src/test/setup.ts'],
    coverage: {
      provider: 'v8',
      include: ['src/**/*.{ts,tsx}'],
      exclude: ['src/**/*.test.*', 'src/main.tsx', 'src/types/**'],
      thresholds: { lines: 80, functions: 80, branches: 75, statements: 80 },
    },
  },
})

package.json 脚本："test": "vitest"、"test:coverage": "vitest run --coverage"。

2.2 第一个测试：断言匹配器要背熟

被测代码——一个带边界条件的金额格式化函数：

// src/utils/money.ts
export function formatMoney(amount: number, currency = 'CNY'): string {
  if (!Number.isFinite(amount)) throw new Error('amount must be a finite number')
  const sign = amount < 0 ? '-' : ''
  const abs = Math.abs(amount)
  const [int, dec] = abs.toFixed(2).split('.')
  const grouped = int.replace(/\B(?=(\d{3})+(?!\d))/g, ',')
  return `${sign}${grouped}.${dec} ${currency}`
}

// src/utils/money.test.ts
import { describe, it, expect } from 'vitest'
import { formatMoney } from './money'

describe('formatMoney', () => {
  it('普通金额：千分位 + 两位小数', () => {
    expect(formatMoney(1234567.8)).toBe('1,234,567.80 CNY')
  })
  it('负数保留符号', () => {
    expect(formatMoney(-42.5)).toBe('-42.50 CNY')
  })
  it('整数补零', () => {
    expect(formatMoney(5)).toBe('5.00 CNY')
  })
  it('非法输入抛错', () => {
    expect(() => formatMoney(NaN)).toThrow('finite number')
  })
})

高频匹配器清单（Vitest 与 Jest 完全一致）：

2.3 异步测试：定时器、Promise、时间

测异步有三种场景，写法完全不同：

// 场景一：Promise 异步
async function fetchUser(id: number) {
  const res = await fetch(`/api/user/${id}`)
  if (!res.ok) throw new Error('fetch failed')
  return res.json()
}

it('成功返回用户', async () => {
  // 用 .resolves/.rejects 避免 try/catch 迷宫
  await expect(fetchUser(1)).resolves.toEqual({ id: 1, name: 'Tom' })
})

it('失败抛错', async () => {
  await expect(fetchUser(999)).rejects.toThrow('fetch failed')
})

// 场景二：假定时器（防抖、轮询）
vi.useFakeTimers()
it('debounce 只在停止输入后触发', () => {
  const fn = vi.fn()
  const debounced = debounce(fn, 300)
  debounced(); debounced(); debounced()
  expect(fn).not.toHaveBeenCalled()          // 300ms 内不触发
  vi.advanceTimersByTime(299)
  expect(fn).not.toHaveBeenCalled()
  vi.advanceTimersByTime(1)
  expect(fn).toHaveBeenCalledTimes(1)        // 只触发一次
  vi.useRealTimers()
})

2.4 Mock 三种粒度：函数 / 模块 / 全局

// 1) 函数级：vi.fn / vi.spyOn
const logger = vi.fn()
logger('hello', 42)
expect(logger).toHaveBeenCalledWith('hello', 42)

// 2) 模块级：替换整个依赖模块
vi.mock('./api', () => ({
  fetchUser: vi.fn().mockResolvedValue({ id: 1, name: 'Tom' }),
}))

// 3) 全局级：拦截 fetch（组件测试常用）
vi.stubGlobal('fetch', vi.fn(() =>
  Promise.resolve(new Response(JSON.stringify({ ok: true }), { status: 200 }))
))

2.5 覆盖率：看懂四个数字

3.1 三个 API 的区别：render / fireEvent / userEvent

// npm i -D @testing-library/react @testing-library/user-event @testing-library/jest-dom
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'

it('点击按钮后显示问候语', async () => {
  render(<GreetForm />)
  const input = screen.getByLabelText('你的名字')   // 按 label 找输入框
  await userEvent.type(input, '小明')            // 模拟真实逐键输入
  await userEvent.click(screen.getByRole('button', { name: '提交' }))
  expect(screen.getByText('你好，小明')).toBeInTheDocument()
})

• render：把组件挂到测试用的 DOM。
• userEvent：模拟「真实用户」——它自动处理聚焦、按键序列、事件组合（click 会先触发 mousedown/mouseup）。永远优先 userEvent，fireEvent 只是底层逃生门。
• screen：全局查询对象，不用把 render 的返回值传来传去。

3.2 查询优先级：从最像用户的方式开始

1. getByRole（按钮、标题、链接都带语义角色）——最接近无障碍视角，首选。
2. getByLabelText——表单输入框。
3. getByPlaceholderText——只有 placeholder 的输入框。
4. getByText——非交互文本。
5. getByTestId——最后的手段，相当于给元素起测试专用名（data-testid）。

3.3 异步加载组件测试 + MSW 拦截真实请求

测「组件 + API」的协作，正确姿势是 MSW（Mock Service Worker）：它在网络层拦截请求，组件里真的调用 fetch，但数据是假的——测试覆盖的是「真实链路」，而不是「mock 过的调用」。

// src/test/server.ts —— 建立 MSW 服务
import { setupServer } from 'msw/node'
import { http, HttpResponse } from 'msw'

export const server = setupServer(
  http.get('/api/users', () => HttpResponse.json([
    { id: 1, name: 'Alice' },
    { id: 2, name: 'Bob' },
  ])),
)

// src/test/setup.ts —— 全局启停
import { server } from './server'

beforeAll(() => server.listen())
afterEach(() => server.resetHandlers())   // 清掉单测里覆盖的 handler
afterAll(() => server.close())

// UserList.test.tsx
it('加载后展示用户列表', async () => {
  render(<UserList />)
  expect(screen.getByText('加载中…')).toBeInTheDocument()   // 初始 loading
  expect(await screen.findByText('Alice')).toBeInTheDocument() // 等待异步结果
  expect(screen.getByText('Bob')).toBeInTheDocument()
})

it('接口失败时显示错误并可以重试', async () => {
  server.use(http.get('/api/users', () => HttpResponse.error()))  // 单测级覆盖
  render(<UserList />)
  expect(await screen.findByText('加载失败')).toBeInTheDocument()
})

3.4 快照测试：用，但只在「纯展示」场景

expect(renderer.create(<Badge kind="danger">删除</Badge>).toJSON()).toMatchSnapshot()

4.1 Playwright 快速上手

# 安装（自带浏览器下载）
npm i -D @playwright/test
npx playwright install chromium

// playwright.config.ts
import { defineConfig } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  timeout: 30_000,
  use: {
    baseURL: 'http://localhost:5173',
    trace: 'on-first-retry',   // 失败自动留 trace，可回放每一步
  },
  projects: [
    { name: 'chromium', use: { browserName: 'chromium' } },
    { name: 'mobile', use: { browserName: 'chromium', viewport: { width: 390, height: 844 } } },
  ],
  webServer: {
    command: 'npm run dev',        // 测试前自动起服务
    port: 5173,
    reuseExistingServer: !process.env.CI,
  },
})

4.2 一条黄金路径测试：搜索 → 加入购物车 → 下单

// e2e/checkout.spec.ts
import { test, expect } from '@playwright/test'

test('用户能完成一次完整购买', async ({ page }) => {
  await page.goto('/')

  // 搜索（用 getByRole 而不是 CSS 选择器）
  await page.getByRole('searchbox').fill('机械键盘')
  await page.getByRole('button', { name: '搜索' }).click()

  // 等待结果出现（自动重试，代替手工 sleep）
  await page.getByText('机械键盘 87 键').click()

  await page.getByRole('button', { name: '加入购物车' }).click()
  await page.getByRole('link', { name: '去结算' }).click()

  // 断言最终结果
  await expect(page.getByText('订单提交成功')).toBeVisible()
})

4.3 E2E 的数量与时机

• 数量：一个团队维护 20～50 条黄金路径已经是极限，再多就变成「维护测试」而不是「用测试」。
• 时机：关键流程（登录、支付、数据导出）必须覆盖；营销页、后台管理页这类低风险页面不值得 E2E。
• CI：E2E 放 merge 后的流水线（或 nightly），别放每次 push——分钟级的等待会让大家开始绕过它。

5.1 TDD 循环与它的真正价值

1. 红（Red）：先写一个会失败的测试（描述期望行为）。
2. 绿（Green）：写最简实现让测试通过——不追求优雅，只求通过。
3. 重构（Refactor）：在测试保护下清理代码，让设计变好。

TDD 的价值不是「测试多」，而是倒逼你先想清楚行为：写测试之前你得定义「输入是什么、输出是什么、边界在哪」。这个思考过程本身就在帮你做接口设计——很多人在写测试时才发现「这个函数职责太杂了，没法测」，于是拆开，代码反而变好了。

5.2 一个完整 TDD 示例：购物车折扣计算

// 第 1 步：先写测试（红）
import { calcDiscount } from './cart'

describe('calcDiscount', () => {
  it('满 100 减 10', () => expect(calcDiscount(100)).toBe(10))
  it('满 300 减 50', () => expect(calcDiscount(300)).toBe(50))
  it('满 500 减 100', () => expect(calcDiscount(500)).toBe(100))
  it('不满 100 不减', () => expect(calcDiscount(99)).toBe(0))
  it('边界：刚好 100 也减', () => expect(calcDiscount(100)).toBe(10))
})

// 第 2 步：最简实现（绿）—— 先把测试跑过
export function calcDiscount(total: number): number {
  if (total >= 500) return 100
  if (total >= 300) return 50
  if (total >= 100) return 10
  return 0
}

// 第 3 步：重构 —— 用查表法消除重复的阶梯 if
const TIERS: Array<[min: number, discount: number]> = [
  [500, 100], [300, 50], [100, 10],
]
export function calcDiscount(total: number): number {
  for (const [min, discount] of TIERS) {
    if (total >= min) return discount
  }
  return 0
}

6.1 三层防线各自管什么

6.2 值得单独立规则的 ESLint 配置

// eslint.config.js（flat config）
import js from '@eslint/js'
import reactHooks from 'eslint-plugin-react-hooks'
import reactRefresh from 'eslint-plugin-react-refresh'
import tseslint from 'typescript-eslint'
import prettier from 'eslint-config-prettier'

export default tseslint.config(
  { ignores: ['dist', 'coverage', 'node_modules'] },
  js.configs.recommended,
  ...tseslint.configs.recommended,
  {
    files: ['**/*.{ts,tsx}'],
    plugins: { 'react-hooks': reactHooks, 'react-refresh': reactRefresh },
    rules: {
      ...reactHooks.configs.recommended.rules,   // 含 rules-of-hooks、exhaustive-deps
      'react-refresh/only-export-components': 'warn',
      '@typescript-eslint/no-explicit-any': 'warn',   // any 是烟雾弹，留下警告
      '@typescript-eslint/consistent-type-imports': 'error',
    },
  },
  prettier,
)

6.3 TypeScript：把「可能出错的运行时」变成「编译期」

// tsconfig.json 里这些开关一定要开
{
  "compilerOptions": {
    "strict": true,
    "noUncheckedIndexedAccess": true,   // arr[i] 可能是 undefined
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true
  }
}

用 type 表达可能性，而不是用 any 逃避：

// 坏：any 把类型错误推到运行时
function getFirst(items: any[]) { return items[0] }

// 好：把「可能没有」写进类型，调用方被迫处理
function getFirst<T>(items: T[]): T | undefined { return items[0] }
const user = getFirst(users)          // user: User | undefined
if (user) { /* 这里才是安全的访问点 */ }

6.4 Git Hooks：让质量检查自动发生

// 用 husky + lint-staged 只检查暂存区，快且不烦人
npm i -D husky lint-staged
npx husky init

// .lintstagedrc.json
{
  "*.{ts,tsx,js,jsx}": ["eslint --fix", "prettier --write"],
  "*.{json,md,css,html}": ["prettier --write"]
}

// .husky/pre-commit（lint-staged 处理暂存文件）
npx lint-staged

// .husky/pre-push（提交前跑全量测试 + 类型检查）
npm run typecheck && npm run test:run

7.1 评审看什么：一份可执行的检查清单

7.2 提意见的艺术：对事不对人

• 用「提问」代替「命令」：「这里写错了」 → 「这里如果 list 是空数组会发生什么？我们考虑过这个情况吗？」
• 区分意见等级：Blocking（必须改，否则线上有风险）/ Should（建议，明显更好）/ Nit（风格小点，不改也行）。等级不清，作者无法判断轻重。
• 先肯定后建议：评审不是批斗会，指出好的设计同样重要——那是团队标准的来源。
• 小 PR 原则：单个 PR 尽量 < 400 行，超过就拆。评审质量随 PR 变大急剧下降。

8.1 重构的时机与前提

• 时机（三过原则）：同样的代码出现第三次时（Rule of Three）就该抽出来了；改功能时顺手重构（童子军原则：离开时比来时干净）；大重构配专项，别夹带在功能 PR 里。
• 前提：目标代码有测试保护。没有测试？先写「特征测试」（characterization test）——记录当前行为，再动手。
• 节奏：一步一测，每次改完立刻跑测试，红了就回滚这一步。重构不是「一次性大改」，是几十个安全的小步。

8.2 四个最高频的重构手法

// ① 提取函数（Extract Function）：把「一段有名字的意图」抽出来
// 重构前
function sendInvoice(user: User) {
  const lines = user.orders.map(o => `${o.name} x${o.qty}: ¥${o.total}`)
  const total = user.orders.reduce((s, o) => s + o.total, 0)
  email(user.email, ['=== 账单 ===', ...lines, `合计: ¥${total}`].join('\n'))
}

// 重构后：账单组装有自己的名字，可单独测试
function buildInvoiceText(user: User): string {
  const lines = user.orders.map(o => `${o.name} x${o.qty}: ¥${o.total}`)
  const total = user.orders.reduce((s, o) => s + o.total, 0)
  return ['=== 账单 ===', ...lines, `合计: ¥${total}`].join('\n')
}
function sendInvoice(user: User) { email(user.email, buildInvoiceText(user)) }

// ② 用对象传参（Introduce Parameter Object）：消灭 5+ 参数的函数
function filterProducts(category: string, priceMax: number, inStock: boolean, sortBy: string, page: number) {}

interface Filter {
  category?: string; priceMax?: number; inStock?: boolean
  sortBy?: 'price' | 'sales'; page?: number
}
function filterProducts(filter: Filter) {}

// ③ 用三元/提前返回拆掉嵌套（Replace Nested Conditional）
function getStatus(user: User): string {
  if (!user.active) return 'blocked'          // 卫语句提前返回，主路径留在最后
  if (user.vip && user.expireAt > Date.now()) return 'vip'
  return 'normal'
}

// ④ 拆分模块（Extract Module）：文件超过 300 行且职责超过一个，就拆
// utils.ts 拆成 money.ts / date.ts / validate.ts，各自带测试

• 测试依赖执行顺序：测试 A 改了全局状态影响测试 B。解法：beforeEach 重置一切，测试间零共享。
• mock 了自己的内部函数：断言了假实现，真实逻辑出 bug 测试照样绿。解法：只 mock 边界（网络/时钟），内部逻辑走真实链路。
• 快照测试当主力：改个 className 全仓库测试红。解法：行为断言为主，快照只留给纯生成器。
• E2E 用 CSS 选择器：前端重构后 E2E 全崩。解法：getByRole/getByText 等「用户可见」选择器。
• 测试里真等 setTimeout：让测试慢 10 倍。解法：假定时器 vi.useFakeTimers。
• 覆盖率追 100%：最后 20% 花了 80% 的时间，测试全是「为覆盖而写」的僵尸断言。解法：红线 80% + 分支覆盖率重点盯。
• lint 规则太多太严：新成员提交被规则淹没，最后绕过规则（disable 注释满天飞）。解法：少数 error 规则 + 持续治理。
• any 滥用：as any 一多，TS 就退化成 JS。解法：no-explicit-any 规则 + 代码评审盯新增 any。
• PR 太大：1500 行的 PR 没人认真看，评审流于形式。解法：小步提交，< 400 行一个 PR。
• 把重构和功能混在一个 PR：出 bug 无法定位，回滚波及新功能。解法：严格分离，先重构（独立 PR、测试绿）再加功能。

项目 A：给「待办清单」装上完整质量体系（推荐先做）

1. 建 Vitest + Testing Library + MSW + Playwright 完整工程，lint-staged + husky 就位。
2. 业务逻辑层（新增/编辑/过滤/状态切换/截止日期判断）用 TDD 写单元测试，覆盖所有边界。
3. 组件层：用 Testing Library 测「用户操作 → UI 变化」完整交互，含异步加载与错误态。
4. 用 MSW 模拟后端，写 3 条 E2E 黄金路径（新建 → 勾选完成 → 删除）。
5. 配置覆盖率红线（lines ≥ 85、branches ≥ 80），CI 中强制执行。
6. 故意引入一个隐蔽 bug（如时间边界差一天），验证测试能抓住它。

项目 B：给「团队旧项目」做一次受控重构

1. 挑一个你熟悉的遗留模块，先用「特征测试」锁定当前行为（输入输出快照）。
2. 按「提取函数 → 参数对象 → 卫语句 → 拆模块」顺序逐步重构，每步跑测试。
3. 记录重构前后：行数、嵌套深度、测试覆盖、可测性评分的变化。
4. 写一份《重构报告》：改了什么、为什么、如何验证没有行为变化。