qa-test-code-coverage

テストからコードカバレッジへ

プロジェクトのテスト（Markdown 形式の手動テストケースと、自動化された E2E テスト）およびソースコードを分析します。ソースファイル（または glob）からテスト識別子（スイート ID、テスト ID、タグ）への対応表 coverage.tests.yml を作成します。Testomat.io では手動テストと自動テストを 1 つのプロジェクトで管理するため、両方に同じカバレッジファイルを使用します。@testomatio/reporter はこのファイルを読み込み、差分の影響を受けるテストのみを実行します（Step 6）。

重要な制約

• 存在するテスト（Markdown 形式の手動テストケース、自動化された E2E テスト、またはその両方）をマッピングします。 ユニットテストは対象外です。新しいテストの作成を提案しないでください。
• 書き込みが許可されるのは、次の 3 か所のみです。それ以外には何も書き込まないでください。
  • カバレッジファイル。デフォルトは coverage.tests.yml、またはユーザーが指定したパスです。
  • .testeiya/ キャッシュディレクトリ。自動テストリポジトリのクローン、および Testomat.io からの手動テストケースの取得に使用します（Step 1）。
  • .gitignore。.testeiya/ の行がない場合に追加します。
• ソースファイルやテストファイルは絶対に変更しないでください。
• 追跡対象のフォルダーにテストを取得またはクローンしないでください。gitignore 対象の .testeiya/ にのみ取得してください。
• カバレッジファイルのすべての内容は、このプロジェクトに由来する必要があります。 ファイルキーはソースツリーから、識別子は Step 2 の一覧から取得してください。このスキルのドキュメントにあるパスや ID はコピーしないでください。これらはプレースホルダーです。
• 場当たり的なスクリプトやパーサーは使用せず、Python は絶対に使用しないでください。 ファイルの読み取りと grep のみ使用できます。唯一の例外は Step 5 の同梱チェッカーです。それ以外では、1 行の node -e '…' までにしてください。
• 積極的に作業し、代表的なサンプルだけで止めないでください。 ドメインごとのエントリーが数件だけでは、作業未完了です。Step 4 の完了条件を満たすまで、続行の許可を求めずマッピングを続けてください。
• 出力ファイルに書き込めない場合、またはテストが見つからず、ユーザーが Step 1 のすべての選択肢を拒否した場合は中止してください。

ワークフロー

Step 1：プロジェクトを調査する

• scan-automation-project スキルを実行して、プロジェクトの一覧を作成します。その出力を信頼できる情報源として使用し、スキャンを重複して実行しないでください。
• 結果から次の情報を取得します。
  • 手動テスト — .test.md ファイルと、スイート／テストのタイトル。
  • 自動テスト — E2E テストファイルとフレームワーク。スキャン結果が不明瞭な場合は、E2E Frameworks を参照してください。
  • プロジェクト概要 — 言語、フレームワーク、複雑さ（Step 4 でのサブエージェント分担に使用）。
• 存在するものをすべてマッピングします。両方ある場合は 1 つのカバレッジファイルにまとめます。どちらか一方だけでもかまいません。
• ❓ スキャンでテストが 1 件も見つからなかった場合（.testeiya/ キャッシュも確認します）、ユーザーに次の選択肢を尋ねます。
  1. Testomat.io から手動テストケースを取得する — sync-test-cases-with-tms を使ってキャッシュに取得します：npx check-tests pull -d .testeiya/test-cases。.gitignore に .testeiya/ がない場合は追加し、再度スキャンします。
  2. 自動テストのリポジトリをクローンする：git clone <url> .testeiya/e2e-tests。.gitignore に .testeiya/ がない場合は追加し、再度スキャンします。
  3. スキャン対象から漏れているディレクトリを指定してもらい、そのディレクトリを再度スキャンします。
  4. 中止します。
• ❓ 自動テストのフレームワークが 2 つ検出された場合（Jest と Playwright など）、どちらが E2E フレームワークかをユーザーに尋ねます。カバレッジのフィルタリングはランナーごとに実行されます。

ステップ 2：テスト情報を抽出する

次の 2 種類から識別子を 1 つの一覧にまとめます。

• スイート ID — @S + 8 文字。
• テスト ID — @T + 8 文字。
• タグ — その他の @word マーカー。
• コンテキスト — タイトル、ステップ、ページオブジェクト、アクセスしたルート。これはステップ 4 のマッピングに使用します。

ID の記載場所：

