setup-change-aware-pr-testing

変更を考慮した PR テストの設定

プロジェクトの CI で、変更を考慮した PR テストを設定します。ここで扱うのは、フローのモデルとユーザーに確認する決定事項です。実際に組み込む内容は、プロジェクトのテストによって異なります。

• 手動 — テスターはデプロイされた変更に対して実施するテストを受け取ります。実行する処理はありません。
• 自動 — 実行方式を選ぶ必要があります。パイプライン内で実行する、Testomat.io の CI プロファイルを使う、または別のワークフロー／リポジトリにディスパッチする方式です。
• 混在 — 1 つの PR につき 1 つの実行を共有して、両方を行います。

仕組みを扱うスキルは 2 つあります。組み込みを行う前に、両方を読んでください。

• run-tests-with-testomatio-reporter — ジョブが実行するすべてのレポーターコマンドと環境変数。
• setup-ci-automation — CI の調査、ワークフロー作成のルール、図の規約、シークレット、PR の提出。

目標：プロジェクト独自の CI システムにコミットされた、動作するパイプライン。 CI 設定こそが、完成させる唯一の成果物です。私はローカルで設定を作成します。CI の一部になることはありません。設定の作成中にレポーターコマンドを実行しないでください。例外は、Testomat.io の CI プロファイル確認（Step 2）と最後の実動作テスト（Step 6）のみです。

最小限の設定は、デプロイを条件とする 1 つのジョブです。このジョブで実行を作成し、テストを開始します。まずこの方式を提案してください。ユーザーが希望する場合は、作成と開始を 2 つのジョブに分けることもできます。その場合、実行 ID をジョブ間で引き継ぎます。

考えられるフロー

環境で Mermaid が表示される場合は、最初の質問をする前に、この図をチャットメッセージとして投稿してください。質問から始めてはいけません。この図で、以降の内容の全体像を示します。質問をフォームまたはツールで行う場合は、それより前のメッセージですでに図が表示されている必要があります。

図だけを投稿してはいけません。直後に、図の説明を短い段落で必ず添えてください。これは PR テストの一般的な構成で、何も実装する前にユーザーに確認してもらうものです。変更のデプロイ後に実行が一度作成されます。これからユーザーに、どのデプロイをトリガーにするか（PR ごとのプレビューデプロイ、マージ後のデプロイ、または両方）、どの種類のテストを実行するか（手動、自動、または両方）、さらに自動テストをどの方式で実行するか（パイプライン内、Testomat.io の CI プロファイル経由、または別のリポジトリへのディスパッチ）を選んでもらいます。

flowchart LR
    DEP([Preview or post-merge<br/>deploy succeeds]) --> WHICH{PR behind<br/>this commit?}
    WHICH -->|none| SKIP([Nothing to test])
    WHICH -->|found| RUN[Create a run scoped<br/>to the deployed changes]
    RUN -->|manual / mixed| TESTERS[Testers execute manual cases<br/>on Testomat.io]
    RUN -->|automated / mixed| MODE{How to execute?}
    MODE -->|via a Testomat.io CI profile| RES
    MODE -->|inline in this pipeline| RES
    MODE -->|by dispatching another repo| RES
    RES[Run the affected automated tests —<br/>results land in the same run]

• 手動のみのプロジェクト → 上の分岐のみです。作成時に実行が完了し、テスターは Testomat.io でテストを実施します。起動する処理はありません。
• 自動のみのプロジェクト → 下の分岐のみです。1 つのジョブで実行を作成し、開始します。
• 混在するプロジェクト → 1 つの PR につき 1 つの実行を両方の分岐で共有します。

カバレッジマップがすべてを決定します

