13 测试与质量保障
  ├─ 前置：06 框架与组件化、09 工程化（CI）
  ├─ 紧接：18 可观测性（线上质量）、12 安全（安全测试）
  ├─ 交叉：11 性能（性能测试）、08 渲染（SSR 测试）
  └─ 长期：20 工程效能（质量文化）

import { describe, it, expect } from 'vitest';
import { calcDiscount } from './discount';

describe('calcDiscount', () => {
  it('满 100 减 20', () => {
    // Arrange 准备
    const total = 120;

    // Act 执行
    const result = calcDiscount(total);

    // Assert 断言
    expect(result).toBe(100);
  });
});

// ❌ 测内部实现：重构就挂，且没验证用户价值
expect(component.state.isOpen).toBe(true);

// ✅ 测可观察行为
expect(screen.getByRole('dialog')).toBeVisible();

import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

test('输入关键词后展示结果', async () => {
  const user = userEvent.setup();
  render(<SearchPage />);

  // 优先级：Role > Label > Placeholder > Text > TestId
  await user.type(screen.getByRole('searchbox', { name: '搜索' }), '手机');
  await user.click(screen.getByRole('button', { name: '查询' }));

  expect(await screen.findByText('共 3 条结果')).toBeInTheDocument();
});

expect(screen.queryByText('加载中')).not.toBeInTheDocument(); // 断言不存在用 query
expect(await screen.findByText('订单列表')).toBeInTheDocument(); // 异步用 find

vitest run --coverage

金字塔（传统）              奖杯（前端更实用）
   /\   E2E  少量             /\   E2E 少量
  /  \  集成 适量             /  \  集成（组件）最多
 /____\ 单元 大量            /____\ 单元 适量

import { http, HttpResponse } from 'msw';
import { setupServer } from 'msw/node';

/**
 * 用 MSW 在网络层拦截，而不是 mock 掉 fetch 或整个模块。
 * 好处：组件内部的请求逻辑、错误处理、加载态都能被真实覆盖。
 */
const server = setupServer(
  http.get('/api/orders', ({ request }) => {
    const url = new URL(request.url);
    const page = Number(url.searchParams.get('page') ?? 1);

    if (page === 1) {
      return HttpResponse.json({ list: [{ id: '1', title: '订单 A' }], total: 2 });
    }
    return HttpResponse.json({ list: [{ id: '2', title: '订单 B' }], total: 2 });
  }),
);

beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

test('加载更多会追加数据', async () => {
  const user = userEvent.setup();
  render(<OrderList />);

  expect(await screen.findByText('订单 A')).toBeInTheDocument();
  await user.click(screen.getByRole('button', { name: '加载更多' }));
  expect(await screen.findByText('订单 B')).toBeInTheDocument();
});

// ❌ 等 1 秒：慢且不稳定
await new Promise((r) => setTimeout(r, 1000));

// ✅ 等「条件成立」
await waitFor(() => expect(screen.getByText('保存成功')).toBeInTheDocument());

// ✅ 等元素出现
expect(await screen.findByRole('alert')).toHaveTextContent('保存失败');

import { test, expect } from '@playwright/test';

test('用户下单成功', async ({ page }) => {
  await page.goto('/login');
  await page.getByLabel('账号').fill('demo');
  await page.getByLabel('密码').fill('123456');
  await page.getByRole('button', { name: '登录' }).click();

  await expect(page.getByRole('heading', { name: '商品列表' })).toBeVisible();

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

  await expect(page.getByText('下单成功')).toBeVisible();
  await expect(page).toHaveURL(/\/orders\/\d+/);
});

test('订单卡片外观稳定', async ({ page }) => {
  await page.goto('/order/1');
  await expect(page.getByTestId('order-card')).toHaveScreenshot('order-card.png', {
    maxDiffPixelRatio: 0.01, // 允许 1% 像素差异，吸收字体渲染差异
  });
});

/**
 * 用 OpenAPI schema 校验真实响应，防止后端悄悄改字段。
 * 比 mock 更强：mock 只能证明「前端能处理假数据」。
 */
