run-tests-with-testomatio-reporter

Testomat.io Reporter でテストを実行する

npx @testomatio/reporter は Testomat.io にテスト実行を作成し、ローカルまたは Testomat.io CI プロファイルを通じてリモートでテストのグループを起動します。すべてのコマンドで TESTOMATIO 環境変数（プロジェクト API キー tstmt_*）が必要で、設定されていない場合は終了コード 1 で終了します。山括弧で囲まれた値はすべてプレースホルダーです。

意図に応じてコマンドを選択する

意図	コマンド
テスト実行を作成し、何も実行しない — テスターが開始する	start
テストをローカルで実行し、結果を報告する	run "<runner command>"
Testomat.io CI プロファイルを使ってテストをリモートで起動する	run --remote <profile-name>
フィルターに一致するテストを一覧表示し、何も実行しない	run --filter-list "<filter>" --format ids
以前に作成したテスト実行を終了する	finish（実行 ID は TESTOMATIO_RUN で指定）
既存のテスト実行を検索し、作成も変更もしない	fetch --project <project-slug>

テスト実行の種類

--kind でテスト実行の内容を指定します。

種類	フラグ	動作
manual	--kind manual	手動テストケースのみ — テスター向けに保留状態となり、起動しなくても完了できます
mixed	--kind mixed	1 つのテスト実行に手動テストと自動テストを含めます — テスターが作業する一方、自動テスト部分は別途起動します
automated	（フラグなし）	自動テストのみ
detect	--kind detect	テスト実行の対象となったテストから Testomat.io が種類を判断します — フィルターを使ったテスト実行で推奨されます

start で作成したテスト実行では何も実行されません。手動テストケースはすぐに保留状態となり、自動テスト部分は起動されるまでスケジュール済みのままです。--format id を指定すると、テスト実行 ID のみが標準出力に出力され（バナーとログは標準エラー出力に出力されるため）、クリーンに取得できます。

RUN_ID=$(npx @testomatio/reporter start --kind manual --format id)

テスト実行に含まれる内容

フィルターを指定しない場合、対象は設定されません。

• start は事前にテスト一覧を指定せずにテスト実行を作成します。テストが TESTOMATIO_RUN=<run-id> を指定して報告すると、その結果が後からテスト実行に追加されます。
• run "<runner command>" はテストスイート全体を実行し、すべての結果を報告します。
• run --remote <profile-name> は、デフォルトの対象範囲で Testomat.io CI プロファイルをディスパッチします。

--filter "<pipe>:<criteria>" を指定すると、テスト実行の対象を一致するテストに絞り込めます。フィルターパイプは 2 種類あります。testomatio:（プロジェクトに保存されたテストメタデータで一致）と coverage:（変更されたソースファイルで一致）です。それ以外のプレフィックスは拒否されます。start と run は同じフィルターを受け付けるため、フィルターで絞り込んだテスト実行を事前に準備し、後から起動できます。

タグ、プラン、ラベル、Jira チケットでフィルターする（testomatio:）

条件	フィルター
タグ	"testomatio:tag-name=<tag>"
プラン（Testomat.io のプラン ID）	"testomatio:plan=<plan-id>"
ラベル	"testomatio:label=<label>"
値を含むラベル	"testomatio:label=<label>:<value>"
Jira チケット	"testomatio:jira-ticket=<ticket-id>"

• 値は、プロジェクトに保存されているタグ名、プラン ID、ラベル、またはチケットと完全に一致する必要があります。
• Playwright、CodeceptJS、Cypress など、ランナーが --grep を受け付けるすべてのテストフレームワークで動作します。フィルターはランナーが使用する grep パターンに変換されます。

変更されたソースファイルでフィルタリングする（coverage:）

--filter "coverage:file=<path-to-coverage-map>,diff=<git-ref>"

「コードの変更によって影響を受けるテストだけを実行する」仕組みです。そのためにはカバレッジマップが必要です。これは、ソースファイルや glob をテスト ID とタグに対応付ける YAML ファイルです。レポーターだけでは、どのテストがどのコードをカバーしているか判断できません。マップがその関連付けを提供し、差分によって影響を受けるエントリが選択されます。qa-test-code-coverage スキルでマップを作成してください（デフォルトは coverage.tests.yml で、手動テストと自動テストの両方に同じファイルを使用します）。

