analyze-selective-testing

分析选择性测试

快速开始

1. 运行 tuist test list --json 查找测试运行记录。
2. 运行 tuist test xcode target list <test-run-id> --json 查看各目标的选择性测试状态。
3. 如果效果有所下降，请比较已知正常运行记录与退化运行记录中的目标。

步骤 1：确定测试运行记录

查找要分析的测试运行记录

列出近期测试运行记录，可按分支筛选：

tuist test list --json --page-size 10
tuist test list --git-branch feature-x --json --page-size 5

获取指定测试运行记录的基本信息：

tuist test show <test-run-id> --json

用此信息确认运行记录的分支、状态、方案和环境（xcode_version、macos_version）。

默认设置

• 如果未指定测试运行记录，则使用当前分支上最近一次 CI 测试运行记录。
• 比较时，使用项目默认分支上最近一次 CI 测试运行记录。

步骤 2：深入查看选择性测试目标

列出某次测试运行记录中各目标的选择性测试数据：

tuist test xcode target list <test-run-id> --json

每个目标包含：

• name：测试目标名称
• hit_status：miss（已运行）、local（通过本地缓存跳过）或 remote（通过远程缓存跳过）
• hash：此目标的选择性测试哈希

按状态筛选，聚焦分析内容：

tuist test xcode target list <test-run-id> --hit-status miss --json
tuist test xcode target list <test-run-id> --hit-status local --json
tuist test xcode target list <test-run-id> --hit-status remote --json

评估效果

按状态统计目标数量：

effectiveness = (local_hits + remote_hits) / total_targets * 100

效果	评估
60-100%	良好——大多数未更改的测试都已跳过
30-60%	一般——发生了一些缓存失效，值得调查
0-30%	较低——可能是核心依赖项发生更改，或缓存已失效
0%	冷缓存——首次运行、环境变更或缓存完全失效

步骤 3：诊断退化

如果效果有所下降，请调查以下情况：

检查全局失效

如果几乎所有目标都显示为 miss，则整个选择性测试缓存已失效。常见原因：

原因	验证方法
Xcode 版本变更	通过 tuist test show 比较正常和异常运行记录的 xcode_version
CI 环境变更	比较各运行记录的 macos_version、model_identifier
项目图或依赖项变更	检查 Git 历史，查看项目清单、依赖项版本或目标配置是否有变更
核心依赖项变更	广泛依赖的目标发生更改，导致其所有依赖方失效

注意：Tuist CLI 版本升级很少导致哈希失效——哈希版本不会在每次发布时更新。

检查级联失效

如果只有部分目标显示为 miss，则可能是依赖项变更引发了级联失效：

1. 运行 tuist test xcode target list <good-run-id> --json 和 tuist test xcode target list <bad-run-id> --json。
2. 按名称匹配目标，找出从 local/remote 变为 miss 的目标。
3. 比较已更改目标的哈希——如果某个目标的哈希不同，则其源代码或依赖项已发生更改。
4. 查找失效目标之间的共同依赖项。

比较两次测试运行记录

对于每个目标：

• 按 name 匹配
• 比较 hit_status（hit -> miss = 已失效，miss -> hit = 已改善）
• 比较 hash（哈希不同 = 目标或其依赖项已发生更改）

步骤 4：提出建议

根据诊断结果：

• 环境变更：确保 CI 使用一致的 Xcode/macOS 版本。这是缓存完全失效最常见的原因。
• 依赖项变更引发级联失效：考虑根目标的变更是否必要。如果根目标是被广泛共享的模块，可考虑拆分它。
• 新分支上的冷缓存：运行一次测试以预热缓存。后续运行将受益于选择性测试。

摘要格式

生成摘要，包含：

1. 总体情况：效果百分比、评估（良好/一般/较低/冷缓存）
2. 目标明细：按命中状态分组的目标
3. 比较（如适用）：运行记录之间状态发生变化的目标及其哈希差异
4. 根本原因：导致退化的原因
5. 建议：可执行的后续步骤

示例：

Selective Testing Analysis: test run abc123 on feature-x

Effectiveness: 15% (3/20 targets skipped) -- LOW
  Local hits:  2 targets (CoreTests, UtilTests)
  Remote hits: 1 target (NetworkTests)
  Misses:      17 targets

Comparison with baseline (run def456, 75% effectiveness):
  14 targets changed from hit to miss
  All changed targets have different hashes

Root cause: Xcode version changed from 15.2 to 16.0 between runs.
This changed all target hashes, invalidating the entire cache.

Recommendations:
- Align CI Xcode version with the version used in the baseline run.
- If the upgrade is intentional, run tests once to re-warm the cache.

完成检查清单

• 已确定要分析的测试运行
• 通过 tuist test xcode target list 深入检查各目标的选择性测试状态
• 如果效果不佳，已诊断根本原因
• 如果检测到回归，已将目标与基线进行比较
• 已提供可行的建议