test('GET /orders 符合契约', async ({ request }) => {
  const res = await request.get('/api/orders');
  expect(res.status()).toBe(200);

  const body = await res.json();
  expect(body).toMatchSchema(orderListSchema); // zod / ajv
});

/**
 * 工厂函数：只写关心的字段，其余给合理默认值。
 * 好处：新增字段不会让所有用例失效。
 */
function makeOrder(overrides = {}) {
  return {
    id: 'o_1',
    title: '测试订单',
    status: 'created',
    total: 100,
    createdAt: '2026-01-01T00:00:00Z',
    ...overrides,
  };
}

const paidOrder = makeOrder({ status: 'paid' });

// ❌ 直接依赖全局时间：测试无法控制
function isExpired(token) {
  return Date.now() > token.exp;
}

// ✅ 注入依赖：测试可以传任意时间
/**
 * @param {{ exp: number }} token
 * @param {number} [now] 当前时间戳（毫秒）
 */
function isExpired(token, now = Date.now()) {
  return now > token.exp;
}

// Playwright：先禁用动画，减少不确定性
test.use({ launchOptions: { args: ['--force-prefers-reduced-motion'] } });

# Playwright 分片：4 台机器各跑 1/4
npx playwright test --shard=1/4

// 用 Playwright 采集一次交互的性能
test('搜索交互性能', async ({ page }) => {
  await page.goto('/search');
  const client = await page.context().newCDPSession(page);
  await client.send('Performance.enable');

  const start = Date.now();
  await page.getByRole('searchbox').fill('手机');
  await page.getByRole('button', { name: '查询' }).click();
  await expect(page.getByText('共 3 条结果')).toBeVisible();

  expect(Date.now() - start).toBeLessThan(1000);
});

// 可访问性：自动扫描 + 人工复核
import AxeBuilder from '@axe-core/playwright';

test('首页无严重可访问性问题', async ({ page }) => {
  await page.goto('/');
  const results = await new AxeBuilder({ page }).analyze();
  expect(results.violations.filter((v) => v.impact === 'critical')).toHaveLength(0);
});

jobs:
  test:
    steps:
      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm typecheck
      - run: pnpm test -- --coverage --changed
      - run: pnpm exec playwright test --shard=${{ matrix.shard }}/4

tests/
├─ unit/            # 纯逻辑，毫秒级
├─ components/      # 组件 + MSW
├─ e2e/             # Playwright
├─ fixtures/        # 数据工厂、登录态
├─ mocks/           # MSW handlers
└─ utils/           # 自定义 render、等待工具

/**
 * 自定义 render：统一注入 Provider，避免每个用例重复包裹。
 */
function renderWithProviders(ui, { preloadedState } = {}) {
  return render(
    <Provider store={createTestStore(preloadedState)}>
      <Router>{ui}</Router>
    </Provider>,
  );
}

成本 = 编写时间 + 维护时间 + 运行时间 + flaky 处理
收益 = 减少的线上故障 × 故障成本 + 提升的迭代速度

事故：优惠券叠加导致金额为负
  ↓
根因：缺少边界用例；金额计算是纯函数但没测负数
  ↓
转化：
  1) 补单元测试（负数、0、极大值）
  2) 加类型约束（金额用分，禁止浮点）
  3) 加监控告警（负金额出现即报警）
  4) 复盘文档进知识库

test('优惠券叠加后金额不为负', () => {
  const cart = makeCart({ total: 100 });
  const coupons = [makeCoupon({ type: 'minus', value: 80 }), makeCoupon({ type: 'minus', value: 50 })];

  const result = calcTotal(cart, coupons);

  expect(result.total).toBe(0);      // 不允许负数
  expect(result.discount).toBe(100); // 折扣不超过总额
});

test('重复点击提交只创建一个订单', async ({ page }) => {
  await page.goto('/checkout');
  const submit = page.getByRole('button', { name: '提交订单' });

  await Promise.all([submit.click(), submit.click()]); // 模拟连点

  await expect(page.getByText('下单成功')).toBeVisible();
  const count = await page.evaluate(() => window.__orders.length);
  expect(count).toBe(1);
});