• file= — カバレッジマップのパスです。絶対パスも指定できます。fs で読み込まれるため、作業ディレクトリには依存しません。
• diff= — 差分を取る対象の git ref です。デフォルトは master です。レポーターは process.cwd() 内で git diff <ref> --name-only を実行します。変更を検出するリポジトリの内部から起動してください。
• 変更されたファイルは YAML を通じてマッピングされ、一致したスイート／テスト ID とタグが実行対象になります。
• 一致するテストが 0 件の場合、実行は作成されません（No tests found.）。終了コード：start と --filter-list は 1、run は 0 です。--warn を指定すると、すべて 0 で終了します。

差分の基点を選ぶ

• ブランチ上の変更 → 対象ブランチ（例：origin/<default-branch>）との差分を取ります。git の全履歴が必要です（fetch-depth: 0 または CI の同等の設定）。
• マージ後は対象ブランチが HEAD と一致するため、そこを基点に差分を取ると何も検出されません。代わりに直前のメインラインの先端を使用します。スカッシュマージでは HEAD~1、マージコミットでは HEAD^1 を指定してください。

実行せずに一致するテストを一覧表示する（--filter-list）

--filter-list はフィルターを解決して、一致するテスト ID を出力します。実行は行われず、実行も作成されません。エンコーディングは --format で選択します。ids（カンマ区切り、デフォルト）、grep（選択パターン）、json、newline を指定できます。テストが 1 件以上一致すると終了コード 0、一致しない場合は 1 です。スクリプトで結果に応じて処理を分岐できます。

GREP=$(npx @testomatio/reporter run --filter-list "coverage:file=<coverage-map>" --format grep)
[ -n "$GREP" ] && npx playwright test --grep "$GREP"

--remote とは併用できません。

実行に名前を付けてグループ化する

• TESTOMATIO_TITLE — 実行のタイトルです（例：PR <number>: <title>）。
• TESTOMATIO_RUNGROUP_TITLE — 関連する実行をグループ化します（週／リリース／マイルストーン単位）。
• TESTOMATIO_DESCRIPTION — 自由形式の実行の説明です。実行と PR/MR コメントに表示されます。変更へのリンクをここに記載してください（生成されたカバレッジ範囲がその後に追加されます）。
• TESTOMATIO_ENV — 任意の環境ラベルです。

既存の実行を検索する（fetch）

fetch はプロジェクトの既存の実行を新しい順に返します。読み取り専用です。

プロジェクトのスラッグが必要です。--project <project-slug> を渡すか、TESTOMATIO_PROJECT を設定してください。どちらも指定しない場合は、終了コード 1 で終了します。どちらも指定されていない場合は、ユーザーにプロジェクトのスラッグを尋ねてください。推測してはいけません。TESTOMATIO_URL を設定するとサーバーを上書きできます（デフォルトは https://app.testomat.io）。

オプション	効果
--title <text>	実行タイトルの部分一致
--tql <query>	Testomat Query Language フィルター（例："status = failed"）
--rungroup <uid>	その実行グループ内の実行。ネストされた実行グループも含みます
--limit <number>	返される実行の最大数。新しい順。デフォルトは 30、上限は 100
--latest	最新の実行のみ（--limit 1 と同じ）。フィルターと併用できます

出力：

• --format を指定しない場合：各実行の ID、タイトル、開始／終了時刻、成功／失敗／スキップ数、環境、CI ビルド URL を含む読みやすい一覧。
• --format id：実行 ID のみを 1 行に 1 つ出力します。
• --format json：各実行のすべてのフィールドを含む JSON 配列。

RUN_ID=$(npx @testomatio/reporter fetch --project <project-slug> --title "<title>" --latest --format id)

既存の実行へのレポート