• 手動テストケースは Classical Tests Markdown Format に従います。ID は / ブロック内、タグはタイトルと tags: 行に記載されています。
• 自動テストでは、describe / it / test / Feature / Scenario のタイトルに ID が含まれます。E2E Frameworks を参照してください。

ファイルを読むか、テストを格納するディレクトリで grep を実行します。

grep -rnE 'id:[[:space:]]*@[ST]' <dir>          # manual suite/test IDs
grep -rnoE '@[ST][0-9a-f]{8}' <dir>             # IDs in automated test titles
grep -rhoE '@[A-Za-z0-9_-]+' <dir> | sort -u    # every @token, tags included

ID がない場合、テストは Testomat.io と同期されていないため、レポーターはそれらを選択できません。

• ❓ ID のない手動テストファイルがある場合：先に sync-test-cases-with-tms でプッシュするか、該当ファイルをスキップするかを確認します。
• ほとんどのファイルに ID のない自動テストがある場合：作業を中断し、まずユーザーに npx check-tests@latest <Framework> "<glob>" --update-ids を実行するよう案内します（フレームワークごとのコマンドは E2E Frameworks を参照してください）。

ステップ 3：ドメインごとにカバレッジマップを計画する

コードベースをファイルごとに調べないでください。 まずアプリケーションのドメイン領域を特定し、ステップ 4 で領域ごとにマッピングします。

• 両方の情報源から領域を導き出します。
  • ステップ 2 のスイートツリー — スイートの階層は、QA チーム独自の製品マップです。
  • ソースの構造 — モジュール、ルート、サービス、エントリーポイント。
• 各領域を、それをテストするスイートおよび実装するソースフォルダーと対応づけます。
• 重要度の高い順に領域を並べます。最も重要なのは決済／請求、認証とアクセス制御、データの整合性、コアビジネスフローです。次にサポート機能、最後に周辺的な UI を並べます。スイートの規模も重要度の指標です。QA が重点的にテストしているものは、重要と見なされています。
• マッピングを始める前に、優先順位を付けた計画をユーザーに提示します。
• ビジネスコードのみを対象とします。テストコード、手動テスト用ディレクトリ、依存関係／ビルド／ベンダーフォルダー、フレームワーク設定、ロックファイルは除外します。
• テンプレートとビューはマッピング対象のソースです（.vue、.erb、.blade.php など）。テストではレンダリングされた UI を確認するため、コードと同様にマッピングします。
• ❓ 領域やその優先順位が不明確な場合は、ユーザーに確認します。

ステップ 4：ソースファイルをテストに対応付ける

ステップ 2 のインベントリが作業リストです。インベントリ内のすべてのスイートがカバレッジファイルに含まれるか、理由を添えて未対応として記録された場合にのみ、対応付けは完了です。 ステップ 3 の順序で作業してください。最も重要なものから着手し、中断されても重要な領域を確実にカバーできるようにします。必ず両方のパスを実行してください。

• コード → テスト：各領域について、ソースファイルとサブツリーを、それらを確認するテストの識別子に対応付けます。
• テスト → コード：インベントリを確認し、マップにまだ含まれていない各スイートについて、対象となるソースを見つけて追加するか、対応付けできない理由（この機能のコードがここにない、外部システム、ユーザー入力が必要）を記録します。

プロジェクトの規模（ステップ 1 で確認したコードベースのサイズとスイート数）に応じて、パスの実施方法を調整します。

• 小規模なコードベースでスイート数も少ない場合は、このセッション内で両方のパスを実行します。
• 大規模なコードベース、または数十個のスイートがある場合は、サブエージェントを並行して起動します。コード → テストのパスでは領域ごとに 1 つ、続いてテスト → コードのパスでは未対応のまま残ったスイートのバッチごとに 1 つ起動します。各サブエージェントには次の情報を渡します。
  • 担当範囲：1 つの領域（その領域のスイートとソースフォルダー）、またはスイートのバッチ。
  • ステップ 2 のテストインベントリ全体。サブエージェントに再抽出させないでください。
  • 以下の対応付けルールと カバレッジファイル形式。
  • 担当範囲のみの YAML 断片を返すよう指示します。
• 断片を 1 つのマップに統合し、重複キーと空のエントリを削除します。ファイルを書き込むのはメインセッションのみです（ステップ 5）。

候補となる各ソースファイルについて、テストスイートの拡大後も適切なテストを選択し続けられる識別子を選びます。

