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. 無効化されたターゲットに共通する依存関係を探します。

2 つのテスト実行を比較する

各ターゲットについて、次の項目を確認します。

• 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 を使って、ターゲットごとの選択的テストの状況を詳しく調べました
• 有効性が低い場合は、根本原因を診断しました
• リグレッションが検出された場合は、ベースラインとターゲットを比較しました
• 実行可能な推奨事項を提示しました