Back to Details

react-testing

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

React Testing Library

React Testing Library

This skill focuses on React-specific testing patterns. For general DOM testing patterns (queries, userEvent, async, accessibility), load the 
front-end-testing
skill. For TDD workflow, load the 
tdd
skill.
本技能专注于React专属的测试模式。若需通用DOM测试模式（查询、userEvent、异步、可访问性相关），请加载
front-end-testing
技能。若需了解TDD工作流，请加载
tdd
技能。

Testing React Components

测试React组件

React components are just functions that return JSX. Test them like functions: inputs (props) → output (rendered DOM).
React组件本质是返回JSX的函数。请像测试函数一样测试它们：输入（props）→ 输出（渲染后的DOM）。

Basic Component Testing

基础组件测试

tsx
// ✅ CORRECT - Test component behavior
it('should display user name when provided', () => {
  render(<UserProfile name="Alice" email="alice@example.com" />);

  expect(screen.getByText(/alice/i)).toBeInTheDocument();
  expect(screen.getByText(/alice@example.com/i)).toBeInTheDocument();
});
tsx
// ❌ WRONG - Testing implementation
it('should set name state', () => {
  const wrapper = mount(<UserProfile name="Alice" />);
  expect(wrapper.state('name')).toBe('Alice'); // Internal state!
});
tsx
// ✅ 正确示例 - 测试组件行为
it('should display user name when provided', () => {
  render(<UserProfile name="Alice" email="alice@example.com" />);

  expect(screen.getByText(/alice/i)).toBeInTheDocument();
  expect(screen.getByText(/alice@example.com/i)).toBeInTheDocument();
});
tsx
// ❌ 错误示例 - 测试内部实现
it('should set name state', () => {
  const wrapper = mount(<UserProfile name="Alice" />);
  expect(wrapper.state('name')).toBe('Alice'); // 内部状态!
});

Testing Props

测试Props

tsx
// ✅ CORRECT - Test how props affect rendered output
it('should call onSubmit when form submitted', async () => {
  const handleSubmit = vi.fn();
  const user = userEvent.setup();

  render(<LoginForm onSubmit={handleSubmit} />);

  await user.type(screen.getByLabelText(/email/i), 'test@example.com');
  await user.click(screen.getByRole('button', { name: /submit/i }));

  expect(handleSubmit).toHaveBeenCalledWith({
    email: 'test@example.com',
  });
});
tsx
// ✅ 正确示例 - 测试Props对渲染输出的影响
it('should call onSubmit when form submitted', async () => {
  const handleSubmit = vi.fn();
  const user = userEvent.setup();

  render(<LoginForm onSubmit={handleSubmit} />);

  await user.type(screen.getByLabelText(/email/i), 'test@example.com');
  await user.click(screen.getByRole('button', { name: /submit/i }));

  expect(handleSubmit).toHaveBeenCalledWith({
    email: 'test@example.com',
  });
});

Testing Conditional Rendering

测试条件渲染

tsx
// ✅ CORRECT - Test what user sees in different states
it('should show error message when login fails', async () => {
  server.use(
    http.post('/api/login', () => {
      return HttpResponse.json({ error: 'Invalid credentials' }, { status: 401 });
    })
  );

  const user = userEvent.setup();
  render(<LoginForm />);

  await user.type(screen.getByLabelText(/email/i), 'wrong@example.com');
  await user.click(screen.getByRole('button', { name: /submit/i }));

  await screen.findByText(/invalid credentials/i);
});
tsx
// ✅ 正确示例 - 测试不同状态下用户可见的内容
it('should show error message when login fails', async () => {
  server.use(
    http.post('/api/login', () => {
      return HttpResponse.json({ error: 'Invalid credentials' }, { status: 401 });
    })
  );

  const user = userEvent.setup();
  render(<LoginForm />);

  await user.type(screen.getByLabelText(/email/i), 'wrong@example.com');
  await user.click(screen.getByRole('button', { name: /submit/i }));

  await screen.findByText(/invalid credentials/i);
});

