# 生成されたXcodeプロジェクト {#generated-xcode-project-flaky-tests}

> [!IMPORTANT]
> **必要条件**
>
> - <.localized_link href="/guides/features/test-insights/xcode">Xcodeテストインサイト</.localized_link>が設定されていること（自動生成されたスキームには`tuist inspect test`ポストアクションが含まれています。カスタムスキームではこれを追加する必要があります）。

不安定なテストとは、同じコードで複数回実行した際に異なる結果（合格または不合格）を生み出すテストのことです。これらはテストスイートへの信頼を損ない、誤った失敗の調査に開発者の時間を浪費させます。Tuist は不安定なテストを自動的に検出し、経時的な追跡をサポートします。


![不安定なテストページ](/images/guides/features/test-insights/flaky-tests-page.png)

## 不安定なテストの検出方法 {#how-it-works}

Tuistは以下の2つの方法で不安定なテストを検出します：

### テスト再試行 {#test-retries}

再試行機能を使用してテストを実行すると、Tuistは各試行の結果を分析します。一部の試行で失敗し、他の試行で成功するテストは、不安定としてマークされます。

`-retry-tests-on-failure`または`-test-iterations`を`tuist test`経由で渡します：

```sh
tuist test MyScheme -- -retry-tests-on-failure -test-iterations 3
```

![不安定なテストケースの詳細](/images/guides/features/test-insights/flaky-test-case-detail.png)

### クロスラン検出 {#cross-run-detection}

テストのリトライがなくても、Tuist は同じコミット、スキーム、報告された宛先（デバイス名、プラットフォーム、OS バージョン）における異なる CI 実行の結果を比較することで、不安定なテストを検出できます。一致する CI 実行の 1 つでテストが成功し、別の実行で失敗した場合、その失敗した実行は不安定としてマークされます。この処理は、どちらの結果が先に到着しても機能します。

同じテストでも、スキームや宛先によって一貫して異なる動作をする場合があります。たとえば、iOS 26 で合格し iOS 27 で不合格になっても、それは不安定性を示すものではありません。異なるスキーム、デバイス、プラットフォーム、または OS バージョンからの結果同士は、互いを不安定としてフラグ付けしません。

宛先メタデータがない実行、または複数の宛先を対象とする実行は、互いとのみ比較されるため、それらの間での環境の違いは依然として不安定として報告される可能性があります。リトライベースの検出も引き続き適用されます。

これは、リトライで捕捉できるほど一貫して失敗しないものの、依然として断続的な CI の失敗を引き起こす不安定なテストを検出するために特に役立ちます。


## 不安定なテストの管理 {#managing-flaky-tests}

### 自動クリア {#automatic-clearing}

検出とクリアはプロジェクト上の **自動化アラート** を介して実行されます。すべてのプロジェクトにはデフォルトで「不安定なテスト検出」自動化が設定されており、その *トリガー* はテストを不安定としてマークし、*リカバリー* はテストが再トリガーされずに設定されたリカバリー期間（デフォルト **14 日**）を経過するとフラグを解除します。**設定 → 自動化** で編集して、リカバリー期間を変更したり、リカバリーアクション（例：テストの隔離も解除する）を変更したり、リカバリーを完全に無効にしてテストを手動でクリアするまで不安定なままにしておくことができます。

### 手動管理 {#manual-management}

テストケースの詳細ページから、テストを不安定として手動でマークまたはマーク解除することもできます。これは以下のような場合に役立ちます。
- 修正作業中に既知の不安定なテストを認識したい場合
- インフラストラクチャの問題によりテストが誤ってフラグ付けされた場合


## 不安定なテストの隔離 {#quarantining}

不安定なテストを隔離することで、修正中にCIがブロックされるのを防ぎます。デフォルトでは**手動操作**です。ダッシュボードのテストケース詳細ページから、テストを隔離したり、隔離を解除したり、モードを切り替えます。**Settings → Automations**で**自動化アラート**を設定し、不安定さが閾値を超えたときにテストを自動的にミュート（またはスキップ）し、回復したら隔離を解除することもできます。手動および自動のすべての遷移は、テストケースの監査ログに記録されます。

デフォルトでは、トリガー条件が満たされなくなるまで回復を待つため、古い不安定な実行がトリガーウィンドウから外れるまでテストは隔離されたままになります。より早く回復させるには、**Recover when**を**No new flaky runs**に設定します。これにより、回復ウィンドウ（日数または実行回数）の間に新しい不安定な実行が発生しなければテストは回復し、新しい不安定な実行が発生するたびに待機時間がリセットされます。回復後は、新しい不安定な実行が発生した場合のみ再度隔離されます。


隔離されたテストは、以下の2つのモードのいずれかになります：

- **ミュート**：テストは引き続き実行されますが、`tuist test`によって失敗がマスクされます。失敗情報は依然として不安定なテスト検出器に送られるため、ビルドを中断することなくテストを監視し続けることができます。積極的に調査中のテストにこのモードを選択してください。
- **スキップ**：xcodebuildは`-skip-testing <identifier>`を受け取るため、テストは開始されません。新しい結果は生成されず、再度有効にするまで不安定なテストダッシュボードから除外されます。テストが壊れている、遅い、またはあまりにも持続的に不安定で実行することがCI時間の無駄である場合にこのモードを選択してください。

### 隔離されたテストが合格として表示される理由 {#quarantined-passing}

