dart-test-coverage

Dart のテストカバレッジ

Dart パッケージでテストカバレッジを実行・解釈するためのガイドラインです。

このスキルを使用する場面

• 「テストカバレッジを確認して」または「カバレッジを改善して」と依頼された場合。
• ライブラリのどの部分がテストされていないかを特定する必要がある場合。

使用しない場面（実施しないためのガードレール）

次の対象について、テストカバレッジを収集したり、要求したりしないでください。

• 生成コード：ビルダーによって生成されたコード（*.g.dart、*.freezed.dart、protobuf）。
• プラットフォーム固有の FFI／OS エントリーポイント：実行環境では利用できない、特定の物理ハードウェアや OS サービスが必要な低レベルのプラットフォームバインディングやエントリーポイント。
• サンプルアプリケーションとツールスクリプト：パッケージでリポジトリ全体のカバレッジ 100% が明示的に必須とされていない限り、example/ 内の単独のサンプルコードや、tool/ 内の開発者向け保守スクリプト。
• 失敗しているテストスイート：既存のテストが dart test で失敗する場合は、カバレッジを収集または報告する前に、まず失敗しているテストを修正してください。

調査

テストカバレッジが不足している箇所を見つけるには、次の手順に従います。

カバレッジ分析を実行する

カバレッジデータを生成して解釈するには、次のワークフローに従います。

1. カバレッジ付きでテストを実行する：dart test --coverage=.dart_tool/coverage
2. 結果を解釈する：「結果の解釈」セクションの説明に従って、スクリプトまたは format_coverage を使用し、対象ファイルとカバレッジされていない行を特定します。

このスキルの使用方法（ワークフロー）

1. dart test を実行して、テストが成功することを確認します。
2. dart test --coverage=.dart_tool/coverage を実行して、カバレッジを収集します。
3. 提供されているスクリプトまたは標準ツールを使って、結果を解釈します。
4. カバレッジされていない行をカバーするテストを追加します。

カバレッジの実行

次のコマンドを実行して、カバレッジを JSON 形式で収集します。

dart test --coverage=.dart_tool/coverage

メモ

出力先ディレクトリに .dart_tool/coverage を使用します。.dart_tool は通常、すでに .gitignore ファイルで無視されているためです。

ヒント

条件分岐が複雑なプロジェクトでは、dart test に --branch-coverage フラグを渡して、分岐レベルのカバレッジを収集できます。

結果の解釈

オプション 1：カスタムの解釈スクリプトを使用する

このリポジトリには、依存関係なしで生の JSON 出力を解析し、カバレッジ率とカバレッジされていない行の概要を表示するスクリプトが含まれています。

プロジェクトのルートから実行します（必要に応じてスクリプトのパスを調整してください）。

dart run skills/dart-test-coverage/scripts/interpret_coverage.dart .dart_tool/coverage <package_name>

<package_name> を pubspec.yaml に記載されている名前に置き換えてください。

出力例：

package:my_pkg/src/file.dart: 50.0% (2/4 lines)
  Missed lines: 3, 4

オプション 2：package:coverage を使用する

package:test がインストールされている場合、package:coverage も推移的依存関係として利用できる可能性があります。format_coverage ツールを使用できます。

カバレッジを人が読みやすい形式で表示するには、次のコマンドを実行します。

dart run coverage:format_coverage --in=.dart_tool/coverage --out=stdout --pretty-print --report-on=lib

ファイルの内容が、左側にヒット数（カバレッジされていない行の場合は 0| など）とともに出力されます。

結果を報告する際のベストプラクティス

カバレッジの結果をユーザーに提示する際は、次のガイドラインに従ってください。

1. まず全体のカバレッジ率を示すことで、すぐに状況を把握できるようにします。
2. 対象ファイルとカバレッジされていない行を明確に示します。
3. 行番号をコードの内容に置き換えて説明します：「3～6 行目が未カバー」とだけ伝えるのではなく、ソースファイルを確認し、どの関数やブロックがテストされていないかをユーザーに伝えます（例：「divide 関数のカバレッジが不足しています」）。
4. 具体的な修正方法を提案します：カバレッジされていない行をカバーするため、ユーザーがすぐに適用できるテストコードの例を提示します。
5. 複数ファイルの概要には表を使用します：複数のファイルについて報告する際は、File、Coverage %、Missed Lines の列を含む Markdown の表を使い、概要を見やすくします。

制約

• カバレッジを収集する前に、テストが成功することを必ず確認してください。
• .dart_tool/coverage ディレクトリをコミットしないでください。
• カバレッジ改善の対象は test/ や生成ファイルではなく、lib/ ファイルにしてください。