React 测试策略与最佳实践

// Jest 配置示例
// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
  moduleNameMapper: {
    '^@/(.*)$': '<rootDir>/src/$1',
    '\.(css|less|scss|sass)$': 'identity-obj-proxy'
  },
  transform: {
    '^.+\.(js|jsx|ts|tsx)$': ['babel-jest', { presets: ['next/babel'] }]
  },
  collectCoverageFrom: [
    'src/**/*.{js,jsx,ts,tsx}',
    '!src/**/*.d.ts',
    '!src/**/*.stories.{js,jsx,ts,tsx}'
  ]
};

// 组件渲染测试
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import Counter from './Counter';

describe('Counter Component', () => {
  test('renders initial count', () => {
    render(<Counter initialCount={0} />);
    expect(screen.getByText('Count: 0')).toBeInTheDocument();
  });
  
  test('increments count when button clicked', async () => {
    const user = userEvent.setup();
    render(<Counter initialCount={0} />);
    
    await user.click(screen.getByRole('button', { name: /increment/i }));
    
    expect(screen.getByText('Count: 1')).toBeInTheDocument();
  });
  
  test('decrements count when button clicked', async () => {
    const user = userEvent.setup();
    render(<Counter initialCount={5} />);
    
    await user.click(screen.getByRole('button', { name: /decrement/i }));
    
    expect(screen.getByText('Count: 4')).toBeInTheDocument();
  });
});

// 表单组件测试
import { render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import LoginForm from './LoginForm';

describe('LoginForm', () => {
  const mockOnSubmit = jest.fn();
  
  beforeEach(() => {
    mockOnSubmit.mockClear();
  });
  
  test('submits form with correct values', async () => {
    const user = userEvent.setup();
    render(<LoginForm onSubmit={mockOnSubmit} />);
    
    await user.type(screen.getByLabelText(/email/i), 'test@example.com');
    await user.type(screen.getByLabelText(/password/i), 'password123');
    await user.click(screen.getByRole('button', { name: /submit/i }));
    
    await waitFor(() => {
      expect(mockOnSubmit).toHaveBeenCalledWith({
        email: 'test@example.com',
        password: 'password123'
      });
    });
  });
  
  test('shows validation error for invalid email', async () => {
    const user = userEvent.setup();
    render(<LoginForm onSubmit={mockOnSubmit} />);
    
    await user.type(screen.getByLabelText(/email/i), 'invalid-email');
    await user.click(screen.getByRole('button', { name: /submit/i }));
    
    expect(await screen.findByText(/invalid email/i)).toBeInTheDocument();
    expect(mockOnSubmit).not.toHaveBeenCalled();
  });
});

// 异步组件测试
import { render, screen, waitFor } from '@testing-library/react';
import UserProfile from './UserProfile';

// Mock fetch
global.fetch = jest.fn();

describe('UserProfile', () => {
  beforeEach(() => {
    fetch.mockClear();
  });
  
  test('shows loading state initially', () => {
    fetch.mockImplementation(() => new Promise(() => {}));
    render(<UserProfile userId="1" />);
    expect(screen.getByText(/loading/i)).toBeInTheDocument();
  });
  
  test('renders user data after fetch', async () => {
    fetch.mockResolvedValueOnce({
      ok: true,
      json: async () => ({ id: '1', name: 'John Doe', email: 'john@example.com' })
    });
    
    render(<UserProfile userId="1" />);
    
    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
      expect(screen.getByText('john@example.com')).toBeInTheDocument();
    });
  });
  
  test('shows error message on fetch failure', async () => {
    fetch.mockRejectedValueOnce(new Error('Network error'));
    
    render(<UserProfile userId="1" />);
    
    expect(await screen.findByText(/error/i)).toBeInTheDocument();
  });
});

// 自定义 Hook 测试
import { renderHook, act } from '@testing-library/react';
import { useCounter } from './useCounter';

