rstest-best-practices

Rstest 最佳实践

设置、编写或审查 Rstest 项目时，请遵循以下规则。

工作流

• 编辑前，先检查现有的包管理器、依赖策略、模块模式、构建配置、测试布局和框架约定。
• 添加 @rstest/core、包级测试脚本，以及扩展名与包模块模式相匹配的配置文件。
• 只有在能够降低维护成本且保持兼容时，才复用现有构建配置。适配器是可选的；如果适配器集成不兼容或成本过高，请使用独立的 Rstest 配置，并明确复现所需的别名、插件、定义、环境和外部依赖。
• 有意配置测试发现、环境和设置文件。除非空测试集是预期且有文档说明的状态，否则不要启用 passWithNoTests。
• 先使用 rstest list 验证测试发现，再运行针对性测试、完整测试套件，以及项目现有的构建或类型检查命令。

配置和环境

• 使用来自 @rstest/core 的 defineConfig，并选择与包模块模式兼容的配置文件扩展名。
• 优先从 @rstest/core 显式导入，而不是使用 globals: true。
• 使用 setupFiles 配置共享匹配器和清理逻辑；普通构建集成使用 plugins、resolve 或 source，仅在必要时使用底层 tools。
• 如果包的测试布局不是标准布局，请显式设置 include；不要假设默认发现模式适用。
• 服务端/SSR 测试使用 node，模拟 DOM 测试使用 happy-dom 或 jsdom，真实浏览器行为测试使用 Browser Mode；请显式安装所选环境包。
• 对于 React 或 Vue 组件测试，请注册相应的构建插件，使用对应的 Testing Library，并在设置文件中集中配置匹配器扩展和清理逻辑。
• 仅当环境或配置确实不同时才使用多个测试项目；将 reporters、coverage、pool、isolation 和 bail 等全局选项保留在根配置中。

编写测试

• 优先编写规模较小、验证单一公开行为的测试；有意使用 .skip 或 .todo，绝不要提交 .only。
• 测试 API 和测试文件应与项目使用相同的模块系统；未经运行时和打包器行为验证，不要混用 ESM/CJS 假设。
• 优先使用 await expect(promise).resolves... 和 .rejects...，而不是可能遗漏断言的 try/catch 模式。
• 仅对小型工具使用 includeSource，用 import.meta.rstest 保护测试，并在生产构建中将其设为 false。

模拟

• 函数使用 rs.fn()，对象方法使用 rs.spyOn()，模块使用 rs.mock() 工厂；应模拟外部边界，而不是被测对象。
• 根据测试之间需要清除调用、重置实现还是恢复原始方法，选择 clearMocks、resetMocks 或 restoreMocks。
• 选择与模块系统匹配的模块模拟 API；验证精确的请求字符串，并在被测模块求值前注册提升式/静态模拟。
• 模块模拟会替换运行时行为，但不一定会从 Rspack 构建图中移除真实依赖。只有在构建仍会遍历不需要或不可用的依赖时，才使用别名或范围严格限定的外部依赖配置，并验证运行时外部化格式。

快照和覆盖率

• 保持快照简短且确定：短输出使用内联快照，大型结构化输出使用文件快照，路径或不稳定数据使用序列化器。仔细审查每次更新。
• 使用 --coverage 或 coverage.enabled 启用覆盖率。
• 选择已安装的 Rstest 版本支持的覆盖率提供程序，并显式添加对应的包；未经检查项目需求，不要照搬 V8 或 Istanbul 提供程序的选择。
• 添加阈值前，有意设置 coverage.include；分别为人工查看和 CI 产物选择 reporters。

运行与 CI

• 单次运行请使用 rstest；rstest run 是可选的显式等效命令。仅在本地开发时使用 rstest --watch 或 rstest watch。
• 使用 rstest list 验证测试发现；使用位置过滤器或 -t 进行定向运行，使用 -u 有意更新快照，使用 -c 指定非默认配置。
• 在 CI 中，切勿使用监视模式。分发测试时，请使用分片与 blob 报告，并使用 rstest merge-reports；如果 CI 系统要求机器可读的结果，请使用 JUnit。
• 如果通过测试的日志过于嘈杂，可以考虑使用 silent: 'passed-only'；诊断设置或运行时输出时，可暂时禁用它。

优先排查

• 从针对性复现和 --reporter=verbose 开始；对于嘈杂或不明确的控制台输出，请使用 --printConsoleTrace。
• 使用 DEBUG=rstest，并检查 dist/.rstest-temp/.rsbuild/，以验证最终的 Rstest/Rsbuild/Rspack 配置和生成的构建输出。
• 对于运行时故障，可通过 Rstest VS Code 扩展或 JavaScript Debug Terminal 设置断点。
• 使用 rstest-debugging 系统地诊断启动、构建、运行时、日志、内存或性能问题。

文档

• 如需查看最新的 Rstest 文档，请访问 https://rstest.rs/llms.txt