TDesign 组件测试指南提供 TDesign React 组件单元测试的完整 SOP 和最佳实践。
触发条件
当需要执行以下任务时使用此技能：为组件编写单元测试；更新或修复测试用例；运行快照测试；提高测试覆盖率。
测试框架和工具
Vitest 用作测试运行器；@testing-library/react 用于 React 组件测试；@testing-library/user-event 用于用户交互模拟；@testing-library/jest-dom 用于 DOM 断言扩展。
测试文件规范
文件位置与命名：packages/components/[component-name]/ 下的 tests/ 目录，包含 vitest-[component-name].test.jsx 单元测试文件与 snapshots/ 快照文件（自动生成）。命名格式为 vitest-[component-name].test.jsx。注意：测试文件由 API 平台生成，文件头部有注释标记。
测试工具导入
import { render, fireEvent, vi } from '@test/utils'; 以及 import { ComponentName } from '..';。@test/utils 已封装常用工具，包括 render、fireEvent、vi、act、userEvent、mockDelay、simulateInputChange、simulateKeydownEvent。
SOP 流程
Step 1 基础渲染测试：验证组件能否正常渲染，使用 render 并断言容器子节点的类名。
Step 2 Props 测试：为每个 prop 编写测试用例。Boolean prop 测试默认值、true、false 三种情况并配合快照；枚举 prop 可遍历取值数组，默认值不添加额外类名，其余断言对应类名并配合快照。
Step 3 TNode 渲染测试：验证 children 与 icon 等自定义渲染内容能正确出现。
Step 4 事件测试：使用 vi.fn() 与 fireEvent 触发事件，断言回调被调用及参数类型；禁用状态下事件不应触发。
Step 5 异步操作测试：使用 mockDelay 等待异步完成后再断言。
Step 6 用户交互测试：使用 userEvent.setup() 模拟输入等复杂交互并断言回调与值。
快照测试
CSR 快照测试位于 test/snap/csr.test.jsx，自动为所有 _example/*.tsx 生成快照，运行命令为 NODE_ENV=test-snap pnpm test。SSR 快照测试位于 test/snap/ssr.test.jsx，测试服务端渲染输出。更新快照可使用 pnpm test -- --update，或更新特定组件快照 pnpm test button -- --update。
运行测试命令
运行所有单元测试：pnpm test；运行特定组件测试：pnpm test button；运行测试并生成覆盖率报告：pnpm test -- --coverage；运行快照测试：NODE_ENV=test-snap pnpm test；交互式测试模式：pnpm test -- --ui。
常见测试模式
测试 Loading 状态：断言 t-is-loading 类与 .t-loading 元素。测试 DOM 属性：断言 href 属性值与标签名。测试 className 组合：断言组件类与自定义类同时存在。Mock ResizeObserver：在 beforeAll 中给 global.ResizeObserver 赋值。Mock 时间：引入 MockDate，在 beforeEach 中 set，在 afterEach 中 reset。
测试检查清单
编写测试时确保覆盖：默认渲染；所有 boolean props（true/false 两种情况）；所有枚举 props 的每个值；TNode 类型 props；事件回调触发；禁用状态下的行为；加载状态；边界情况（空值、极端值）；快照测试。
测试覆盖率要求
整体覆盖率目标大于 80%；新组件要求大于 90% 行覆盖率；核心逻辑要求 100% 分支覆盖。
常见问题
测试文件是否可以手动编辑：vitest-*.test.jsx 文件由 API 平台生成，文件头有注释标记，可以在其基础上添加额外测试，但核心测试应通过 API 平台维护。如何处理异步组件：使用 mockDelay 或 act wrapper，确保异步操作完成后再进行断言。快照测试失败怎么办：首先检查变更是否预期内，如果是预期变更，使用 --update 参数更新快照。