describe('useCounter Hook', () => {
  test('initializes with default value', () => {
    const { result } = renderHook(() => useCounter());
    expect(result.current.count).toBe(0);
  });
  
  test('initializes with custom value', () => {
    const { result } = renderHook(() => useCounter(10));
    expect(result.current.count).toBe(10);
  });
  
  test('increments count', () => {
    const { result } = renderHook(() => useCounter());
    
    act(() => {
      result.current.increment();
    });
    
    expect(result.current.count).toBe(1);
  });
  
  test('decrements count', () => {
    const { result } = renderHook(() => useCounter(5));
    
    act(() => {
      result.current.decrement();
    });
    
    expect(result.current.count).toBe(4);
  });
});

// MSW API Mock 示例
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import { render, screen, waitFor } from '@testing-library/react';
import UserList from './UserList';

const server = setupServer(
  rest.get('/api/users', (req, res, ctx) => {
    return res(
      ctx.json([
        { id: 1, name: 'John Doe' },
        { id: 2, name: 'Jane Smith' }
      ])
    );
  })
);

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

describe('UserList with MSW', () => {
  test('renders users from API', async () => {
    render(<UserList />);
    
    await waitFor(() => {
      expect(screen.getByText('John Doe')).toBeInTheDocument();
      expect(screen.getByText('Jane Smith')).toBeInTheDocument();
    });
  });
  
  test('handles API error', async () => {
    server.use(
      rest.get('/api/users', (req, res, ctx) => {
        return res(ctx.status(500));
      })
    );
    
    render(<UserList />);
    
    expect(await screen.findByText(/error/i)).toBeInTheDocument();
  });
});

// 快照测试
import { render } from '@testing-library/react';
import Card from './Card';

describe('Card Snapshot', () => {
  test('matches snapshot', () => {
    const { asFragment } = render(
      <Card title="Test Card" description="This is a test card" />
    );
    expect(asFragment()).toMatchSnapshot();
  });
  
  test('matches snapshot with custom className', () => {
    const { asFragment } = render(
      <Card 
        title="Test Card" 
        description="This is a test card" 
        className="custom-class"
      />
    );
    expect(asFragment()).toMatchSnapshot();
  });
});

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

function LoginForm() {
  return (
    <form>
      <label htmlFor="email">邮箱</label>
      <input id="email" type="email" placeholder="请输入邮箱" />
      <button type="submit">登录</button>
      <img src="/logo.png" alt="公司 Logo" />
      <p data-testid="status">就绪</p>
    </form>
  );
}

describe('查询优先级演示', () => {
  beforeEach(() => render(<LoginForm />));

  // 1. 首选：可被所有人访问的查询（无障碍角色）
  test('getByRole - 最推荐', () => {
    // role 查询最健壮，同时验证了无障碍性
    expect(screen.getByRole('button', { name: '登录' })).toBeInTheDocument();
    expect(screen.getByRole('textbox', { name: '邮箱' })).toBeInTheDocument();
  });

  // 2. getByLabelText - 表单元素首选
  test('getByLabelText - 表单元素', () => {
    expect(screen.getByLabelText('邮箱')).toBeInTheDocument();
  });

  // 3. getByPlaceholderText - 没有 label 时的退路
  test('getByPlaceholderText', () => {
    expect(screen.getByPlaceholderText('请输入邮箱')).toBeInTheDocument();
  });

  // 4. getByText - 非交互元素（div、span、p）
  test('getByText', () => {
    expect(screen.getByText('就绪')).toBeInTheDocument();
  });

  // 5. getByAltText - 图片
  test('getByAltText', () => {
    expect(screen.getByAltText('公司 Logo')).toBeInTheDocument();
  });

  // 6. 最后的手段：getByTestId（前面都无法定位时）
  test('getByTestId - 最后手段', () => {
    expect(screen.getByTestId('status')).toHaveTextContent('就绪');
  });
});

