变异测试 | Mutation Testing#

使用 StrykerJS 在源码中引入行为变化，检查现有测试能否识别这些变化。测试通过率和覆盖率之外，变异测试可帮助定位断言不足的场景。

本地运行#

使用 Node >=22.20（推荐 Node 24），先按仓库要求安装依赖，再执行：

pnpm mutation       # 校验语义输入；兼容时复用，否则全量运行
pnpm mutation:full  # 强制全量运行并重建本地基线

配置位于 stryker.config.json，使用现有 Vitest 测试，变异范围为 src/ 下的 TypeScript 和 TSX 源码，排除声明文件。

reports/ 和 .stryker-tmp/ 不提交到 Git。

CI 执行策略#

独立的 CI - Mutation Testing 工作流采用以下策略：

将昂贵的变异测试移到 main，减少 PR 反复提交时的重复执行；部分断言不足会延后到合入后才发现。 main 失败由项目维护者查看报告、修复并重跑，必要时按项目流程回退，不能以普通 CI 通过代替变异测试结果。

main 首次成功运行后自动建立共享基线，无需额外服务或 Secret。没有兼容基线时，main 或手动运行会全量执行。 main 与手动运行均不主动取消；同一分支的运行串行，新的待执行任务可能替换旧的待执行任务，不保证每个提交都执行。

每次运行的报告可在 GitHub Actions 的 mutation-reports-* artifact 中下载，保留 14 天。完整报告和增量基线在整轮结束后生成；任务提前中止时可能没有可上传的报告，下次运行也可能仍需全量执行。

合入前手动验证#

高风险改动可在 Actions 中选择同仓库 PR 分支运行；需要完整重测时勾选 full，或使用：

gh workflow run mutation.yml --ref <同仓库PR分支> -f full=true

工作流已存在于默认分支才可手动触发。分支名会移动，验证后需在运行详情和 checkout 日志中核对实际提交 SHA。 分支手动运行只读取兼容的 main 基线，不保存共享基线；外部 fork 分支按项目受信任流程验证，不使用 pull_request_target 运行其代码。

迁移合并门禁时，应核对 branch protection、rulesets 和聚合作业，确认不再要求 PR 的 mutation 检查。 若它仍是必需检查，维护者须先迁移该门禁；手动运行不能替代 PR 必需检查，也不能用跳过作业冒充变异测试成功。

耗时与重建#

首次全量或基线重建可能超过 90 分钟，工作流总时限为 180 分钟。该时限与 Stryker 对单个变异执行设置的超时不同。

本地和 CI 都先校验语义输入与基线元数据。源码、测试、依赖、锁文件、配置、fixture、快照、 辅助文件或运行时变化时，保守全量运行当前配置范围。不能仅凭 Stryker 的原生差异检测， 认定任意源码修改后旧结果都可安全复用；跨函数依赖可能导致遗漏。

缓存采用 v3 命名空间，旧缓存不迁入。报告必须和兼容性元数据一起保存和恢复； 缺少元数据、报告被修改或上次运行未成功时，下一次运行重建基线。 pnpm mutation:full 显式强制重建；只有成功运行才写入有效元数据。

输入默认保守纳入；仅经审核的精确文档路径可排除。维护缓存策略时，不要将全部 Markdown、 源码、测试或整个 package.json 排除：Markdown 也可能是测试 fixture，依赖声明必须入键。 策略见 .github/mutation-cache-inputs.json，可用 node .github/scripts/baseline-inputs.mjs .github/mutation-cache-inputs.json --list 检查输入清单。 常规入口仅接受 --force；局部实验需通过 run-mutation.mjs 使用独立配置与报告。 根包 package.json 的 version 经审核不被当前源码与测试消费，因此仅规范化这一字段， 其余 manifest 字段、依赖声明和锁文件仍进入摘要。 外部服务和无法自动确定的环境状态发生变化时，仍应显式全量重跑。

评分与门禁#

当前保留 Stryker 默认评分阈值，未额外设置最低分门禁。原始测试失败或工作流执行错误会使 CI 失败；有存活变异时，应结合报告判断哪些行为缺少有效断言。