testomatio-mcp

Testomatio MCP

MCP 経由で Testomat.io へのアクセスを設定し、QA 分析ワークフローを実行します：分析の実行、失敗のクラスタリング、根本原因の調査、計画の分析、不具合のトリアージ。

使用するタイミング

• AI エージェント（Claude、Cursor、OpenCode など）のために、Testomat.io MCP サーバーを検出または設定します。
• テスト実行を分析します：直近の結果、成功率、失敗の傾向。
• 失敗を調査します：類似した失敗をグループ化し、パターンを見つけます。
• 多数のテストが同じ問題で失敗した場合に、根本原因を特定します。
• 失敗したテストから、ユーザーの課題トラッカー（Jira など）に不具合を作成します。

MCP ツール

• テスト：tests_list、tests_get、tests_search
• テスト計画：plans_list、plans_get、plans_search
• 実行：runs_list、runs_get、runs_search
• テスト実行（実行内の結果）：testruns_list、testruns_get
• スイート：suites_list、suites_get、suites_search
• ラベル：labels_list、labels_get、labels_create、labels_update、labels_delete。ラベルはスコープを指定できます（key:value）。link パラメーターを使って、エンティティにラベルを追加または置き換えます — MCP 設定リファレンス。
• タグ：tags_list、tags_get、tags_search

CRUD ツール（作成、更新、削除）はすべてのエンティティに用意されています。対象を絞った更新が明示的に必要な場合にのみ使用してください。

ルール

• MCP よりローカルのテストを優先してください。 リポジトリに Markdown のテストケース（*.test.md）や自動テストファイルが含まれている場合は、MCP を使ってテストをすべて検出・分析するのではなく、ファイルシステムから読み取ってください（または sync-test-cases-with-tms スキルを使って読み込んでください）。
• MCP は次の用途に使用します：
  • 実行レポートの読み取りと分析
  • 分析とレポート作成
  • テスト計画の管理
  • Testomat.io にのみ存在するテスト（ローカルにコピーがない場合）、またはテストケースの簡易検索（tests_list、tests_search）
  • リモートのテストケースを対象に絞って検索し、個別に更新
• runs_list、plans_list、testruns_list は TQL（Testomat.io Query Language）でフィルターしてください。演算子と使用例：MCP 設定リファレンス。

設定

ステップ 1：既存の設定を検出する

ユーザーの AI エージェント設定ファイルに testomatio または mcp.testomatio エントリがあるか確認します：

• opencode.json
• .cursor/mcp.json
• claude_desktop_config.json
• その他、ユーザーのローカルエージェントに応じたファイル

次を検証します：

• サーバーが有効になっている（クライアントが有効／無効フラグに対応している場合）
• TESTOMATIO_PROJECT_TOKEN と TESTOMATIO_PROJECT_ID が設定されている

設定済みで有効な場合は「ワークフロー」へ進みます。不足、不完全、または無効の場合はステップ 2 に進みます。

ステップ 2：MCP を設定する

設定する前に：

• プロジェクトのテスト数が 1000 件以下であることを確認するのを優先します。
• プロジェクトの規模を確認できない場合は、大規模プロジェクトにおける MCP のパフォーマンス上の制限についてユーザーに警告します。
• 明示的に要求された場合にのみ、対象を絞った操作またはフィルター付き操作を使用してください。

TESTOMATIO_PROJECT_TOKEN と TESTOMATIO_PROJECT_ID の認証情報の優先順位：

1. 既存の環境変数。
2. 既存の MCP 設定。
3. ユーザーから提供された値。

エージェントごとの設定形式（OpenCode、Cursor、Claude Desktop）と認証情報の取得方法：MCP 設定リファレンス。

ルール：

• 無関係な MCP サーバー設定を上書きしないでください。 既存の設定内容に注意して変更を統合してください。
• プロジェクトトークン、シークレット、認証情報をチャットの応答で公開しないでください。

設定が正常に完了したら、次の概要で確認します：

Testomat.io MCP configuration completed successfully.

AI Agent: Cursor
Config Updated: `.cursor/mcp.json`
MCP Server: Enabled
Authentication: Verified

Available workflows:
- Test run analysis
- Failure clustering
- Root-cause investigation
- Plan analysis & defect triage

ワークフロー

よくあるパターンを示していますが、これですべてではありません。ユーザーのニーズに合わせて調整、拡張してください。いずれも MCP サーバーが有効であることを前提としています。

ワークフロー 1：テスト実行の分析

目的：最近のテスト実行の健全性を把握します。

1. runs_list を tql フィルター（例：finished、failed、with_defect）とともに呼び出します。ステータス、環境、またはプランで範囲を絞り込みます。
2. 対象の実行を選び、runs_get を呼び出して詳細なメタデータを取得します。
3. testruns_list を run_id と filter_status: failed を指定して呼び出し、失敗した結果を抽出します。
4. テストの合計数、成功数、失敗数、スキップ数、対象環境をまとめます。
   • 実行ごとの成功率と失敗率を比較して、リグレッションを見つけます。

