# Elixirのコードカバレッジ {#elixir-code-coverage}

コードカバレッジは、テストが実行したコードの行を示します。Hexパッケージは`mix test --cover`の実行ごとにラインカバレッジをアップロードし、Tuistはコミット内のすべての実行を集約して、プロジェクト全体、各OTPアプリケーション、および各ファイルに対して単一の数値としてまとめます。ダッシュボードの**Code Coverage**ページでは、コミットごとの結果とブランチごとの推移を表示します。

> [!IMPORTANT]
> **要件**
>
> - <.localized_link href="/guides/get-started/elixir-project">共有Elixirセットアップ</.localized_link>を完了してください。これにより、`mix test`がパッケージ経由でルーティングされます。

## セットアップ {#setup}

### カバレッジ付きでテストを実行する {#run-your-tests}

Tuistを使用しない場合の`mix test`と同様に、`--cover`を指定します：

```sh
mix test --cover
```

パッケージは、実行のテスト結果とともにカバレッジをアップロードします。スイートが完了すると、同じ`test_coverage`オプションで構成されたMixのカバレッジツールと同様の処理を行います：

- **サマリー。** 各モジュールと全体の合計のカバレッジを表示します。`summary: false`で無効にできます。
- **しきい値。** 合計がしきい値を下回ると、終了ステータス3で実行が失敗します。しきい値を設定しない場合のデフォルトは90%です：

```elixir
def project do
  [
    test_coverage: [summary: [threshold: 80]]
  ]
end
```

Mixと同様、しきい値はサマリーに属するため、`summary: false`で両方が無効になります。実行を失敗させずにサマリーを表示するには、`threshold: 0`を設定します。`test_coverage: [ignore_modules: [...]]`にリストされたモジュールは、サマリーとアップロードから除外されます。

Tuistはコミットごとにカバレッジを追跡するため、プロジェクトがGitリポジトリにある必要があります。リポジトリ外での実行はテスト結果をアップロードしますが、カバレッジはアップロードしません。

カバレッジは、パッケージがアップロードする<.localized_link href="/guides/features/test-insights/elixir#git-history">Git履歴</.localized_link>に依存しており、これによりコミットがそのブランチ上に配置されます。継続的インテグレーション上の実行は常にこれをアップロードし、`--cover`の実行はどのマシンでもこれをアップロードします。`--cover`を使用すると、パッケージはプルリクエストの分岐元も特定します。ベースブランチを取得し、必要に応じてシャロークローンを深化させます。リモートへの接触を防ぐには、`TUIST_GIT_UNSHALLOW_ENABLED=false`を設定します。

### シャーディングされた実行 {#sharded-runs}

<.localized_link href="/guides/features/test-sharding/elixir">テストをシャーディング</.localized_link>する場合、各シャードを`--cover`付きで実行します：

```sh
MIX_ENV=test TUIST_SHARD_INDEX=0 mix tuist.test --cover
```

新しいランナーでは、シャーディングガイドの<.localized_link href="/guides/features/test-sharding/elixir#test-phase">テストフェーズ</.localized_link>にあるbootstrapコマンドを使用します。これにより、シャードがビルドをダウンロードする前にMixがすべての依存関係をコンパイルするのを防ぎ、それに`--cover`を追加します。

シャードは自身のカバレッジのみを報告し、スイートの一部のみを実行するため、しきい値チェックは行いません。Tuistは実行内のシャードを1つの数値に統合します。

各シャードは、ダウンロードしたビルドにカバレッジカウンタを追加します。代わりに一度だけ行うには、ビルドフェーズにも`--cover`を渡します：

```sh
MIX_ENV=test mix tuist.test.build --shard-max 5 --cover
```

パイプライン実行間でビルドディレクトリを保持し、カバレッジを収集しない実行で再利用する場合は、これをオフにしておきます。こうすることで、そのビルドにはカウンタが含まれなくなります。

### CIで各コミットを完了させる {#complete-each-commit}

コミットのカバレッジは、シャードごと、データベースバージョンごと、またはアプリケーションごとなど、複数のジョブから得られることがよくあります。Tuistは最後に報告されたジョブを自動検出できないため、明示的に通知する必要があります。コミットのすべてのテストジョブが完了したら、それらすべてに依存するジョブで次を実行します：

```sh
MIX_ENV=test mix tuist.coverage.complete
```

タスクは`GIT_COMMIT`またはチェックアウトの`HEAD`からコミットを読み取ります。別のコミットを指定するには、`--commit <sha>`を渡します。コミットが完了するまで、そのカバレッジは**In progress**として表示され、ブランチの推移には含まれません。

## 仕組み {#how-it-works}

### ネイティブなラインカウンタ {#native-line-counters}

Mixのカバレッジツールは、各実行の開始時にErlangの`cover`のためにすべてのモジュールを再コンパイルするため、大規模なプロジェクトでは遅くなります。このパッケージは代わりにランタイムのネイティブなラインカウンタを使用して計測します。前回の実行以降にコンパイルによって書き込まれたモジュールのみを再コンパイルし、ランタイムをそれらのカウンタに切り替えて、スイート終了時に読み取ります。Mixのカバレッジツールは使用されませんが、そのサマリーとしきい値の機能は維持されます。

パッケージは、以下の場合にMixのカバレッジツールにフォールバックし、同じアップロード処理を行います：

- アンブレラプロジェクトのルート。ネイティブな計測を行うには、各アプリケーション内でテストを実行します。
- 独自の`test_coverage: [tool: ...]`を設定しているプロジェクト。
- JITのないランタイム。ネイティブな計測ができないためです。