• TESTOMATIO_RUN=<run-id> — 新しい実行を作成せず、指定した実行にレポートを送信するか、その実行に対してテストを起動します。パイプライン間やリポジトリ間でも機能します。テストを実行するプロセスに、TESTOMATIO とタイトル環境変数とともに渡してください。
• ID が手元にない場合 → タイトルで共有実行を照合します。両側で設定してください。
  • TESTOMATIO_SHARED_RUN=1 — 新しい実行を作成する代わりに、TESTOMATIO_TITLE で実行を照合します。
  • TESTOMATIO_TITLE — 照合キー。両側で同じ値を指定します。
  • TESTOMATIO_SHARED_RUN_TIMEOUT — タイトルで照合できる時間（分）。デフォルトは20です。作成から起動までの想定時間差に合わせて設定してください。

リモート起動（run --remote）

--remote <profile-name> は、テストをローカルで実行する代わりに、Testomat.io に Testomat.io CI プロファイル（プロジェクトに保存された CI ワークフロー設定。Settings → CI）をディスパッチするよう指示します。Testomat.io がそのワークフローを起動し、結果は実行にレポートされます。

TESTOMATIO_RUN=$RUN_ID npx @testomatio/reporter run --remote <profile-name> \
  --filter "coverage:file=<coverage-map>,diff=<git-ref>"

• TESTOMATIO_RUN を指定すると、その実行に対して Testomat.io CI プロファイルが起動します。指定しない場合は、新しい実行が作成されます。
• すべてのフィルター形式で機能します。解決されたテスト ID は、grep パターンとして CI ワークフローに渡されます。フィルターがない場合は grep を渡さず、ワークフローのデフォルト範囲、または準備済みの実行では作成時に保存された範囲で実行します。起動時に新しい --filter を指定すると、保存済みの範囲が置き換えられます。
• --remote-param <key>=<value> は、パラメーターを Testomat.io CI プロファイル設定に渡します（複数指定する場合は繰り返します）。たとえば、プレビュー URL や対象ブランチを渡せます。
• 制約：--filter-list とは併用できません。位置引数のコマンドは警告を表示して無視されます。Testomat.io CI プロファイルが見つからない場合は CI launch failed: <message> で失敗し、終了コード 1 を返します。

Testomat.io CI プロファイルの選択

プロファイルごとにワークフロー、ジョブ名、パラメーターが異なるため、決して推測しないでください。ユーザーとやり取りする際は、常に「Testomat.io CI プロファイル」と正式名称で呼び、どのようなものか説明してください。「プロファイル」だけではユーザーに意味が伝わりません。

• Testomat.io MCP に接続済み → Testomat.io CI プロファイルを取得して一覧を提示し、ユーザーに選択してもらいます（接続方法は testomatio-mcp を参照してください）。
• MCP がない → Testomat.io CI プロファイル名をユーザーに尋ねます。
• まだ存在しない → まずユーザーが Testomat.io の Settings → CI で作成する必要があります。

ローカル実行（run "<runner command>"）

テストランナーの実行と結果のレポートを、実行にまとめて行います。フィルターがない場合はスイート全体を実行し、フィルターがある場合は、テストランナーが使用する grep をフィルターから生成します。

TESTOMATIO_RUN=$RUN_ID npx @testomatio/reporter run "<runner command>" \
  --filter "testomatio:tag-name=<tag>"

PR/MR コメント

レポーターが PR/MR の要約コメントを自動で投稿・更新します。start は実行の作成と同時に、予定されているテストを含む保留中のコメントを投稿し、結果がレポートされるたびにそのコメントを更新します。コメント API の呼び出しをスクリプトに記述しないでください。start を含むすべてのレポーターコマンドでトークンを設定し、パイプを有効にしてください。

プラットフォーム	環境変数	備考
GitHub	GH_PAT	PR の実行中は、ワークフローに組み込まれたトークンを使用できます
GitLab	GITLAB_PAT	api スコープを持つアクセストークン
Bitbucket	BITBUCKET_ACCESS_TOKEN	リポジトリアクセストークン

そのプラットフォーム用のパイプがない場合（例：Azure DevOps）はコメントを投稿しません。結果は Testomat.io で引き続き確認できます。

関連スキル

qa-test-code-coverage（coverage: フィルターに必要なカバレッジマップを作成します）、setup-change-aware-pr-testing（これらのコマンドを CI パイプラインに組み込みます）、qa-e2e-tests-reporting（自動化プロジェクトにレポーターをインストールして設定します）。