- **ミュートされたテスト**は引き続き実行されます。失敗したミュートテストは、テストケースの実行で**失敗**として記録され、不安定としてフラグが立てられます。テストごとのステータスは書き換えられません。上書きされるのは**テスト実行全体**です。実行内の失敗しているテストケースがすべてミュートされている場合、実行全体は合格として報告されるため、ミュートされた失敗によってCIが中断されることはありません。
- **スキップされたテスト**はまったく実行されないため、ダッシュボードにはそのテストの最後の実際の実行時のステータスが引き続き表示されます。そのスナップショットは数週間前のものかもしれません。


### テストの実行 {#running-tests}

`tuist test`は両方のモードを自動的に尊重します：

```sh
tuist test
```

スキップされたテストは`-skip-testing`としてxcodebuildに渡され、開始されることはありません。ミュートされたテストは通常通り実行されます。失敗した場合、その失敗は結果のビルドステータスでマスクされます。

隔離を完全にバイパスし、ミュートおよびスキップされたテストを含めてすべてを実行するには：

```sh
tuist test --skip-quarantine
```

## 新しいテストのストレステスト {#stress-testing-new-tests}

ストレステストゲートは、ブランチが追加したテストケースをそれぞれ新しいプロセスで複数回再実行し、不安定な結果となったものを報告します。新たに発生した不安定なテストは、それを導入したプルリクエスト上で確認でき、数週間後まで気づかないことはありません。


テストケースは、プロジェクトのデフォルトブランチ上で過去90日間にCIで実行されていない場合、またはそれ以降にマージされたコミット上で実行されていない場合に新規とみなされます。マージキューを使用する場合、キューが実行したテストケースは、キューのコミットがマージされた時点で認識され、キューがそれを削除した場合は新規のままとなります。コミットは、TuistがCI上で収集する<.localized_link href="/guides/features/test-insights/xcode#git-history">Git履歴</.localized_link>を通じて照合されます。

### 有効にする {#enabling-stress-testing}

ゲートはデフォルトでオフです。モードを設定してください：

- **`report`**：不安定なテストケースごとに警告を表示します。実行はその結果に基づいて終了します。
- **`enforce`**：不安定なテストケースが実行を失敗させ、失敗したテストと同じ終了コードを返します。

`report` を数週間使用して、`enforce` が何をブロックしていたかを確認してください。


どちらのモードでも、<.localized_link href="/guides/features/selective-testing/generated-xcode-project">選択的テスト</.localized_link>は、次の実行で不安定な新規テストケースを含むテストターゲットをスキップしません。ターゲットは再び実行され、ゲートはすべての再試行に合格するまでテストケースを再度ストレステストします。

パススルー引数の前にこれを渡すか、`TUIST_TEST_STRESS_NEW_TESTS`を設定してCIレーンごとにモードを変更します：

```sh
tuist test --stress-new-tests report
```

### 各テストの再実行回数 {#stress-reruns}

最初のパスでのテストケースの実行時間によって異なります。

| 最初のパス | 再実行回数 |
| --- | --- |
| 5秒以内 | 10 |
| 10秒以内 | 5 |
| 30秒以内 | 3 |
| 5分以内 | 2 |
| 5分超 | 再実行なし |

最初の到達した方の制限（200テストケースまたは10分）でパスが停止し、どの制限に達したかが表示されます。


再試行は、最初のパスでビルドされたものを再利用します。

### ゲートが実行されない場合 {#when-the-gate-does-not-run}

- 最初のパスですでに失敗しています。まずそれらのテストを修正してください。
- プロジェクトにデフォルトブランチがないか、CI でまだ何も実行されていません。
- プロジェクトのテストケースの 30% 以上が新しいように見えます。これほど多くを再実行すると、コストに見合わない時間がかかります。Tuist へのレポートを始めたばかりのプロジェクトや、一度に多くのテストを移動させるリネームを行った後では、この状況が想定されます。


## Slack通知 {#slack-notifications}

Slack連携で<.localized_link href="/guides/integrations/slack#flaky-test-alerts">不安定なテストのアラート</.localized_link>を設定し、テストが不安定になった際に通知を受け取りましょう。


## 不安定および隔離状態のクエリ {#querying}

### CLI {#querying-cli}

`tuist test case` コマンドツリーは、Tuist がテストケースについて追跡するすべての情報を公開します。

```sh
tuist test case list --flaky                       # only flaky test cases
tuist test case list --quarantined                 # only muted or skipped test cases
tuist test case show <test_case_id>                # detail: flakiness rate, last status, run counts
tuist test case events <test_case_id>              # audit log: marked_flaky, muted, skipped, ...
tuist test case run list <test_case_id>            # run history with status and duration
tuist test case run show <test_case_run_id>        # single run, including failure breakdown
```

これらはすべて、スクリプト用に `--json` を受け入れます。

### REST API {#querying-rest-api}

同じデータは HTTP 経由で利用できます。ルート、フィルター、レスポンスフィールドの完全なリストについては、API リファレンスの [テストケースエンドポイント](https://tuist.dev/api/docs#tag/test-cases) を参照してください。テストケースの状態（不安定のマークまたは解除、ミュート、スキップ）を変更するには、`is_flaky` または `state` を指定して `PATCH /api/projects/{account_handle}/{project_handle}/tests/test-cases/{test_case_id}` を送信してください。同じ変更は `tuist test case update` および `update_test_case` MCP ツールとしても利用できます。