// getBy*   - 找不到直接抛错，找到多个也抛错（断言元素必须存在）
// queryBy* - 找不到返回 null，用于断言"元素不存在"
// findBy*  - 返回 Promise，自动重试，用于异步出现的元素

describe('查询变体', () => {
  test('queryBy 断言元素不存在', () => {
    render(<div>已登录</div>);
    // 不能用 getByText 断言不存在，它会抛错；用 queryByText
    expect(screen.queryByText('登录')).not.toBeInTheDocument();
  });

  test('findBy 等待异步元素', async () => {
    render(<AsyncGreeting />);
    // findBy 内部封装了 waitFor，默认重试 1000ms
    expect(await screen.findByText('你好，World')).toBeInTheDocument();
  });

  test('getAllBy 处理多个元素', () => {
    render(
      <ul>
        <li>项 1</li>
        <li>项 2</li>
        <li>项 3</li>
      </ul>
    );
    expect(screen.getAllByRole('listitem')).toHaveLength(3);
  });
});

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

describe('userEvent 完整交互', () => {
  test('输入、清空、键盘操作', async () => {
    const user = userEvent.setup();
    render(<input aria-label="search" />);
    const input = screen.getByLabelText('search');

    // 输入文本
    await user.type(input, 'hello');
    expect(input).toHaveValue('hello');

    // 清空
    await user.clear(input);
    expect(input).toHaveValue('');

    // 特殊按键：{Enter}、{Backspace}、{ArrowLeft} 等
    await user.type(input, 'abc{Backspace}');
    expect(input).toHaveValue('ab');

    // 组合键（全选后删除）
    await user.type(input, '{Control>}a{/Control}{Delete}');
    expect(input).toHaveValue('');
  });

  test('下拉选择与复选框', async () => {
    const user = userEvent.setup();
    render(
      <>
        <select aria-label="城市">
          <option value="bj">北京</option>
          <option value="sh">上海</option>
        </select>
        <input type="checkbox" aria-label="同意条款" />
      </>
    );

    await user.selectOptions(screen.getByLabelText('城市'), 'sh');
    expect(screen.getByLabelText('城市')).toHaveValue('sh');

    await user.click(screen.getByLabelText('同意条款'));
    expect(screen.getByLabelText('同意条款')).toBeChecked();
  });

  test('悬停、双击、右键', async () => {
    const user = userEvent.setup();
    const onDoubleClick = jest.fn();
    const onContextMenu = jest.fn();
    render(
      <button onDoubleClick={onDoubleClick} onContextMenu={onContextMenu}>
        操作
      </button>
    );
    const btn = screen.getByRole('button');

    await user.dblClick(btn);
    expect(onDoubleClick).toHaveBeenCalledTimes(1);

    await user.pointer({ keys: '[MouseRight]', target: btn });
    expect(onContextMenu).toHaveBeenCalledTimes(1);
  });

  test('使用假定时器时需要配置 advanceTimers', async () => {
    jest.useFakeTimers();
    // 关键：userEvent 内部有延迟，需告知它推进假定时器
    const user = userEvent.setup({ advanceTimers: jest.advanceTimersByTime });
    render(<DebouncedSearch />);
    await user.type(screen.getByRole('textbox'), 'react');
    jest.advanceTimersByTime(500);
    expect(await screen.findByText(/搜索: react/)).toBeInTheDocument();
    jest.useRealTimers();
  });
});

// 完整 Mock 一个模块
jest.mock('axios');
import axios from 'axios';

test('mock axios', async () => {
  axios.get.mockResolvedValue({ data: { name: 'Alice' } });
  const res = await axios.get('/user');
  expect(res.data.name).toBe('Alice');
});

// 部分 Mock：保留真实实现，只覆盖某个导出
jest.mock('./utils', () => ({
  ...jest.requireActual('./utils'),
  formatDate: jest.fn(() => '2026-08-03'),
}));

// Mock 默认导出与具名导出混合
jest.mock('./api', () => ({
  __esModule: true,
  default: jest.fn(),
  fetchUser: jest.fn(),
}));

