React / 系统课时
渲染组件与查询元素
渲染组件与查询元素
组件测试的第一步不是寻找某个类名,而是把组件渲染到测试 DOM,再按用户能够识别的语义查找元素。本课掌握 render、screen 以及 getBy、queryBy、findBy 三类查询的选择方法。
学习目标
- 在测试环境中渲染 React 组件
- 按角色、标签和可见文本查询元素
- 根据元素出现时机选择正确的查询类型
渲染组件并使用语义查询
render 会把组件挂载到测试环境提供的 DOM 容器中。测试通常通过全局 screen 查询当前页面,这样代码更接近用户面对整个页面查找控件的方式,也避免依赖 container.querySelector。
查询优先级应从可访问语义开始:能用 getByRole 就先使用角色和可访问名称;表单控件也可以使用 getByLabelText;只有元素没有合适语义时,才考虑文本、测试标识或底层选择器。
使用三类查询
下面的组件会立即显示标题和按钮,点击后异步显示保存结果。测试分别演示同步存在、不应存在和稍后出现三种情况。
// src/ProfileEditor.tsx
import { useState } from "react";
export function ProfileEditor() {
const [saved, setSaved] = useState(false);
async function save() {
await Promise.resolve();
setSaved(true);
}
return (
<section>
<h1>编辑资料</h1>
<label>
昵称
<input defaultValue="小林" />
</label>
<button onClick={() => void save()}>保存</button>
{saved && <p role="status">保存成功</p>}
</section>
);
}// src/ProfileEditor.test.tsx
import { render, screen } from "@testing-library/react";
import "@testing-library/jest-dom/vitest";
import userEvent from "@testing-library/user-event";
import { expect, test } from "vitest";
import { ProfileEditor } from "./ProfileEditor";
test("保存后显示结果", async () => {
const user = userEvent.setup();
render(<ProfileEditor />);
// getBy 用于此刻必须存在的唯一元素
expect(screen.getByRole("heading", { name: "编辑资料" })).toBeInTheDocument();
expect(screen.getByLabelText("昵称")).toHaveValue("小林");
// queryBy 用于确认元素当前不存在
expect(screen.queryByRole("status")).not.toBeInTheDocument();
await user.click(screen.getByRole("button", { name: "保存" }));
// findBy 等待异步出现的元素
expect(await screen.findByRole("status")).toHaveTextContent("保存成功");
});预期结果:测试通过。若页面缺少“昵称”标签,getByLabelText 会失败;若点击后没有显示状态信息,findByRole 会在等待超时后失败。
查询类型的选择规则
getBy 在找不到元素或找到多个元素时立即抛错,适合断言当前必须存在的单个元素。queryBy 找不到时返回 null,适合断言某个元素不存在。findBy 返回 Promise,会等待元素出现,适合请求完成、定时更新或异步状态变化。
当页面预期存在多个同类元素时,应使用 getAllBy、queryAllBy 或 findAllBy。不要为了让测试通过而随意改成复数查询;先确认需求是否真的允许多个匹配项。
可访问性与查询调试
getByRole 的 name 指可访问名称,通常来自按钮文字、关联的 label、aria-label 或标题内容。一个图标按钮若没有文字,应提供准确的 aria-label,这不仅让测试可查询,也让辅助技术能够理解控件用途。
测试无法通过语义查询找到元素,常常说明页面本身缺少标签、角色或名称。此时应优先修正组件的可访问性,而不是立即添加 data-testid。测试标识适合画布、复杂可视化或确实没有用户语义的技术节点。
调试查询失败
查询失败时,错误信息通常会列出当前 DOM 和可访问角色。可以临时使用 screen.debug() 查看渲染结果,但最终测试应保留明确断言,不依赖人工观察输出。
// 调试片段:只在定位问题时临时使用
render(<ProfileEditor />);
screen.debug();预期结果:测试终端打印当前组件的 HTML 结构。定位完成后应删除调试调用,避免持续产生无关日志。