React / 系统课时
测试 React 组件
测试 React 组件
本课用一个可提交姓名的表单组件完成最小测试闭环:在 jsdom 中渲染组件,按可访问角色查询输入框和按钮,模拟输入与点击,并断言按钮状态和页面反馈。完成后,你可以为常见交互组件编写稳定、接近真实用户行为的测试。
学习目标
- 配置 Vitest、jsdom 与 React Testing Library 测试环境
- 使用
render、screen和语义查询定位页面元素 - 使用
userEvent模拟交互并验证可见结果
准备测试环境
以下示例基于 React 18、TypeScript 和 Vite。安装测试运行器、DOM 环境、断言扩展及用户交互工具:
npm install --save-dev vitest jsdom @testing-library/react @testing-library/jest-dom @testing-library/user-event预期输出如下,<N> 会随已有依赖和锁文件变化:
added <N> packages创建 vitest.config.ts,让测试在 jsdom 中运行,并统一加载断言扩展:
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:
import '@testing-library/jest-dom/vitest'配置生效后,toBeInTheDocument、toBeDisabled 和 toHaveTextContent 等 DOM 断言可直接在 Vitest 中使用。验证方式是运行本课末尾的测试命令,而不是单独执行配置文件。
编写被测组件
创建 src/ProfileForm.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 等内部状态,而是观察按钮是否可用以及提交后的页面内容:
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')
})
})运行指定测试文件:
npx vitest run src/ProfileForm.test.tsx预期输出:
✓ 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 或私有函数作为主要断言对象,否则重构实现细节会导致无意义的测试失败。