describe('假定时器', () => {
  beforeEach(() => jest.useFakeTimers());
  afterEach(() => jest.useRealTimers());

  test('防抖函数只在最后触发一次', () => {
    const fn = jest.fn();
    const debounced = debounce(fn, 300);
    debounced();
    debounced();
    debounced();
    expect(fn).not.toHaveBeenCalled();
    jest.advanceTimersByTime(300);
    expect(fn).toHaveBeenCalledTimes(1);
  });

  test('setInterval 轮询', () => {
    const poll = jest.fn();
    setInterval(poll, 1000);
    jest.advanceTimersByTime(3500);
    expect(poll).toHaveBeenCalledTimes(3);
  });
});

// Mock matchMedia（jsdom 不实现）
beforeAll(() => {
  Object.defineProperty(window, 'matchMedia', {
    writable: true,
    value: jest.fn().mockImplementation((query) => ({
      matches: false,
      media: query,
      addEventListener: jest.fn(),
      removeEventListener: jest.fn(),
    })),
  });
});

// Mock IntersectionObserver
beforeAll(() => {
  global.IntersectionObserver = class {
    observe = jest.fn();
    unobserve = jest.fn();
    disconnect = jest.fn();
  };
});

// Mock localStorage
const localStorageMock = (() => {
  let store = {};
  return {
    getItem: (key) => store[key] || null,
    setItem: (key, value) => { store[key] = String(value); },
    removeItem: (key) => { delete store[key]; },
    clear: () => { store = {}; },
  };
})();
Object.defineProperty(window, 'localStorage', { value: localStorageMock });

// test-utils.tsx —— 自定义 render，一次性包裹所有 Provider
import { render as rtlRender } from '@testing-library/react';
import { ThemeProvider } from './ThemeContext';
import { AuthProvider } from './AuthContext';

function AllProviders({ children }) {
  return (
    <ThemeProvider>
      <AuthProvider>{children}</AuthProvider>
    </ThemeProvider>
  );
}

// 重新导出所有内容，并覆盖 render
export * from '@testing-library/react';
export function render(ui, options) {
  return rtlRender(ui, { wrapper: AllProviders, ...options });
}

// 使用：业务测试无需关心 Provider 细节
import { render, screen } from './test-utils';

test('组件能读取主题', () => {
  render(<ThemedButton />);
  expect(screen.getByRole('button')).toHaveClass('theme-light');
});

function renderWithAuth(ui, { user = null } = {}) {
  return render(
    <AuthContext.Provider value={{ user, login: jest.fn(), logout: jest.fn() }}>
      {ui}
    </AuthContext.Provider>
  );
}

test('未登录显示登录按钮', () => {
  renderWithAuth(<Navbar />, { user: null });
  expect(screen.getByRole('button', { name: '登录' })).toBeInTheDocument();
});

test('已登录显示用户名', () => {
  renderWithAuth(<Navbar />, { user: { name: 'Alice' } });
  expect(screen.getByText('Alice')).toBeInTheDocument();
});

import { MemoryRouter, Routes, Route } from 'react-router-dom';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

// 用 MemoryRouter 控制初始路由，无需真实浏览器
function renderWithRouter(ui, { route = '/' } = {}) {
  return render(<MemoryRouter initialEntries={[route]}>{ui}</MemoryRouter>);
}

test('访问 /about 渲染关于页', () => {
  renderWithRouter(
    <Routes>
      <Route path="/" element={<Home />} />
      <Route path="/about" element={<About />} />
    </Routes>,
    { route: '/about' }
  );
  expect(screen.getByRole('heading', { name: '关于我们' })).toBeInTheDocument();
});

test('点击链接跳转', async () => {
  const user = userEvent.setup();
  renderWithRouter(<App />);
  await user.click(screen.getByRole('link', { name: '关于' }));
  expect(await screen.findByRole('heading', { name: '关于我们' })).toBeInTheDocument();
});

