migrate-to-rstest

迁移到 Rstest

目标

以最小的行为变更，迁移最小可运行的 Jest、Vitest 或 Playwright Test 范围。使用与已安装 Rstest 版本相匹配的文档和类型；只有在能力门控确认适用后，才使用最新的在线文档。

工作流

1. 使用 references/detect-test-framework.md 检测测试运行器、环境、Rstack 集成以及最小可运行范围。
2. 在选择 Rstest、覆盖率、适配器或插件 API 之前，先运行 references/dependency-install-gate.md。
3. 编辑前，记录确切命令、Node 和测试运行器版本、环境、文件／测试／跳过项／快照以及失败情况。捕获迁移前的测试清单，并在整个迁移过程中遵循 references/discovery-parity.md。
4. 对于 Jest，阅读 references/jest-migration-deltas.md；对于 Vitest，阅读 references/vitest-migration-deltas.md；涉及全局 API 时，也阅读 references/global-api-migration.md；检测到 Playwright Test 运行器时，阅读 references/playwright-migration-deltas.md。对于运行器并非 Playwright Test 的纯浏览器请求，不要加载 Playwright 相关文档。编辑测试主体之前，先迁移脚本、配置和 setup；优先采用适配器或 Rsbuild/Rspack 修复，而不是大范围重写测试。
5. 如果加载配置时出现 [MODULE_TYPELESS_PACKAGE_JSON]，使用 references/config-module-type.md。不要屏蔽此警告，也不要未经审查就更改整个包的模块类型。
6. 使迁移范围在语义上通过测试。按以下顺序修复失败：依赖版本不匹配、配置／解析器、测试发现、setup／环境／覆盖率、模拟／计时器／快照，然后是测试主体。
7. 将迁移后的清单和执行数量与基线进行比较。明确说明每个新增、移除、跳过或排除的测试；不能仅因测试通过就称其等效。对于 Jest 快照迁移，还要完成 references/jest-migration-deltas.md 中的快照清理和 unchecked 验证。
8. 移除不再需要的临时别名、诊断钩子和复制来的旧版变通方案。仅保留经行为或测量证明必需的配置。
9. 如果耗时、构建、测试运行时间、日志或内存出现明显退化，且有 rstest-debugging 技能时，加载并遵循该技能。否则，使用 references/performance-diagnosis.md 中的迁移备用方案，然后根据测得的瓶颈阅读 references/dependency-bundling-performance.md 和／或 references/mocked-module-build-graph.md。每次只更改一个变量。
10. 正确性和性能验证完成后，仅移除迁移范围所涉及的旧版文件和依赖。总结行为一致性、测试发现差异、不受支持的字段、保留的兼容性配置、性能权衡和待办事项。

防护原则

• 保持范围尽可能小。不要仅因多个范围共用一个 lockfile，就扩大 monorepo 的迁移范围。
• 不要为了让迁移通过而更改生产行为、断言、测试名称、场景、覆盖率阈值或忽略指令。
• 不要引入 jest／vi 垫片或别名；使用 references/global-api-migration.md 重写调用点。
• 不要悄悄丢弃未知配置字段或历史排除项。逐一验证、替换或报告。
• 不要比较测试清单、Node 版本、覆盖率模式、缓存状态或 worker 设置不同情况下的性能。
• 在 Rstest 通过之前，保留原测试运行器。本地 Rstest 检出版本仅用于注明标签的诊断，最终结果须使用项目已安装的依赖进行验证。
• 大量编辑测试或更改任何生产源代码之前，先升级处理：说明较小的配置／setup 修复为何无效、有哪些选项及其风险，并给出推荐方案。

高风险 Rstest 差异

• rstest / rstest run 只运行一次；监视模式为 rstest --watch 或 rstest watch。
• globals 默认值为 false；要保留全局 API，需设置 globals: true 并使用 @rstest/core/globals 类型。
• Rstest 会在测试运行前构建。rs.mock() 是运行时替换，本身不会从模块依赖图中移除真实模块。
• 依赖打包会用编译器工作量换取运行时 Node 加载。无论“全部打包”还是“全部外部化”，都不一定更快；请用有代表性的文件和完整范围进行测量。
• 外部化模块的运行时模拟必须与请求和模块格式完全匹配。如果任何测试需要真实模块，就不应使用全局配置级别的 external。