カバレッジマップでは、ソースファイルや glob をテスト識別子に対応付けます。レポーターは差分でマップをフィルタリングし、影響を受けるテストのみを準備して実行します。カバレッジマップは qa-test-code-coverage スキルで作成します。デフォルトは coverage.tests.yml で、手動テストと自動テストの両方に 1 つのファイルを使用します。マップがない場合は、qa-test-code-coverage に委任してください。ここで手書きしてはいけません。マップがなければ、テストをフィルタリングできず、パイプラインも設定できません。

重要な制約

• 作成中にレポーターを実行してはいけません。成果物はコミットする CI 設定です。 承認済みの例外は 2 つです。Testomat.io CI プロファイルの確認（ステップ 2）と実地テスト（ステップ 6）です。
• CI 設定ファイルのみを変更してください。ソースファイルやテストファイルには触れないでください。
• 図で対話の流れを決めます。最初の質問の前にフロー図を提示し、配線を行う前に選択したフローの図について承認を得てください（ステップ 3）。
• まず調査してください。何かを書く前に、scan-automation-project に委任してください。
• Testomat.io CI プロファイル名を推測してはいけません。ユーザーが確認したリスト（Testomat.io MCP）から選ぶか、ユーザーに尋ねてください。起動できることが実証されていないプロファイルは配線しないでください。
• 「Testomat.io CI profile」と省略せずに記載し、単に「profile」とは書かないでください。質問の各選択肢は、平易な言葉で内容を説明してください。
• プロジェクトのテスト一覧全体を実行対象として提示しないでください。テストの完全な一覧を表示してはいけません。
• カバレッジマップがない場合は、パイプラインを作成しないでください。qa-test-code-coverage にマップの作成を委任してください。
• デプロイジョブの成功を条件とするジョブを 1 つ提案してください。ユーザーが必要とする場合に限り、作成と起動を別々のジョブに分け、CI の値渡し機能を使って実行 ID を引き継いでください。
• プレビューデプロイもマージ後のデプロイも、どちらもトリガーとして有効です。同じジョブ構成を両方に適用し、プロジェクトにある各デプロイに接続してください。
• PR が紐付いていないデプロイ済みコミットからは、何も作成しません。
• --kind detect を指定すると、Testomat.io が実行対象に基づいて種別を解決します。mixed をハードコードしてはいけません。
• このジョブによってデプロイパイプラインが失敗することはありません。
• PR コメントはレポーター自身のパイプを通じて投稿されます。PR コメント用 API 呼び出しをスクリプトで実行してはいけません。
• 実行タイトルには、解決済みの PR からそのまま引き継いだ PR 自体のタイトルを使い、先頭に PR 番号を付けてください。独自の語句を付け加えてはいけません。「selective tests」「affected tests」や、フレームワーク名・対象範囲のラベルも追加しないでください。
• すべての実行に、そのタイトルと rungroup を設定してください。

ワークフロー

ステップ 1 — 調査

• scan-automation-project に委任し、手動の .test.md ケースがあるか、どの e2e フレームワークがあるか（unit／integration は対象外です）、自動テストがこのリポジトリ内と別の場所のどちらにあるかを確認してください。
• 調査結果により、プロジェクトの種別（manual、automated、mixed）と、適用するフローが決まります。
• setup-ci-automation を使って CI を調査してください。プロジェクトで実行される CI システム、存在するワークフロー、デプロイを行うワークフロー、およびデプロイ先の環境を確認してください。
• カバレッジマップ（デフォルトは coverage.tests.yml）の場所を確認してください。存在しない場合は、作成を提案し、qa-test-code-coverage に委任してください。

ステップ 2 — フローを提示し、不明点を確認する

ステップ 1 で見つかった種類に絞った、可能なフローの図を、1 段落の説明（スキーマとは何か、ユーザーがこれからどの選択をするのか）とともに、独立したメッセージとして投稿し、その後、該当する項目だけを確認します。すでに回答されている質問をしないよう、まず CI ファイルを確認してください。