PR：单元 + 组件 + 类型 + lint（< 8min）
主干：加契约 + 关键 E2E（< 15min）
发布前：全量 E2E + 视觉回归 + 冒烟（< 30min）

/** 已注册的用例 */
const suites = [];
let currentSuite = null;

/**
 * 定义一组用例。
 * @param {string} name
 * @param {() => void} fn
 */
function describe(name, fn) {
  const parent = currentSuite;
  currentSuite = { name, tests: [], children: [], parent };
  (parent ? parent.children : suites).push(currentSuite);
  fn();
  currentSuite = parent;
}

/**
 * 定义单个用例。
 * @param {string} name
 * @param {() => void | Promise<void>} fn
 */
function it(name, fn) {
  currentSuite.tests.push({ name, fn });
}

/**
 * 断言：只实现最常用的相等与抛错。
 * @param {any} actual
 */
function expect(actual) {
  return {
    toBe(expected) {
      if (!Object.is(actual, expected)) {
        throw new Error(`期望 ${String(expected)}，实际 ${String(actual)}`);
      }
    },
    toEqual(expected) {
      if (JSON.stringify(actual) !== JSON.stringify(expected)) {
        throw new Error(`期望 ${JSON.stringify(expected)}，实际 ${JSON.stringify(actual)}`);
      }
    },
    toThrow() {
      let thrown = false;
      try {
        actual();
      } catch {
        thrown = true;
      }
      if (!thrown) throw new Error('期望抛出异常，但没有');
    },
  };
}

/**
 * 执行全部用例，返回失败列表。
 * @returns {Promise<Array<{name: string, error: Error}>>}
 */
async function run() {
  const failures = [];
  const visit = async (suite, prefix) => {
    for (const test of suite.tests) {
      const fullName = `${prefix}${suite.name} > ${test.name}`;
      try {
        await test.fn();
        console.log(`✓ ${fullName}`);
      } catch (error) {
        failures.push({ name: fullName, error });
        console.error(`✗ ${fullName}`);
      }
    }
    for (const child of suite.children) await visit(child, `${prefix}${suite.name} > `);
  };
  for (const suite of suites) await visit(suite, '');
  return failures;
}

/**
 * 假定时器：接管 setTimeout/setInterval，支持推进与全部执行。
 * @param {number} [start=0] 起始时间
 */
function createFakeTimers(start = 0) {
  let now = start;
  let seq = 0;
  const timers = new Map();

  const schedule = (fn, delay = 0, interval = null, args = []) => {
    const id = ++seq;
    timers.set(id, { fn, time: now + Math.max(0, delay), interval, args });
    return id;
  };

  const clear = (id) => timers.delete(id);

  /** 取出下一个到期任务执行 */
  const tick = () => {
    let next = null;
    timers.forEach((timer, id) => {
      if (!next || timer.time < next.timer.time) next = { id, timer };
    });
    if (!next) return false;

    const { id, timer } = next;
    now = timer.time;
    if (timer.interval == null) timers.delete(id);
    else timer.time = now + timer.interval;
    timer.fn(...timer.args);
    return true;
  };

  /**
   * 推进指定毫秒，执行到期任务（含推进过程中新增的）。
   * @param {number} ms
   */
  const advance = (ms) => {
    const target = now + ms;
    while (true) {
      let next = null;
      timers.forEach((timer, id) => {
        if (timer.time <= target && (!next || timer.time < next.timer.time)) next = { id, timer };
      });
      if (!next) break;
      tick();
    }
    now = target;
  };

  const runAll = () => {
    while (tick()) {
      // 直到没有任务，注意 setInterval 会死循环，需加保护
    }
  };

  return {
    setTimeout: (fn, delay, ...args) => schedule(fn, delay, null, args),
    setInterval: (fn, delay, ...args) => schedule(fn, delay, delay, args),
    clearTimeout: clear,
    clearInterval: clear,
    advance,
    runAll,
    get now() {
      return now;
    },
  };
}