Testing React Hooks

测试React Hooks

Custom Hooks with renderHook

使用renderHook测试自定义Hooks

Built into React Testing Library (since v13):
tsx
import { renderHook } from '@testing-library/react';

it('should toggle value', () => {
  const { result } = renderHook(() => useToggle(false));

  expect(result.current.value).toBe(false);

  act(() => {
    result.current.toggle();
  });

  expect(result.current.value).toBe(true);
});
Pattern:
  • result.current
    - Current return value of hook
  • act()
    - Wrap state updates
  • rerender()
    - Re-run hook with new props
该功能内置于React Testing Library（v13及以上版本）：
tsx
import { renderHook } from '@testing-library/react';

it('should toggle value', () => {
  const { result } = renderHook(() => useToggle(false));

  expect(result.current.value).toBe(false);

  act(() => {
    result.current.toggle();
  });

  expect(result.current.value).toBe(true);
});
模式说明：
  • result.current
    - Hook的当前返回值
  • act()
    - 包裹状态更新操作
  • rerender()
    - 使用新Props重新运行Hook

Hooks with Props

测试带Props的Hooks

tsx
it('should accept initial value', () => {
  const { result, rerender } = renderHook(
    ({ initialValue }) => useCounter(initialValue),
    { initialProps: { initialValue: 10 } }
  );

  expect(result.current.count).toBe(10);

  // Test with different initial value
  rerender({ initialValue: 20 });
  expect(result.current.count).toBe(20);
});
tsx
it('should accept initial value', () => {
  const { result, rerender } = renderHook(
    ({ initialValue }) => useCounter(initialValue),
    { initialProps: { initialValue: 10 } }
  );

  expect(result.current.count).toBe(10);

  // 使用不同初始值测试
  rerender({ initialValue: 20 });
  expect(result.current.count).toBe(20);
});

Testing Context

测试Context

wrapper Option

wrapper选项

For hooks that need context providers:
tsx
const { result } = renderHook(() => useAuth(), {
  wrapper: ({ children }) => (
    <AuthProvider>
      {children}
    </AuthProvider>
  ),
});

expect(result.current.user).toBeNull();

act(() => {
  result.current.login({ email: 'test@example.com' });
});

expect(result.current.user).toEqual({ email: 'test@example.com' });
适用于需要Context提供者的Hooks：
tsx
const { result } = renderHook(() => useAuth(), {
  wrapper: ({ children }) => (
    <AuthProvider>
      {children}
    </AuthProvider>
  ),
});

expect(result.current.user).toBeNull();

act(() => {
  result.current.login({ email: 'test@example.com' });
});

expect(result.current.user).toEqual({ email: 'test@example.com' });

Multiple Providers

多提供者嵌套

tsx
const AllProviders = ({ children }) => (
  <AuthProvider>
    <ThemeProvider>
      <RouterProvider>
        {children}
      </RouterProvider>
    </ThemeProvider>
  </AuthProvider>
);

const { result } = renderHook(() => useMyHook(), {
  wrapper: AllProviders,
});
tsx
const AllProviders = ({ children }) => (
  <AuthProvider>
    <ThemeProvider>
      <RouterProvider>
        {children}
      </RouterProvider>
    </ThemeProvider>
  </AuthProvider>
);

const { result } = renderHook(() => useMyHook(), {
  wrapper: AllProviders,
});

Testing Components with Context

测试依赖Context的组件

tsx
// ✅ CORRECT - Wrap component in provider
const renderWithAuth = (ui, { user = null, ...options } = {}) => {
  return render(
    <AuthProvider initialUser={user}>
      {ui}
    </AuthProvider>,
    options
  );
};