手動テストが見つかった場合 — 選択する項目はありません。作成時に実行のうち手動テストの部分は完了しているため、テスターはすぐに Testomat.io を使い始めます。

自動テストが見つかった場合 — ❓ 実行モードを選んでもらいます。質問内の各選択肢では、何がどこで実行され、誰が起動するのかを、平易な言葉で説明してください。特に、Testomat.io CI プロファイルとは何かを明記してください。これは Testomat.io プロジェクトに保存された CI ワークフロー設定（Settings → CI）で、Testomat.io がこれをディスパッチしてテストを実行し、結果を実行に報告します。

モード	該当する場合
リモート — Testomat.io CI プロファイル	e2e スイート用の Testomat.io CI プロファイルが存在する（Settings → CI）。ランナー、環境、シークレットは Testomat.io が管理します
インライン — このパイプライン	モバイル／シミュレーター、このパイプラインが起動するサービス、またはこのリポジトリですでに動作する e2e ジョブ
リポジトリ間ディスパッチ	e2e スイートが別のリポジトリにあり、それを対象とする Testomat.io CI プロファイルがない場合

• リモートを選択した場合 → Testomat.io CI プロファイルを特定します。絶対に推測しないでください。Testomat.io MCP が接続されている場合 → プロファイル一覧を取得して提示し、❓ ユーザーに選んでもらいます（プロファイルごとにワークフロー名とジョブ名が異なります）。MCP がない場合 → ❓ 正確なプロファイル名を尋ねます。まだプロファイルがない場合 → Testomat.io（Settings → CI）での作成が前提条件です。
• そのプロファイルが起動することを証明してから、周辺の設定を行ってください。 ❓ 承認を求めます。これによりスイート全体が実行されます。npx @testomatio/reporter run --remote <profile-name> をフィルターなしで実行し、CI でジョブが実際に開始されたことを確認します。終了コード 0 が意味するのは、Testomat.io がディスパッチを受け付けたということだけです。対象のワークフロー、ジョブ、ブランチが間違っているプロファイルは、何も通知せずに失敗します。何も開始されなかった場合 → Settings → CI で修正し、再度実行します。
• e2e スイートがどこにもない場合 → 手動フローだけを設定し、e2e ジョブを捏造しないでください。

すべての種類について、次の項目も確認してください。

1. ❓ どのデプロイで実行をトリガーするか — PR ごとのプレビューデプロイ、マージ後のステージング／本番環境へのデプロイ、または両方。ステップ 1 で見つかったデプロイパイプラインを提示します。両方が存在する場合 → 両方を設定します。それぞれ独自の実行が作成され、そのデプロイで反映され、その環境に対してテストされた内容が対象になります。
2. ❓ 実行グループ化の方法 — 週／日／リリース／マイルストーン。

ステップ 3 — 選択したフローを確認する

• 回答から導き出されたフローを図にします。選ばれた種類、デプロイ、実行モードだけを含めてください。
• ❓ 図を提示して承認を得ます。ユーザーが承認するまでは何も設定しないでください。

例 — 混在するプロジェクト、プレビューとマージ後のデプロイ、Testomat.io CI プロファイル：