// Redux：为每个测试创建独立 store，避免测试间污染
import { configureStore } from '@reduxjs/toolkit';
import { Provider } from 'react-redux';
import cartReducer from './cartSlice';

function renderWithStore(ui, { preloadedState } = {}) {
  const store = configureStore({
    reducer: { cart: cartReducer },
    preloadedState,
  });
  return {
    store,
    ...render(<Provider store={store}>{ui}</Provider>),
  };
}

test('加入购物车增加数量', async () => {
  const user = userEvent.setup();
  const { store } = renderWithStore(<ProductCard id="1" />, {
    preloadedState: { cart: { items: [] } },
  });
  await user.click(screen.getByRole('button', { name: '加入购物车' }));
  expect(store.getState().cart.items).toHaveLength(1);
});

// Zustand：在每个测试前重置 store 状态
import { useCartStore } from './store';

beforeEach(() => {
  useCartStore.setState({ items: [] });
});

test('Zustand action 更新状态', () => {
  useCartStore.getState().addItem({ id: '1', name: '商品' });
  expect(useCartStore.getState().items).toHaveLength(1);
});

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

class ErrorBoundary extends React.Component {
  state = { hasError: false };
  static getDerivedStateFromError() {
    return { hasError: true };
  }
  render() {
    if (this.state.hasError) return <div>出错了</div>;
    return this.props.children;
  }
}

function Bomb() {
  throw new Error('炸了');
}

test('错误边界捕获子组件异常', () => {
  // 抑制 React 打印的错误日志，让测试输出干净
  const spy = jest.spyOn(console, 'error').mockImplementation(() => {});
  render(
    <ErrorBoundary>
      <Bomb />
    </ErrorBoundary>
  );
  expect(screen.getByText('出错了')).toBeInTheDocument();
  spy.mockRestore();
});

import { render } from '@testing-library/react';
import { axe, toHaveNoViolations } from 'jest-axe';

expect.extend(toHaveNoViolations);

test('表单无无障碍违规', async () => {
  const { container } = render(<LoginForm />);
  const results = await axe(container);
  // 自动检测缺少 label、对比度不足、缺少 alt 等问题
  expect(results).toHaveNoViolations();
});

// tests/login.spec.ts
import { test, expect } from '@playwright/test';

test.describe('登录流程', () => {
  test('成功登录后跳转到仪表盘', async ({ page }) => {
    await page.goto('/login');
    await page.getByLabel('邮箱').fill('user@example.com');
    await page.getByLabel('密码').fill('password123');
    await page.getByRole('button', { name: '登录' }).click();

    // 等待导航并断言 URL 与页面内容
    await expect(page).toHaveURL('/dashboard');
    await expect(page.getByRole('heading', { name: '欢迎回来' })).toBeVisible();
  });

  test('拦截网络请求 Mock 后端', async ({ page }) => {
    // Playwright 可直接拦截并 Mock API，无需真实后端
    await page.route('**/api/user', (route) =>
      route.fulfill({ json: { name: 'Alice', role: 'admin' } })
    );
    await page.goto('/profile');
    await expect(page.getByText('Alice')).toBeVisible();
  });

  test('视觉回归截图对比', async ({ page }) => {
    await page.goto('/');
    // 首次运行生成基准图，后续对比像素差异
    await expect(page).toHaveScreenshot('homepage.png', { maxDiffPixels: 100 });
  });
});

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

export default defineConfig({
  testDir: './tests',
  fullyParallel: true,          // 文件内并行
  retries: process.env.CI ? 2 : 0, // CI 失败重试，缓解偶发波动
  workers: process.env.CI ? 4 : undefined,
  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: 'mobile', use: { ...devices['iPhone 13'] } },
  ],
});