it('should show user menu when authenticated', () => {
  renderWithAuth(<Dashboard />, {
    user: { name: 'Alice', role: 'admin' },
  });

  expect(screen.getByRole('button', { name: /user menu/i })).toBeInTheDocument();
});
tsx
// ✅ 正确示例 - 将组件包裹在提供者中
const renderWithAuth = (ui, { user = null, ...options } = {}) => {
  return render(
    <AuthProvider initialUser={user}>
      {ui}
    </AuthProvider>,
    options
  );
};

it('should show user menu when authenticated', () => {
  renderWithAuth(<Dashboard />, {
    user: { name: 'Alice', role: 'admin' },
  });

  expect(screen.getByRole('button', { name: /user menu/i })).toBeInTheDocument();
});

Testing Forms

测试表单

Controlled Inputs

受控输入框

tsx
it('should update input value as user types', async () => {
  const user = userEvent.setup();

  render(<SearchInput />);

  const input = screen.getByLabelText(/search/i);

  await user.type(input, 'react');

  expect(input).toHaveValue('react');
});
tsx
it('should update input value as user types', async () => {
  const user = userEvent.setup();

  render(<SearchInput />);

  const input = screen.getByLabelText(/search/i);

  await user.type(input, 'react');

  expect(input).toHaveValue('react');
});

Form Submissions

表单提交

tsx
it('should submit form with user input', async () => {
  const handleSubmit = vi.fn();
  const user = userEvent.setup();

  render(<RegistrationForm onSubmit={handleSubmit} />);

  await user.type(screen.getByLabelText(/name/i), 'Alice');
  await user.type(screen.getByLabelText(/email/i), 'alice@example.com');
  await user.type(screen.getByLabelText(/password/i), 'password123');
  await user.click(screen.getByRole('button', { name: /sign up/i }));

  expect(handleSubmit).toHaveBeenCalledWith({
    name: 'Alice',
    email: 'alice@example.com',
    password: 'password123',
  });
});
tsx
it('should submit form with user input', async () => {
  const handleSubmit = vi.fn();
  const user = userEvent.setup();

  render(<RegistrationForm onSubmit={handleSubmit} />);

  await user.type(screen.getByLabelText(/name/i), 'Alice');
  await user.type(screen.getByLabelText(/email/i), 'alice@example.com');
  await user.type(screen.getByLabelText(/password/i), 'password123');
  await user.click(screen.getByRole('button', { name: /sign up/i }));

  expect(handleSubmit).toHaveBeenCalledWith({
    name: 'Alice',
    email: 'alice@example.com',
    password: 'password123',
  });
});

Form Validation

表单验证

tsx
it('should show validation errors for invalid input', async () => {
  const user = userEvent.setup();

  render(<RegistrationForm />);

  // Submit empty form
  await user.click(screen.getByRole('button', { name: /sign up/i }));

  // Validation errors appear
  expect(screen.getByText(/name is required/i)).toBeInTheDocument();
  expect(screen.getByText(/email is required/i)).toBeInTheDocument();
  expect(screen.getByText(/password is required/i)).toBeInTheDocument();
});
tsx
it('should show validation errors for invalid input', async () => {
  const user = userEvent.setup();

  render(<RegistrationForm />);

  // 提交空表单
  await user.click(screen.getByRole('button', { name: /sign up/i }));

  // 验证错误提示出现
  expect(screen.getByText(/name is required/i)).toBeInTheDocument();
  expect(screen.getByText(/email is required/i)).toBeInTheDocument();
  expect(screen.getByText(/password is required/i)).toBeInTheDocument();
});

React-Specific Anti-Patterns

React专属反模式

1. Unnecessary act() wrapping

1. 不必要的act()包裹

❌ WRONG - Manual act() everywhere
tsx
act(() => {
  render(<MyComponent />);
});

await act(async () => {
  await user.click(button);
});
✅ CORRECT - RTL handles it
tsx
render(<MyComponent />);
await user.click(button);
Modern RTL auto-wraps:
  • render()
  • userEvent
    methods
  • fireEvent
  • waitFor
    , 
    findBy