flowchart LR
    PREV([Preview deploy succeeds]) --> JOB
    STG([Post-merge deploy succeeds]) --> JOB
    JOB[Same job — get the PR, create a run<br/>scoped to what this deploy shipped]
    JOB --> TESTERS[Testers execute manual cases<br/>on Testomat.io]
    JOB --> L1[Launch automated tests via the Testomat.io<br/>CI profile, against this deploy's environment]
    L1 --> RES[Results land in that run]

ステップ 4 — CI にジョブを組み込む

デプロイパイプラインにジョブを 1 つ追加し、CI のネイティブなジョブ依存関係を使って、デプロイジョブの成功を条件に実行します。同じジョブを両方のデプロイで使用し、異なるのは次の 3 点だけです。

デプロイ	PR	差分範囲	テストの実行先
プレビューデプロイ（PR ごと）	デプロイをトリガーした PR	PR のターゲットブランチ	プレビュー URL
マージ後のデプロイ	デプロイされたコミットから特定	デプロイされたプッシュのコミット範囲	ステージング／本番環境

setup-ci-automation のワークフロー作成ルールに従って記述し、すべてのコマンドと環境変数は run-tests-with-testomatio-reporter から取得してください。--filter-list による事前チェックは行いません。手動テストのみのプロジェクトでは、（a）と（b）だけを実行します。

（a）PR を取得します。 プレビューデプロイには、すでに PR が含まれています。マージ後は、デプロイされたコミットを含む PR をプラットフォームに問い合わせて特定します。コミットの件名は解析しないでください。マージコミットの場合、ブランチ名が返されるためです。PR がない場合はログに記録して 0 で終了します。メインラインへの直接コミットは、これまでどおりデプロイし、何も作成しません。

（b）テストランを作成します。

• start --kind detect --format id --warn --filter "coverage:file=<map>,diff=<range>" を実行し、出力された ID を同じシェル内で TESTOMATIO_RUN に格納します。
• <range> は、このデプロイで反映された範囲です。上の表を参照してください。
• --kind detect を指定すると、手動テストのみが含まれる差分の場合、空の自動テスト部分を含む混合ランではなく、手動ランになります。
• TESTOMATIO_TITLE は特定した PR の番号とタイトルだけを使用します。TESTOMATIO_DESCRIPTION にはその URL を設定し、TESTOMATIO_RUNGROUP_TITLE はステップ 2 に従って設定します。
• レポーターが PR コメントを投稿できるよう、プラットフォームのコメントパイプトークンを渡します（プラットフォームごとのトークンは run-tests-with-testomatio-reporter を参照）。
• 対応するテストがマッピングされていない変更も通常どおり発生します。--warn によってジョブは成功するため、出力を解析しないでください。
• カバレッジフィルターで差分を取れるよう、完全な履歴を含めてデプロイ済みリビジョンをチェックアウトします。

（c）自動テストをそのランに対して開始します（自動テスト／混合テストの場合のみ）。

• （b）と同じフィルターおよび範囲を使い、開始対象をテストランの作成時と一致させます。
• リモートの場合：run --remote <profile-name>。インラインの場合：run "<runner command>"。リポジトリをまたぐ場合：CI のネイティブな仕組みで別のリポジトリのパイプラインをトリガーし、ラン ID と API キーを渡します。
• このデプロイで生成された環境の URL をテストで使用できるようにします。リモートモードではリモートパラメーターを、インラインではランナー独自のベース URL 環境変数を使用します。
• 手動テストケースの開始は不要です。テスターがデプロイされた変更に対して手動でテストを実施します。

ステップ 5 — 提供：シークレットと PR

setup-ci-automation の指示に従ってシークレットを設定し、パイプラインの PR を作成します。これに加えて、ここで固有の内容も対応します。

• API キーとともに、PR コメント用パイプトークンを設定します（プラットフォームごとのトークンは run-tests-with-testomatio-reporter を参照）。
• リモート開始用の Testomat.io CI プロファイルは、リポジトリのシークレットではなく、Testomat.io（Settings → CI）で設定します。
• PR の説明には、承認済みのフロー図、組み込んだフェーズ、選択した実行モード、マージ前に設定が必要なシークレットや前提条件を記載します。

ステップ 6 — セットアップを実地検証する（承認後）

CI が実行する前に、実際の変更を使ってローカルで一度コマンドを実行し、パイプラインのコマンドが動作することを確認します。

• ❓ 検証に使う PR と、実際に実行を作成してテストを起動することへの承認をユーザーに確認します。プレビューのデプロイが接続されている場合はオープン中の PR、それ以外の場合はマージ済みの PR を使います。
• ステップ 4 の表に従い、そのデプロイの差分をローカルで再現します。オープン中の PR の場合は、そのブランチをチェックアウトしてターゲットブランチとの差分を確認します。マージ済みの PR の場合は、マージコミットをチェックアウトし、その直前のメインラインの状態との差分を確認します。
• (b) とまったく同じ方法で実行を作成します。同じ種類、同じフィルターを使い、その PR 自身のタイトルから生成されるタイトルを設定します。その後、(c) と同じ方法で、その実行に対して起動します。
• 作成した実行の ID、種類、対象となったテストを報告し、Testomat.io で確認するようユーザーに依頼します。その差分が影響するはずの範囲と一致していますか？
• 対象となるテストが 0 件の場合は、そのことを検出結果として報告し、マッピングされたソースファイルを変更する PR をユーザーと一緒に選びます。

ステップ 7 — 要約して引き継ぐ

承認済みのフロー図を、配線済みとしてもう一度提示します。以下を報告します。対象とした CI と書き込んだファイル、ジョブが接続されているデプロイ、選択した実行モードと Testomat.io CI プロファイルの確認結果、スキップした項目（e2e なし／Testomat.io CI プロファイルなし）、タイトルの形式と rungroup、実地検証の結果とユーザーの確認待ちの実行、これから用意する必要があるシークレットと前提条件、確認が必要な仮定。CI 設定と一緒にカバレッジマップをコミットすることを推奨します。

例

例 1 — 混在プロジェクト、プレビューとマージ後のデプロイ、Testomat.io CI プロファイルあり 調査の結果、手動テストケース、e2e スイート、PR ごとのプレビューのデプロイ、メインライン上のステージングへのデプロイが見つかります。MCP に Testomat.io CI プロファイルの一覧を表示させ、ユーザーが e2e スイートを実行するプロファイルを選択します。→ フィルターなしの run --remote と、ジョブが開始されたことの確認によってプロファイルを検証し、図の承認を得てから、同じジョブを両方のデプロイパイプラインに追加します。PR を取得し、そのデプロイの差分範囲に対応するカバレッジフィルターを使って start --kind detect を実行し、そのデプロイの URL に対してリモートで起動します。PR ごとに 2 件の実行（プレビューで 1 件、ステージングで 1 件）となります。コメントの連携を有効にします。

例 2 — e2e が別のリポジトリにあり、Testomat.io CI プロファイルなし ユーザーがモードの表からリポジトリ間ディスパッチを選択します。同じジョブで実行を作成した後、CI のネイティブな仕組みを使って e2e リポジトリのパイプラインをトリガーし、実行 ID を渡すことで、結果がその実行に記録されるようにします。より簡単な今後の選択肢として、Testomat.io CI プロファイルを使用する方法を記載します。

例 3 — カバレッジマップがまだない coverage*.yml が見つからない場合 → マップがなければフィルタリングできないことを説明し、qa-test-code-coverage に委任します。マップができてから CI を接続します。

例 4 — 手動テストのみのプロジェクト scan-automation-project で .test.md のテストケースが見つかり、e2e フレームワークが見つからない場合 → フロー図には手動テストの分岐だけが表示され、実行モードについての質問はしません。ジョブで PR を特定して実行を作成し、その時点で完了となります。テスターはデプロイされた変更に対して Testomat.io でテストを開始します。起動するには、まず e2e スイートが必要であることを説明します。

関連スキル

setup-ci-automation（CI の調査、作成ルール、シークレット、PR の配信）、run-tests-with-testomatio-reporter（すべてのジョブで実行するレポーターコマンド）、qa-test-code-coverage（このスキルで使用するカバレッジマップを作成）、scan-automation-project（必須の調査）、qa-e2e-tests-reporting（プロジェクトに Testomat.io の連携がまだない場合にレポーターをインストール）、sync-test-cases-with-tms（Testomat.io に未登録の手動テストケース）。