前端组件测试实战：Testing Library 查询哲学、Storybook 交互测试与 MSW 集成

单元测试（纯函数 / hooks / composables）  无 DOM，毫秒级
  · 覆盖格式化、计算、状态机逻辑          · 占比目标：60%
组件测试（单个组件 / 组件组合）  真实 DOM，秒级
  · 覆盖交互、条件渲染、表单校验、错误态   · 占比目标：30%
E2E 测试（真实浏览器 + 真实后端）  分钟级，最贵最脆弱
  · 只覆盖关键用户旅程                    · 占比目标：10%

优先使用（可访问性导向）：
  1. getByRole ← 首选，天然带可访问性校验
  2. getByLabelText ← 表单元素首选   3. getByPlaceholderText
  4. getByText ← 非表单内容首选      5. getByDisplayValue
次选（语义弱）：getByAltText / getByTitle
最后手段：getByTestId ← 需团队评审
禁止：container.querySelector('.btn-primary')、依赖 DOM 结构与类名

为什么 getByRole 最强？它要求元素有正确的语义角色——button 必须是
<button> 或 role="button"。写测试时顺手就发现了可访问性缺陷。

// Button.test.tsx
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { SubmitButton } from './SubmitButton';

describe('SubmitButton', () => {
  it('渲染可访问的按钮并响应点击', async () => {
    const user = userEvent.setup();
    const onClick = vi.fn();

    render(<SubmitButton onClick={onClick}>提交订单</SubmitButton>);

    // 1. 用 role 查询，顺带验证语义正确
    const button = screen.getByRole('button', { name: '提交订单' });
    expect(button).toBeEnabled();

    // 2. 用真实用户事件而非 fireEvent
    await user.click(button);
    expect(onClick).toHaveBeenCalledTimes(1);
  });

  it('加载中禁用按钮并暴露 aria-busy', () => {
    render(<SubmitButton loading>提交订单</SubmitButton>);

    const button = screen.getByRole('button', { name: '提交订单' });
    expect(button).toBeDisabled();
    expect(button).toHaveAttribute('aria-busy', 'true');
  });
});

// 反例：用 getBy 断言不存在 → 测试会红
expect(() => screen.getByText('错误提示')).toThrow();  // ✗ 脆弱

// 正例：用 queryBy 断言不存在
expect(screen.queryByText('错误提示')).not.toBeInTheDocument();  // ✓

// 正例：异步出现的元素用 findBy
expect(await screen.findByRole('alert')).toHaveTextContent('保存成功');  // ✓

fireEvent.click(el)：直接派发一个 click 事件，不模拟真实交互序列，
  不触发 focus、pointerdown、mousedown、mouseup

userEvent.click(el)：模拟完整交互序列 pointerover → pointerdown →
  mousedown → focus → pointerup → mouseup → click，并检查元素是否
  可交互（pointer-events、disabled、可见性），默认带 delay。

结论：一律用 userEvent，fireEvent 只在极少数底层场景使用。

// SearchBox.test.tsx
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { SearchBox } from './SearchBox';

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

  await user.type(screen.getByRole('searchbox'), 'playwright');

  // ✓ 用 findBy 等待元素出现（内部就是 waitFor + getBy）
  const results = await screen.findAllByRole('listitem');
  expect(results).toHaveLength(3);
  expect(results[0]).toHaveTextContent('Playwright 入门');
});

it('请求失败时展示错误提示', async () => {
  server.use(
    http.get('/api/search', () => HttpResponse.json({ message: 'boom' }, { status: 500 })),
  );
  const user = userEvent.setup();
  render(<SearchBox />);

  await user.type(screen.getByRole('searchbox'), 'x');

  // ✓ 用 findByRole 等待 alert（ARIA 语义 + 异步）
  expect(await screen.findByRole('alert')).toHaveTextContent('搜索失败，请重试');
});

反模式一：waitFor 里放空断言  await waitFor(() => {})  ✗ 必然立即通过
反模式二：waitFor 里做副作用  await waitFor(() => { fetchData(); })
  ✗ 会重试多次，副作用爆炸 → 副作用放外面，里面只做断言
反模式三：加大 timeout 掩盖 flaky  { timeout: 10000 } ✗ 只是变成长等待

正解：优先 findBy*（语义清晰、内置等待），
     只有多元素条件组合时才用 waitFor。

// Form.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { expect, userEvent, within, fn } from '@storybook/test';
import { LoginForm } from './LoginForm';

const meta = {
  component: LoginForm,
  args: { onSubmit: fn() },
} satisfies Meta<typeof LoginForm>;
export default meta;

type Story = StoryObj<typeof meta>;

export const 提交成功: Story = {
  play: async ({ canvasElement, args }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText('邮箱'), 'dev@example.com');
    await userEvent.type(canvas.getByLabelText('密码'), 's3cret!');
    await userEvent.click(canvas.getByRole('button', { name: '登录' }));

    await expect(args.onSubmit).toHaveBeenCalledWith({
      email: 'dev@example.com',
      password: 's3cret!',
    });
  },
};