When you DO need manual 
act()
:
  • Custom hook state updates (
    renderHook
    )
  • Direct state mutations (rare, usually bad practice)
❌ 错误示例 - 手动到处使用act()
tsx
act(() => {
  render(<MyComponent />);
});

await act(async () => {
  await user.click(button);
});
✅ 正确示例 - RTL自动处理
tsx
render(<MyComponent />);
await user.click(button);
现代RTL会自动包裹以下操作：
  • render()
  • userEvent
    方法
  • fireEvent
  • waitFor
    , 
    findBy
    系列方法
以下场景需要手动使用
act()
：
  • 自定义Hook的状态更新（
    renderHook
    中）
  • 直接修改状态（罕见，通常是不良实践）

2. Manual cleanup() calls

2. 手动调用cleanup()

❌ WRONG - Manual cleanup
tsx
afterEach(() => {
  cleanup(); // Automatic since RTL 9!
});
✅ CORRECT - No cleanup needed
tsx
// Cleanup happens automatically after each test
❌ 错误示例 - 手动清理
tsx
afterEach(() => {
  cleanup(); // RTL 9及以上版本已自动执行！
});
✅ 正确示例 - 无需手动清理
tsx
// 每个测试结束后会自动执行清理

3. beforeEach render pattern

3. beforeEach中渲染组件的模式

❌ WRONG - Shared render in beforeEach
tsx
let button;
beforeEach(() => {
  render(<MyComponent />);
  button = screen.getByRole('button'); // Shared state across tests
});

it('test 1', () => {
  // Uses shared button from beforeEach
});
✅ CORRECT - Factory function per test
tsx
const renderComponent = () => {
  render(<MyComponent />);
  return {
    button: screen.getByRole('button'),
  };
};

it('test 1', () => {
  const { button } = renderComponent(); // Fresh state
});
For factory patterns, see 
testing
skill.
❌ 错误示例 - 在beforeEach中共享渲染结果
tsx
let button;
beforeEach(() => {
  render(<MyComponent />);
  button = screen.getByRole('button'); // 测试间共享状态
});

it('test 1', () => {
  // 使用beforeEach中共享的button
});
✅ 正确示例 - 每个测试使用工厂函数
tsx
const renderComponent = () => {
  render(<MyComponent />);
  return {
    button: screen.getByRole('button'),
  };
};

it('test 1', () => {
  const { button } = renderComponent(); // 全新状态
});
关于工厂函数模式，请参考
testing
技能。

4. Testing component internals

4. 测试组件内部实现

❌ WRONG - Accessing component internals
tsx
const wrapper = shallow(<MyComponent />);
expect(wrapper.state('isOpen')).toBe(true); // Internal state
expect(wrapper.instance().handleClick).toBeDefined(); // Internal method
✅ CORRECT - Test rendered output
tsx
render(<MyComponent />);
expect(screen.getByRole('dialog')).toBeInTheDocument(); // What user sees
❌ 错误示例 - 访问组件内部细节
tsx
const wrapper = shallow(<MyComponent />);
expect(wrapper.state('isOpen')).toBe(true); // 内部状态
expect(wrapper.instance().handleClick).toBeDefined(); // 内部方法
✅ 正确示例 - 测试组件渲染输出
tsx
render(<MyComponent />);
expect(screen.getByRole('dialog')).toBeInTheDocument(); // 用户可见内容

5. Shallow rendering

5. 浅层渲染

❌ WRONG - Shallow rendering
tsx
const wrapper = shallow(<MyComponent />);
// Child components not rendered - incomplete test
✅ CORRECT - Full rendering
tsx
render(<MyComponent />);
// Full component tree rendered - realistic test
Why: Shallow rendering hides integration bugs between parent/child components.
❌ 错误示例 - 使用浅层渲染
tsx
const wrapper = shallow(<MyComponent />);
// 子组件未被渲染 - 测试不完整
✅ 正确示例 - 完整渲染
tsx
render(<MyComponent />);
// 完整组件树被渲染 - 更贴近真实场景的测试
**原因：**浅层渲染会隐藏父子组件间的集成bug。

