React 测试完全指南：单元测试、组件测试、E2E、Mock API、视觉回归与 CI/CD 集成

npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom

// vitest.config.ts
import { defineConfig } from 'vitest/config';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,
    setupFiles: './tests/setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      thresholds: {
        functions: 80,
        lines: 80,
      },
    },
  },
});

// tests/setup.ts
import '@testing-library/jest-dom';

import { describe, it, expect } from 'vitest';
import { formatPrice, calculateDiscount, parseQueryString } from './utils';

describe('formatPrice', () => {
  it('formats number with currency symbol', () => {
    expect(formatPrice(1999.99)).toBe('¥1,999.99');
  });

  it('handles zero', () => {
    expect(formatPrice(0)).toBe('¥0.00');
  });

  it('rounds to 2 decimals', () => {
    expect(formatPrice(99.999)).toBe('¥100.00');
  });
});

describe('calculateDiscount', () => {
  it('applies percentage discount', () => {
    expect(calculateDiscount(100, 20)).toBe(80);
  });

  it('returns full price for zero discount', () => {
    expect(calculateDiscount(100, 0)).toBe(100);
  });

  it('caps discount at 100%', () => {
    expect(calculateDiscount(100, 150)).toBe(0);
  });
});

// 1. 最优先：查询语义化元素（无障碍）
screen.getByRole('button', { name: /submit/i });
screen.getByRole('textbox', { name: 'Email' });

// 2. 标签关联
screen.getByLabelText('Password');

// 3. placeholder
screen.getByPlaceholderText('Enter email');

// 4. 文本内容
screen.getByText('Welcome back');

// 5. 显示值（表单）
screen.getByDisplayValue('John Doe');

// 6. alt 文本（图片）
screen.getByAltText('Product thumbnail');

// 7. title
screen.getByTitle('Close menu');

// 8. 最后手段：test id
screen.getByTestId('user-card');

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

it('toggles password visibility', async () => {
  const user = userEvent.setup();
  render(<PasswordInput />);

  // 初始为密码类型（不可见）
  const input = screen.getByLabelText('Password');
  expect(input).toHaveAttribute('type', 'password');

  // 点击显示按钮
  const toggleBtn = screen.getByRole('button', { name: /show password/i });
  await user.click(toggleBtn);

  // 验证类型变为 text
  expect(input).toHaveAttribute('type', 'text');

  // 再次点击恢复
  await user.click(toggleBtn);
  expect(input).toHaveAttribute('type', 'password');
});

import { render, screen, waitFor, within } from '@testing-library/react';

it('loads and displays user list', async () => {
  render(<UserList />);

  // 初始 loading 状态
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  // 等待数据加载
  const users = await screen.findByRole('list');
  expect(users).toBeInTheDocument();

  // 确认列表项数量
  const items = within(users).getAllByRole('listitem');
  expect(items).toHaveLength(3);

  // 确认特定用户存在
  expect(screen.getByText('Alice')).toBeInTheDocument();
});

it('handles error state', async () => {
  // Mock API 失败
  vi.spyOn(global, 'fetch').mockRejectedValue(new Error('Network error'));

  render(<UserList />);

  await waitFor(() => {
    expect(screen.getByText(/failed to load/i)).toBeInTheDocument();
  });

  // 恢复 mock
  vi.restoreAllMocks();
});

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

export const handlers = [
  http.get('/api/users', () => {
    return HttpResponse.json([
      { id: '1', name: 'Alice', email: 'alice@example.com' },
      { id: '2', name: 'Bob', email: 'bob@example.com' },
    ]);
  }),

  http.get('/api/users/:id', ({ params }) => {
    return HttpResponse.json({
      id: params.id,
      name: `User ${params.id}`,
      email: `user${params.id}@example.com`,
    });
  }),

  http.post('/api/login', async ({ request }) => {
    const body = await request.json();
    if (body.email === 'test@test.com' && body.password === '123456') {
      return HttpResponse.json({ token: 'fake-jwt-token', user: { id: '1', name: 'Test' } });
    }
    return new HttpResponse(null, { status: 401 });
  }),
];

// tests/setup.ts
import { setupServer } from 'msw/node';
import { handlers } from './mocks/handlers';

const server = setupServer(...handlers);

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

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

export default defineConfig({
  testDir: './e2e',
  fullyParallel: true,
  workers: process.env.CI ? 1 : undefined,
  reporter: [['html'], ['junit', { outputFile: 'test-results/junit.xml' }]],
  use: {
    baseURL: 'http://localhost:3000',
    trace: 'on-first-retry',
    screenshot: 'only-on-failure',
  },
  projects: [
    { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
    { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
    { name: 'webkit', use: { ...devices['Desktop Safari'] } },
    { name: 'Mobile Chrome', use: { ...devices['Pixel 5'] } },
    { name: 'Mobile Safari', use: { ...devices['iPhone 12'] } },
  ],
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
});

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

test.describe('Checkout Flow', () => {
  test.beforeEach(async ({ page }) => {
    // 登录
    await page.goto('/login');
    await page.fill('[name="email"]', 'test@example.com');
    await page.fill('[name="password"]', 'password123');
    await page.click('button[type="submit"]');
    await expect(page).toHaveURL('/dashboard');
  });

  test('complete purchase flow', async ({ page }) => {
    // 浏览商品
    await page.goto('/products');
    await page.click('text=Premium Widget');
    await expect(page.locator('h1')).toContainText('Premium Widget');

    // 加入购物车
    await page.click('button:has-text("Add to Cart")');
    await expect(page.locator('[data-testid="cart-count"]')).toHaveText('1');

    // 进入结账
    await page.click('text=Checkout');
    await page.fill('[name="address"]', '123 Test St');
    await page.fill('[name="city"]', 'Test City');
    await page.selectOption('[name="country"]', 'US');

    // 提交订单
    await page.click('button:has-text("Place Order")');

    // 验证成功页
    await expect(page).toHaveURL(/\/order\//);
    await expect(page.locator('h1')).toContainText('Order Confirmed');
  });

  test('handles payment failure', async ({ page }) => {
    // ... 模拟支付失败场景
  });
});

npm install -D chromatic
npx chromatic --project-token=<your-token>

// .storybook/main.ts
export default {
  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx)'],
  addons: ['@storybook/addon-essentials', '@chromatic-com/storybook'],
};

# .github/workflows/test.yml
name: Test
on: [push, pull_request]

jobs:
  unit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run test:unit -- --coverage
      - uses: actions/upload-artifact@v4
        with:
          name: coverage
          path: coverage/

  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npm run test:e2e
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

  visual:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npx chromatic --project-token=${{ secrets.CHROMATIC_TOKEN }}