### Tuistが計測するもの {#what-tuist-measures}

- **アプリケーション。** 各OTPアプリケーションはダッシュボード上のターゲットとなり、それぞれ独自のカバレッジを持ちます。
- **プロダクトコードのみ。** テストパス下のファイルはテストコードです。Tuistはこれらを保存しますが、すべての数値からは除外します。
- **ファイルごとの行数。** 行は、それが属するモジュールの数に関係なく、ファイルごとに1回だけ計上されます。
- **関数。** 各行は、その直上で最も近く開始される節を持つ関数に属します。コンパイラやマクロが生成する関数（`__info__/1`や`__schema__/1`など）はリストされませんが、それらの行はファイルの計測対象に含まれます。

したがって、Tuistの数値はMix自体のカバレッジレポートとは幾つかの点で異なります。テストコードを除外し、モジュール単位ではなくファイル単位で行を計上します。また、ネイティブな計測ではアプリケーション起動時に実行されるコードも検出し、コンパイラが決して実行されないことを証明した行を除外します（Mixのツールではこれらの行は「未カバー」として報告されます）。

### スキップされたテスト {#skipped-tests}

Tuistは、実行から除外されたテストのカバレッジを引き継ぐことはできません。パッケージは各テストの実行内容ではなく、実行全体の実行内容を記録するためです。そのため、実行の引数（`--only`、`--exclude`、`--failed`、`--stale`、`--name-pattern`、`--max-failures`、またはテストファイルや行の指定）によってテストが除外されると、何も除外していない同じバリアントの実行も行われない限り、コミットのカバレッジは**Incomplete**となります。`--exclude slow`と`--only slow`のように、それぞれがテストを除外する2つの実行は、合わせてすべてのテストを実行した場合でも、コミットを不完全な状態にします。

意図的に除外され、コミットを不完全にしないテストもあります：

- **テストヘルパーの除外設定。**`ExUnit.start(exclude: [...])`によってデフォルトで除外されるテストは、プロジェクトのスイートがデフォルトで実行するものとしての選択であり、Tuistはこれらを欠落としてカウントしません。それらのカバレッジをコミットに追加するには、`--include`または`--only`を使用して別のジョブで実行します。
- **コード内でスキップされたテスト**。`@tag :skip`を使用します。
- **<.localized_link href="/guides/features/test-insights/flaky-tests/elixir#quarantining">quarantine</.localized_link>がスキップするテスト。** これらは削除されたものとして除外されるため、これらのテストのみがカバーしていた行は未カバーとしてカウントされます。

### 完全および不完全なコミット {#commit-status}

ダッシュボード上の各コミットにはステータスがあります：

| ステータス | 意味 |
| --- | --- |
| 進行中 | 実行がカバレッジを報告していますが、`mix tuist.coverage.complete` がそのコミットに対してまだ実行されていません。 |
| 完了 | コミットの実行に含まれるすべてのテストが実行されたか、意図的に除外されました。 |
| 不完全 | 一部のカバレッジを特定できなかったため、数値は下限値となります。 |
| 未測定 | コミットに対してカバレッジを報告した実行がありません。 |

ブランチのトレンドには完了したコミットのみが含まれます。例えば、以下の場合にコミットは不完全となります：

- バリアントのすべての実行が、独自の引数によってテストを除外しました。
- バリアントのすべての実行で、一部のシャードが欠落していました。
- バリアントのカバレッジが、未コミットの変更を含むチェックアウトでのCI実行からのみ得られました。

バリアントとは、`--scheme` で渡すラベル（データベースのバージョンなど）のことです。ラベルのない実行は1つのバリアントとして扱われます。コミットの図はすべての実行を統合しますが、Tuistは各バリアントの完全性を個別に確認するため、各バリアントには何も除外しない実行が必要です。

## パフォーマンスへの影響 {#performance-impact}

カバレッジの収集にはオーバーヘッドがかかるため、`--cover` を使用した実行は使用しない場合よりも時間がかかります。最初の実行ではモジュールが行カウンタ付きで再コンパイルされますが、以降の実行では変更された部分のみが再コンパイルされるため、コストは大幅に低減します。大規模なプロジェクトでは、ネイティブな計測はMixのカバレッジツールよりもはるかに高速です。

## 制限事項 {#limitations}

- **HTMLレポートなし。** ネイティブな計測では `test_coverage: [output: ...]` ディレクトリにレポートを書き込まないため、設定されている場合は実行時に警告が表示されます。代わりに、ダッシュボードのファイルページでカバーされた行を確認できます。
- **リトライではカバレッジは追加されません。**<.localized_link href="/guides/features/test-insights/flaky-tests/elixir#test-retries">テストのリトライ</.localized_link>を使用する場合、カバレッジは最初の実行時のものです。その実行ですでに失敗したテストが実行されているため、欠落する行は不安定なテストがリトライ時に到達するが最初の実行時には到達しなかった行のみです。
- **フォークからのプルリクエストからはカバレッジを取得できません。** カバレッジはTuistで認証された実行によってのみアップロードされます。CIは通常、フォークから開かれたプルリクエストに対してシークレットやIDトークンを提供しないため、それらの実行からはカバレッジが報告されません。マージされると、コミットは資格情報を持ってあなたのブランチで実行され、通常通りカバレッジを報告します。

## カバレッジのクエリ {#querying}

ダッシュボードの **コードカバレッジ** ページには、各コミットの図、そのアプリケーション、ファイル、および各実行がカバーした行が表示されます。同じデータは、<.localized_link href="/guides/features/agentic-coding/mcp">Model Context Protocolサーバー</.localized_link>を通じてエージェントからも利用可能です。