// jest.config.js —— 设置覆盖率阈值，低于则 CI 失败
module.exports = {
  collectCoverage: true,
  coverageThreshold: {
    global: {
      statements: 80,
      branches: 75,
      functions: 80,
      lines: 80,
    },
    // 对核心模块设更高标准
    './src/utils/': {
      branches: 90,
      functions: 90,
    },
  },
  coverageReporters: ['text', 'lcov', 'html'],
};

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

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    globals: true,          // 无需 import describe/test/expect
    setupFiles: './vitest.setup.ts',
    coverage: {
      provider: 'v8',
      reporter: ['text', 'html'],
    },
  },
});

// 测试写法几乎与 Jest 一致，只需把 jest.fn 换成 vi.fn
import { describe, test, expect, vi } from 'vitest';
import { render, screen } from '@testing-library/react';

test('vitest 测试组件', () => {
  const onClick = vi.fn();
  render(<button onClick={onClick}>点我</button>);
  screen.getByRole('button').click();
  expect(onClick).toHaveBeenCalled();
});

# .github/workflows/test.yml
name: Test
on: [push, pull_request]
jobs:
  unit-and-integration:
    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:ci -- --coverage --maxWorkers=2
      - uses: codecov/codecov-action@v4

  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 chromium
      - run: npm run build && npm run test:e2e
      - uses: actions/upload-artifact@v4
        if: failure()
        with:
          name: playwright-report
          path: playwright-report/

// SearchableList.jsx
function SearchableList({ fetchUrl }) {
  const [query, setQuery] = React.useState('');
  const [items, setItems] = React.useState([]);
  const [loading, setLoading] = React.useState(false);
  const [error, setError] = React.useState(null);

  React.useEffect(() => {
    if (!query) { setItems([]); return; }
    let cancelled = false;
    setLoading(true);
    setError(null);
    fetch(fetchUrl + '?q=' + encodeURIComponent(query))
      .then((r) => { if (!r.ok) throw new Error('请求失败'); return r.json(); })
      .then((data) => { if (!cancelled) setItems(data); })
      .catch((e) => { if (!cancelled) setError(e.message); })
      .finally(() => { if (!cancelled) setLoading(false); });
    return () => { cancelled = true; };
  }, [query, fetchUrl]);

  return (
    <div>
      <input aria-label="搜索" value={query} onChange={(e) => setQuery(e.target.value)} />
      {loading && <p>加载中...</p>}
      {error && <p role="alert">{error}</p>}
      <ul>{items.map((it) => <li key={it.id}>{it.name}</li>)}</ul>
    </div>
  );
}

// SearchableList.test.jsx —— 用 MSW 覆盖成功、空、错误三条路径
import { rest } from 'msw';
import { setupServer } from 'msw/node';
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';

const server = setupServer(
  rest.get('/api/search', (req, res, ctx) => {
    const q = req.url.searchParams.get('q');
    if (q === 'empty') return res(ctx.json([]));
    return res(ctx.json([{ id: 1, name: q + ' 结果' }]));
  })
);
beforeAll(() => server.listen());
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

describe('SearchableList', () => {
  test('输入后展示搜索结果', async () => {
    const user = userEvent.setup();
    render(<SearchableList fetchUrl="/api/search" />);
    await user.type(screen.getByLabelText('搜索'), 'react');
    expect(await screen.findByText('react 结果')).toBeInTheDocument();
  });

  test('无结果时列表为空', async () => {
    const user = userEvent.setup();
    render(<SearchableList fetchUrl="/api/search" />);
    await user.type(screen.getByLabelText('搜索'), 'empty');
    // 等待 loading 消失后断言无列表项
    await waitForElementToBeRemoved(() => screen.queryByText('加载中...'));
    expect(screen.queryByRole('listitem')).not.toBeInTheDocument();
  });

  test('请求失败展示错误', async () => {
    server.use(rest.get('/api/search', (req, res, ctx) => res(ctx.status(500))));
    const user = userEvent.setup();
    render(<SearchableList fetchUrl="/api/search" />);
    await user.type(screen.getByLabelText('搜索'), 'boom');
    expect(await screen.findByRole('alert')).toHaveTextContent('请求失败');
  });
});