export const 校验失败: Story = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByRole('button', { name: '登录' }));
    await expect(canvas.getByText('请输入邮箱')).toBeInTheDocument();
  },
};

# 方式一：test-runner（Playwright 真实浏览器）启动 Storybook 逐 story 执行 play
npx storybook test --ci --coverage
# 方式二：Vitest addon（jsdom/browser，更快）
npx vitest --project=storybook
# 方式三：只跑变更 story（增量）
npx storybook test --ci --onlyChanged

Mock 模块（vi.mock('./api')）
  ✗ 与实现强耦合，改函数名就碎；无法验证真实的请求参数与序列化
Mock fetch / axios
  ✗ 需 mock 全局，影响其他测试；拦截不到真实请求

MSW（Service Worker / Node 拦截器）
  ✓ 拦截在网络层，代码调用真实 fetch/axios
  ✓ 请求 URL、方法、body、headers 全部可断言
  ✓ 同一份 handler 可用于测试、Storybook、本地开发
  ✓ 未处理的请求可配置为报错，避免"假通过"

// mocks/handlers.ts
import { http, HttpResponse, delay } from 'msw';

export const handlers = [
  http.get('/api/users/:id', async ({ params }) => {
    await delay(50);
    return HttpResponse.json({ id: Number(params.id), name: 'Leeting Yan' });
  }),
  http.post('/api/orders', async ({ request }) => {
    const body = (await request.json()) as { sku: string; qty: number };
    if (body.qty <= 0) {
      return HttpResponse.json({ message: '数量必须大于 0' }, { status: 422 });
    }
    return HttpResponse.json({ id: 'ord_123', ...body }, { status: 201 });
  }),
];

// test/setup.ts
import { setupServer } from 'msw/node';
import { handlers } from '../mocks/handlers';
import { afterAll, afterEach, beforeAll } from 'vitest';

export const server = setupServer(...handlers);
beforeAll(() => server.listen({ onUnhandledRequest: 'error' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

import { server } from '../test/setup';
import { http, HttpResponse } from 'msw';

it('提交订单时发送正确的请求体', async () => {
  const captured: unknown[] = [];
  server.use(
    http.post('/api/orders', async ({ request }) => {
      captured.push(await request.json());
      return HttpResponse.json({ id: 'ord_1' }, { status: 201 });
    }),
  );
  const user = userEvent.setup();
  render(<OrderForm />);
  await user.type(screen.getByLabelText('商品编码'), 'SKU-9');
  await user.click(screen.getByRole('button', { name: '下单' }));
  expect(await screen.findByText('下单成功')).toBeInTheDocument();
  expect(captured).toEqual([{ sku: 'SKU-9', qty: 1 }]);
});

// ✓ 推荐：内联快照，快照就在测试文件里，review 必然看到
import { render } from '@testing-library/react';

it('表格组件的语义结构稳定', () => {
  const { container } = render(<DataTable rows={rows} />);
  expect(container).toMatchInlineSnapshot(`
    <table>
      <caption>订单列表</caption>
      <thead><tr><th scope="col">编号</th><th scope="col">金额</th></tr></thead>
      <tbody><tr><td>1001</td><td>¥500.00</td></tr></tbody>
    </table>
  `);
});

import { axe, toHaveNoViolations } from 'jest-axe';
expect.extend(toHaveNoViolations);

it('登录表单无 WCAG 违规', async () => {
  const { container } = render(<LoginForm />);
  expect(await axe(container)).toHaveNoViolations();
});

it('错误态下依然无违规（含 aria-describedby 关联）', async () => {
  const { container } = render(<LoginForm error="密码错误" />);
  // 关掉与本次无关的规则，聚焦表单语义
  const results = await axe(container, { rules: { region: { enabled: false } } });
  expect(results).toHaveNoViolations();
});

// Counter.spec.ts
import { render, screen } from '@testing-library/vue';
import userEvent from '@testing-library/user-event';
import { nextTick } from 'vue';
import Counter from './Counter.vue';

it('点击后计数递增并更新 aria-live 区域', async () => {
  const user = userEvent.setup();
  render(Counter, { props: { initial: 0 } });

  await user.click(screen.getByRole('button', { name: '增加' }));
  await nextTick();   // Vue 需显式等待响应式更新

  expect(screen.getByRole('status')).toHaveTextContent('当前计数：1');
});

// useCart.spec.ts — 组合式函数单独测试，无需渲染
import { effectScope } from 'vue';
import { useCart } from './useCart';

it('添加同款商品时合并数量', () => {
  const scope = effectScope();
  const cart = scope.run(() => useCart())!;
  cart.add({ sku: 'A', qty: 1 });
  cart.add({ sku: 'A', qty: 2 });
  expect(cart.items.value).toEqual([{ sku: 'A', qty: 3 }]);
  expect(cart.total.value).toBe(3);
  scope.stop();   // 清理副作用，避免跨测试污染
});