React / 系统课时

测试 React 组件

测试 React 组件

本课用一个可提交姓名的表单组件完成最小测试闭环:在 jsdom 中渲染组件,按可访问角色查询输入框和按钮,模拟输入与点击,并断言按钮状态和页面反馈。完成后,你可以为常见交互组件编写稳定、接近真实用户行为的测试。

学习目标

  • 配置 Vitest、jsdom 与 React Testing Library 测试环境
  • 使用 render、screen 和语义查询定位页面元素
  • 使用 userEvent 模拟交互并验证可见结果

准备测试环境

以下示例基于 React 18、TypeScript 和 Vite。安装测试运行器、DOM 环境、断言扩展及用户交互工具:

bash
npm install --save-dev vitest jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event

预期输出如下,<N> 会随已有依赖和锁文件变化:

text
added <N> packages

创建 vitest.config.ts,让测试在 jsdom 中运行,并统一加载断言扩展:

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

export default defineConfig({
  plugins: [react()],
  test: {
    environment: 'jsdom',
    setupFiles: './src/test/setup.ts',
  },
})

创建 src/test/setup.ts:

ts
import '@testing-library/jest-dom/vitest'

配置生效后,toBeInTheDocument、toBeDisabled 和 toHaveTextContent 等 DOM 断言可直接在 Vitest 中使用。验证方式是运行本课末尾的测试命令,而不是单独执行配置文件。

编写被测组件

创建 src/ProfileForm.tsx。组件初始禁用提交按钮,用户输入非空姓名后允许提交,并在页面上显示欢迎信息:

tsx
import { useState, type FormEvent } from 'react'

export function ProfileForm() {
  const [name, setName] = useState('')
  const [message, setMessage] = useState('')

  function handleSubmit(event: FormEvent<HTMLFormElement>) {
    event.preventDefault()
    // 业务结果通过页面可见内容呈现,测试无需读取组件内部状态。
    setMessage(`欢迎,${name.trim()}`)
  }

  const canSubmit = name.trim().length > 0

  return (
    <form onSubmit={handleSubmit}>
      <label htmlFor="name">姓名</label>
      <input
        id="name"
        value={name}
        onChange={(event) => setName(event.target.value)}
      />
      <button type="submit" disabled={!canSubmit}>
        提交
      </button>
      {message && <p role="status">{message}</p>}
    </form>
  )
}

标签与输入框通过 htmlFor 和 id 建立关联,状态消息使用 role="status"。这些语义既改善可访问性,也让测试能按用户感知到的名称定位元素。

按用户视角编写测试

创建 src/ProfileForm.test.tsx。测试不读取 name、message 等内部状态,而是观察按钮是否可用以及提交后的页面内容:

tsx
import { render, screen } from '@testing-library/react'
import userEvent from '@testing-library/user-event'
import { describe, expect, it } from 'vitest'
import { ProfileForm } from './ProfileForm'

describe('ProfileForm', () => {
  it('输入姓名后允许提交并显示欢迎信息', async () => {
    const user = userEvent.setup()
    render(<ProfileForm />)

    const nameInput = screen.getByRole('textbox', { name: '姓名' })
    const submitButton = screen.getByRole('button', { name: '提交' })

    // 初始状态体现真实业务约束:空姓名不能提交。
    expect(submitButton).toBeDisabled()

    await user.type(nameInput, 'Ada')
    expect(submitButton).toBeEnabled()

    // userEvent 返回 Promise,必须等待完整交互和 React 更新结束。
    await user.click(submitButton)

    expect(screen.getByRole('status')).toHaveTextContent('欢迎,Ada')
  })
})

运行指定测试文件:

bash
npx vitest run src/ProfileForm.test.tsx

预期输出:

text
✓ src/ProfileForm.test.tsx (1 test)
Test Files  1 passed (1)
Tests       1 passed (1)

查询与断言边界

优先使用 getByRole、getByLabelText 等语义查询,因为它们同时验证页面是否具备可理解的名称。getBy... 适合必须立即存在的元素;判断元素不存在时使用 queryBy...;等待异步出现的元素则使用 findBy...。

模拟输入、点击和键盘操作时优先使用 userEvent,并对调用使用 await。只有需要触发浏览器不易由用户直接完成的底层事件时,才考虑 fireEvent。不要把 CSS 类名、组件 state 或私有函数作为主要断言对象,否则重构实现细节会导致无意义的测试失败。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

测试 React 组件

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通