ワークフロー 2：失敗の調査とエラーのクラスタリング

目的：何が起きたのか、どの領域が影響を受けているのかを特定します。

1. testruns_list（filter_status: failed、run_id）を呼び出して、失敗した結果を取得します。
2. 失敗した各テスト実行について tests_get を呼び出し、スイート、優先度、タグ、関連する課題を特定します。
3. 失敗をクラスタリングします。
   • suite_id ごと → 失敗数が最も多いスイートを特定します
   • message の部分文字列ごと → 同じ例外またはアサーションで失敗しているテストを見つけます
4. クラスターを件数順に並べ、スイートとメッセージの内訳、および影響を受けたテストのタイトルを示します。

ワークフロー 3：プランの分析と根本原因の特定

目的：多くのテストが同じ問題で失敗した場合に、根本原因を説明します。

1. plans_get を呼び出し（プランが実行に関連付けられている場合）、想定される範囲を把握します。失敗が特定のプランセクションと相関しているか確認します。
2. 同じプランまたは環境を対象とする tql を指定して runs_list を呼び出し、過去の実行を取得します。
3. 実行間で失敗を比較します。
   • 失敗数の増加 → 新たなリグレッション
   • 複数の実行で同じ失敗が発生 → 継続的なバグ、または不安定なインフラストラクチャ
   • 1 つのスイートまたはタグで急増 → 限定的なコード変更、機能のリグレッション
   • 無関係なスイートに散在 → 全体的な問題（インフラストラクチャ、設定、依存関係）
4. 影響を受けたテストに対して tests_get を呼び出し、code、state、関連する課題を確認します。
5. 根本原因の仮説を報告します。

例 — ユーザーの質問：「直近の実行で 20 件のテストが失敗した理由を確認してください。特定のスイートの問題ですか、それとも全体的な問題ですか？」

1. Detecting existing Testomat.io MCP configuration:
   - Found `.cursor/mcp.json`
   - Found `testomatio` MCP server entry
   - MCP server status: enabled

2. Verifying MCP availability...
   - Authentication successful
   - Testomat.io tools available

3. Analyzing latest test run...
   - Retrieved last completed run
   - Total failed tests: 20

4. Failure clustering summary:
   - 16/20 failures belong to suite: "Checkout / Payments"
   - 14 failures share the same error: "Timeout waiting for payment confirmation"
   - First failure timestamp indicates failures started simultaneously

5. Probable root cause:
   - The failures appear systemic rather than test-specific.
   - Most failures point to instability or outage in the payment gateway service used during checkout flows.

ワークフロー 4：失敗したテストからの不具合の作成

目的：繰り返し発生する失敗を、追跡可能な不具合にします。

1. ワークフロー 2 を実行し、メッセージごとに失敗をクラスタリングします。
2. 同じ失敗を示すテストが 5 件以上あるクラスターの場合：
   • ユーザーに不具合（例：Jira 課題）の作成を提案します
   • 不具合の概要を下書きします。内容はタイトル、説明、影響を受けたテストのタイトル、失敗メッセージ、実行へのリンク、環境です
   • Jira MCP が利用可能な場合は、Jira スキルを使ってチケットを作成することを提案します
3. 不具合の作成後、影響を受けた各テストに対して tests_issues_link を呼び出し、不具合に関連付けます。

ワークフロー 5：テストのラベルとタグの更新

目的：テストのラベルとタグを設定、変更、または削除します。たとえば、ダッシュボードのグラフに反映されるステータスラベルを更新します。

1. labels_list（または project_info）を呼び出し、スコープ付きラベルの完全な key:value 形式を含め、プロジェクトに存在する正確なラベル値を確認します。ラベル文字列を推測しないでください。
2. 必要に応じて tests_list と TQL を使い、更新するテストを見つけます：label == 'regression:yes'。
3. link 配列を使って tests_update（または tests_create）で更新します。変更ごとに { action, type, value } エントリを 1 つ指定します。値を変更する場合（例：regression:no → regression:yes）、同じ呼び出しで remove と add を送信します。同じ形式を tag、custom_field、milestone、issue、jira にも使用できます。

リンクの形式と入れ替えの完全な例：MCP セットアップリファレンス。

クイックコマンド

操作	MCP ツール	主なパラメーター
失敗した結果を一覧表示	testruns_list	run_id、filter_status: failed
実行を一覧表示	runs_list	tql、page、per_page
実行の詳細を取得	runs_get	run_id
テストの詳細を取得	tests_get	test_id
プランの詳細を取得	plans_get	plan_id
テストに課題をリンク	tests_issues_link	test_id、url または jira_id
ラベルを一覧表示	labels_list	page、per_page
テストのラベルを設定／入れ替え	tests_update	test_id、link
ラベルでテストを検索	tests_list	tql: label == '...'
サーバーの状態を確認	system_ping	なし