• スイート（@S）— デフォルトです。スイート内の大半のテストがそのファイルに関連します。
• タグ（@word）— 該当するテストが複数のスイートにまたがっています。
• テスト（@T）— 例外です。スイート内の 1、2 個のテストだけがそのファイルに一致する場合に限り使用します。

ルール：

• 同じスイートまたはカテゴリから複数のテスト ID を指定する場合は、スイートまたはタグに置き換えます。 後から追加されるテストも自動的に対象になります。テスト ID のリストは古くなります。
• 同じエントリにそのスイートがすでに含まれている場合、そのスイートのテスト ID は列挙しないでください。
• キーにはリポジトリルートからの相対パスでソースファイルのパスまたは glob を指定します。サブツリー全体が同じ識別子に対応する場合は glob を使用します。
• 手動の識別子と自動の識別子は、1 つのエントリに自由に混在させられます。
• 空のエントリを作成しないでください。
• 各識別子には、そのスイート／テスト／タグのタイトルを示す # コメントを付けます。

YAML の構文：カバレッジファイル形式。

ステップ 5：カバレッジファイルを保存して検証する

• # コメントを残したまま、YAML を出力パスに書き込みます。
• キーにはこのリポジトリ内のソースファイルのパスを指定します。.testeiya/... のパスは使用しないでください。
• 同梱のチェッカーで確認します。このチェッカーはプロジェクト内ではなく、このスキルの scripts/ ディレクトリ（この SKILL.md と同じ場所）にあります。スキルの場所からパスを解決してください。

npx js-yaml coverage.tests.yml | node <path-to-this-skill>/scripts/check-coverage.mjs

• チェッカーはディスク上に存在しないキーと空のエントリを検出し、参照されているすべての識別子を表示します。それらをステップ 2 のインベントリと照合してください。どれが実在するか判断できるのはあなただけです。
• 逆方向も確認します。インベントリ内のすべてのスイートがファイルに含まれているか、未対応リストに記録されている必要があります。どちらにもないものがあれば、テスト → コードのパスは完了していません。ステップ 4 に戻ってください。

ステップ 6：カバレッジの完全性を報告する

ユーザーに次の内容を提示します。

• 対応付け済みのスイート数とインベントリ内の総スイート数。意味がある場合は、テスト数とタグ数についても同様に示します。
• 未対応の各スイートとその理由。
• 作成した YAML（大きい場合は、そのパスとエントリ数）。

Step 7: 次の手順を提示する

@testomatio/reporter でファイルを使用する方法をユーザーに伝えます。

# Automated tests — the project's runner command must be passed in
npx @testomatio/reporter run "npx playwright test" \
  --filter "coverage:file=coverage.tests.yml,diff=main"

# Manual tests — creates a pending run with only the affected cases
npx @testomatio/reporter run --kind manual \
  --filter "coverage:file=coverage.tests.yml,diff=main"

• フレームワークごとのランナーコマンドと GitHub Actions の例：Coverage File Format。
• 1 つの回帰サイクルにおける手動実行と自動実行をまとめるには、両方のコマンドで同じ TESTOMATIO_RUNGROUP 環境変数を設定します。
• CI とチームメンバーが同じマッピングを使用できるよう、カバレッジファイルをコミットすることを推奨します。
• CI ではベースブランチとの差分を取ります — diff=origin/main — また、fetch-depth: 0 でチェックアウトします。
• プルまたはクローンしたテストは、再実行用に Git で無視される .testeiya/ キャッシュに保持されます。削除したり、追跡対象のフォルダーに移動したりしないでください。

Step 8: 次のアクションを提案する

• マップを CI に組み込みます — PR ごとに実行を作成し、プレビューまたはマージ時に起動します。setup-change-aware-pr-testing に委任します。
• 影響を受けるテストを今すぐターミナルから実行します。run-tests-with-testomatio-reporter に委任します。
• カバレッジの不足 — ソース内の機能に対応するテストがありません。承認を得たうえで、新しいケースを提案します（qa-write-test-cases に委任します）。
• デッドテスト — ソースに存在しなくなった機能のテストです。
• インベントリーを参照して、「X のテストはありますか？」などの質問に答えます。
• プルした手動テストケースを編集する場合は、.testeiya/test-cases/ で編集し、sync-test-cases-with-tms でプッシュして戻します。

参考資料

• Coverage File Format — カバレッジ YAML の文法、レポーターの契約、GitHub Actions の例。
• E2E Frameworks — フレームワークの検出シグナル、ID の格納場所、フレームワークごとの check-tests コマンド。
• Manual test markdown format — qa-write-test-cases が管理する正式な形式。