Testing Loading States

测试加载状态

tsx
it('should show loading then data', async () => {
  render(<UserList />);

  // Initially loading
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  // Wait for data
  await screen.findByText(/alice/i);

  // Loading gone
  expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
});
tsx
it('should show loading then data', async () => {
  render(<UserList />);

  // 初始显示加载状态
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  // 等待数据加载完成
  await screen.findByText(/alice/i);

  // 加载状态消失
  expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
});

Testing Error Boundaries

测试错误边界

tsx
it('should catch errors with error boundary', () => {
  // Suppress console.error for this test
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});

  render(
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <ThrowsError />
    </ErrorBoundary>
  );

  expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();

  spy.mockRestore();
});
tsx
it('should catch errors with error boundary', () => {
  // 屏蔽本测试中的console.error输出
  const spy = vi.spyOn(console, 'error').mockImplementation(() => {});

  render(
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <ThrowsError />
    </ErrorBoundary>
  );

  expect(screen.getByText(/something went wrong/i)).toBeInTheDocument();

  spy.mockRestore();
});

Testing Portals

测试Portals（传送门）

tsx
it('should render modal in portal', () => {
  render(<Modal isOpen={true}>Modal content</Modal>);

  // Portal renders outside root, but Testing Library finds it
  expect(screen.getByText(/modal content/i)).toBeInTheDocument();
});
Testing Library queries the entire document, so portals work automatically.
tsx
it('should render modal in portal', () => {
  render(<Modal isOpen={true}>Modal content</Modal>);

  // Portal会渲染到根节点外，但Testing Library可以找到它
  expect(screen.getByText(/modal content/i)).toBeInTheDocument();
});
**Testing Library会查询整个文档，**因此Portals可以自动被测试。

Testing Suspense

测试Suspense

tsx
it('should show fallback then content', async () => {
  render(
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );

  // Initially fallback
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  // Wait for component
  await screen.findByText(/lazy content/i);
});
tsx
it('should show fallback then content', async () => {
  render(
    <Suspense fallback={<div>Loading...</div>}>
      <LazyComponent />
    </Suspense>
  );

  // 初始显示占位内容
  expect(screen.getByText(/loading/i)).toBeInTheDocument();

  // 等待组件加载完成
  await screen.findByText(/lazy content/i);
});

Summary Checklist

总结检查清单

React-specific checks:
  • Using 
    render()
    from @testing-library/react (not enzyme's shallow/mount)
  • Using 
    renderHook()
    for custom hooks
  • Using 
    wrapper
    option for context providers
  • No manual 
    act()
    calls (RTL handles it)
  • No manual 
    cleanup()
    calls (automatic)
  • Testing component output, not internal state
  • Using factory functions, not 
    beforeEach
    render
  • Following TDD workflow (see 
    tdd
    skill)
  • Using general DOM testing patterns (see 
    front-end-testing
    skill)
  • Using test factories for data (see 
    testing
    skill)
React专属检查项：
  • 使用@testing-library/react中的
    render()
    （而非enzyme的shallow/mount）
  • 使用
    renderHook()
    测试自定义Hooks
  • 使用
    wrapper
    选项处理Context提供者
  • 无手动
    act()
    调用（RTL自动处理）
  • 无手动
    cleanup()
    调用（自动执行）
  • 测试组件输出，而非内部状态
  • 使用工厂函数，而非
    beforeEach
    中渲染组件
  • 遵循TDD工作流（参考
    tdd
    技能）
  • 使用通用DOM测试模式（参考
    front-end-testing
    技能）
  • 使用测试工厂生成测试数据（参考
    testing
    技能）