react-testing

React 测试技能

此技能适用于关注用户行为的 React 测试：Vitest/Jest 配置、Testing Library 查询、user-event 交互流程、异步 UI、Hooks、提供程序、模拟、集成测试、无障碍检查以及媒体组件测试。

何时使用此技能

当用户提出的任务符合 frontmatter 触发条件时使用，尤其是涉及此领域的实现指导、调试、架构选择、生产环境加固或性能敏感决策。先从此协调器入手，然后加载与所需详细程度相匹配的参考文件。

核心工作流

1. 先配置测试运行器和 jsdom 环境，然后在测试设置中集中配置 @testing-library/jest-dom、清理逻辑和浏览器 API 模拟。
2. 从用户视角编写测试：优先使用角色、标签、文本、占位符和值展示查询，最后再使用测试 ID。
3. 使用 userEvent.setup() 进行交互，并使用 waitFor 或 findBy 查询等待异步状态变化。
4. 在模块或网络边界进行模拟，而不是模拟组件内部状态；并在测试之间重置模拟。
5. 创建支持提供程序的渲染工具，以处理上下文、路由器、查询客户端、主题及其他应用级包装器。
6. 对于媒体组件，模拟 jsdom 的功能缺失，例如 HTMLMediaElement.play、pause、load、元数据属性和 IntersectionObserver。

关键注意事项

• 避免断言组件状态等实现细节；应断言可见行为和无障碍状态。
• fireEvent 的抽象层级低于 userEvent；除非必须直接触发浏览器或媒体事件，否则优先使用 userEvent。
• 异步断言应等待 UI 变化，而不是等待任意计时器。
• jsdom 不支持真实的媒体播放、布局或浏览器编解码器；应有针对性地模拟这些 API。
• 如果渲染工具没有为每次测试创建新的客户端，且每次测试后未执行清理，则提供程序状态可能会在测试间泄漏。

参考资料索引

• references/react-testing-complete-guide.md - 完整的原始指南，涵盖设置、组件测试、表单、异步组件、Hooks、上下文、模拟、集成测试、无障碍测试、测试工具以及视频/媒体测试。
• references/testing-recipes.md - 此技能已有的其他测试方法。

回复指导

• 除非有明确的兼容性或性能理由建议更换，否则保留用户现有的框架、库和工具选择。
• 仅针对当前任务提供可直接复制粘贴的代码；否则请指向相关参考章节。
• 针对生产工作流，说明权衡、故障模式和验证步骤。
• 优先选择无障碍、易维护且可衡量的解决方案，而不是巧妙的微优化。