import { renderHook, act, waitFor } from '@testing-library/react';

// 1. 测试带异步的 Hook
function useUser(id) {
  const [user, setUser] = React.useState(null);
  React.useEffect(() => {
    fetch('/api/user/' + id).then((r) => r.json()).then(setUser);
  }, [id]);
  return user;
}

test('useUser 加载数据', async () => {
  const { result } = renderHook(() => useUser('1'));
  expect(result.current).toBeNull();
  await waitFor(() => expect(result.current).toEqual({ id: '1', name: 'Alice' }));
});

// 2. 测试 rerender 时 props 变化
test('id 变化重新加载', async () => {
  const { result, rerender } = renderHook(({ id }) => useUser(id), {
    initialProps: { id: '1' },
  });
  await waitFor(() => expect(result.current?.id).toBe('1'));
  rerender({ id: '2' });
  await waitFor(() => expect(result.current?.id).toBe('2'));
});

// 3. 测试 cleanup（unmount 时清理）
test('unmount 时取消订阅', () => {
  const unsubscribe = jest.fn();
  renderHook(() => {
    React.useEffect(() => unsubscribe, []);
  }).unmount();
  expect(unsubscribe).toHaveBeenCalledTimes(1);
});

// 4. 需要 Provider 的 Hook：通过 wrapper 注入
test('useTheme 需要 Provider', () => {
  const wrapper = ({ children }) => <ThemeProvider>{children}</ThemeProvider>;
  const { result } = renderHook(() => useTheme(), { wrapper });
  expect(result.current.theme).toBe('light');
  act(() => result.current.toggleTheme());
  expect(result.current.theme).toBe('dark');
});

// 在 jest.setup.js 中一次性引入
import '@testing-library/jest-dom';

test('jest-dom 常用匹配器', () => {
  render(
    <form>
      <input aria-label="邮箱" required disabled value="a@b.com" readOnly />
      <button disabled>提交</button>
      <span hidden>隐藏文本</span>
    </form>
  );
  const input = screen.getByLabelText('邮箱');
  expect(input).toBeDisabled();
  expect(input).toBeRequired();
  expect(input).toHaveValue('a@b.com');
  expect(screen.getByRole('button')).toBeDisabled();
  expect(screen.getByText('隐藏文本')).not.toBeVisible();
});

// 编写自定义匹配器
expect.extend({
  toBeWithinRange(received, floor, ceiling) {
    const pass = received >= floor && received <= ceiling;
    return {
      pass,
      message: () =>
        '期望 ' + received + (pass ? ' 不' : ' ') + '在 ' + floor + '-' + ceiling + ' 范围内',
    };
  },
});

test('自定义范围匹配器', () => {
  expect(100).toBeWithinRange(90, 110);
});

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

test('调试技巧', () => {
  render(<ComplexComponent />);

  // 1. screen.debug() 打印当前 DOM（可传元素只打印局部）
  screen.debug();
  screen.debug(screen.getByRole('list'));

  // 2. 找不到元素时，logTestingPlaygroundURL 生成可视化调试链接
  screen.logTestingPlaygroundURL();

  // 3. 查看某元素有哪些可用的 role
  // 在断言前临时打印所有可访问角色
});

// 4. 设置更长的调试超时，避免调试时 findBy 提前失败
// configure({ asyncUtilTimeout: 5000 });

// 好的快照：小而聚焦，针对序列化数据
test('格式化函数输出稳定', () => {
  expect(formatInvoice({ amount: 100, tax: 0.1 })).toMatchInlineSnapshot(`
    {
      "amount": 100,
      "tax": 10,
      "total": 110,
    }
  `);
});

// 内联快照直接写在测试里，diff 时一目了然
// 反例：对整个复杂页面 toMatchSnapshot，任何微小改动都触发大 diff