カスタムテスト失敗の理由のエージェントガイドラインを記述する

エージェント > 設定 で自動失敗分類を有効にすると、mablエージェントが失敗したすべての実行にテスト失敗の理由を割り当てます。カスタムテスト失敗の理由の エージェントガイドライン フィールドは、その理由をいつ選択すべきかをエージェントに伝えるためのものです。この記事では、エージェントがガイドラインをどのように使用するかを説明し、効果的なガイドラインを記述するための推奨事項を紹介します。

エージェントによるガイドラインの使用方法

エージェントは、失敗した実行ごとに、収集できる根拠から根本原因を推測します。根拠には、失敗時のスクリーンショット、コンソールログとネットワークログ、失敗したアサーション、直近の実行にわたるテスト結果、関連するデプロイメントイベント、そしてテスト定義そのものが含まれます。次に、ワークスペース内で有効なすべてのテスト失敗の理由（デフォルトとカスタムの両方）を一覧化し、各カスタム理由のエージェントガイドラインを確認して、最も一致する理由を1つだけ割り当てます。

このことから、次の3つの原則が導かれます。

• エージェントは、エラーの文言ではなく根本原因から判断します。 同じ表面的なエラーでも、根本原因はまったく異なる場合があります。たとえば、「element not found」で失敗したテストの原因は、リグレッション、古くなったセレクター、タイミングの問題のいずれの可能性もあります。エージェントは、エラーテキストではなく、その背後にある根拠を調べます。
• エージェントは、常に理由を1つだけ割り当てます。 当てはまるものがない場合は、デフォルトの「その他の問題」が使用されます。カスタム理由が選択されるのは、ガイドラインがその根拠を明確に示している場合のみです。「異常な失敗に割り当てる」といった曖昧なガイドラインでは、エージェントは判断できません。
• ガイドラインは判断の参考になりますが、判断を強制するものではありません。 エージェントは、ガイドラインをすべての根拠と照らし合わせて検討します。選択された理由はあくまで提案であり、実行を確認する担当者がいつでも変更できます。エージェントが誤った理由を選択した場合は、ガイドラインをより明確にすることで、次回以降の実行で精度が向上します。

効果的なガイドラインを記述する

優れたガイドラインは、失敗を切り分ける担当者向けの短い判断ルールのように読めます。

1. 割り当てる条件から始める — 「〜の場合に割り当てる」のように書き始めます。
2. 具体的な手がかりを挙げる — この理由を示す具体的な根拠を挙げます。たとえば、ネットワークログ内のエラーコードやベンダーのドメイン、スクリーンショット内のメッセージ、直近の実行にわたるパターンなどです。説明をそのまま繰り返すだけにしないでください（「ベンダーの障害がある場合に割り当てる」では、エージェントに新しい情報を与えられません）。また、エラーテキストだけに頼らないでください。多くの根本原因が同じ「timeout」を引き起こします。根拠と、それが明らかにする根本原因を記述します。
3. 最も近いデフォルト理由と区別する — 表面的に一致するだけの理由が選ばれないよう、「〜の場合は 環境の問題 よりこちらを優先する」のように記述します。デフォルトの理由はテスト失敗の理由に一覧があります。
4. エージェントが実際に持っている根拠に基づける — 上記に挙げた情報源です。フィーチャーフラグのダッシュボードやJiraチケットなど、エージェントが見られない情報は参照しないでください。
5. 具体的な例で締めくくる — この理由を割り当てるべき失敗を、1文で説明します。

1,000文字の上限に収めてください。多くの場合、短いほど的確になります。

例

サードパーティベンダーの障害 — 自社アプリではなく、依存している外部サービスが原因の失敗です。

自社のコードやインフラではなく、アプリが埋め込んでいる、または呼び出している特定のサードパーティサービス（Stripe や Braintree などの決済ゲートウェイ、Okta や Auth0 などのIDプロバイダー、地図/チャットウィジェットなど）に失敗の原因がある場合に割り当てます。手がかり：ネットワークログで、ベンダー自身のドメインへのリクエストに対する 5xx またはタイムアウトが記録されている。または、ページとテストの直前までのステップは正常に動作していたのに、失敗時のスクリーンショットにベンダーのエラーメッセージ（「Payment provider unavailable」）が表示されている。自社アプリやインフラが広範囲にダウンしている場合の「環境の問題」や、自社アプリに到達するトランスポートレベルの失敗である「ネットワークの問題」より、こちらを優先します。例：同じテストで直前のカートと配送のステップは成功したのに、「Pay」ステップでネットワークログに js.stripe.com からの 503 が記録されて失敗する。

テストデータの問題 — テストとアプリはどちらも正常だが、テストが依存するデータが古い、存在しない、またはすでに使用済みの場合です。

テストのロジックとアプリはどちらも正しいものの、テストが依存するデータが存在しない、古い、またはすでに使用済みである場合に割り当てます。たとえば、ロックされた、または期限切れのアカウントでのログイン、すでに使用済みのクーポンやギフトカード、削除された、または在庫切れのレコードの検索、共有フィクスチャと一致しなくなった金額などです。この場合、失敗時のスクリーンショットには、壊れたページではなく、アプリが正しく動作して入力を拒否している様子（例：「This code has already been used」）が表示されるのが一般的です。テスト自体の古いセレクターや誤ったアサーションが原因の「テストの実装の問題」や、アプリ自体の動作が変化した場合の「リグレッション」より、こちらを優先します。例：1回限りのコードが以前の実行で使用済みになったためにプロモーションコードのステップが失敗し、アプリが正しく「Coupon expired」と表示する。

フィーチャーフラグまたは実験 — A/B実験や段階的なロールアウトによって、テストが想定していないバリアントが表示された場合です。

アプリの恒久的な変更ではなく、A/B実験や段階的な機能ロールアウトによって、テストが想定するものとは異なるバリアントが表示されたことが失敗の原因である場合に割り当てます。手がかり：関連するデプロイメントがないのに、同じテストが直近の実行で成功と失敗を繰り返している。失敗時のスクリーンショットに、（壊れたページや読み込み途中のページではなく）別の有効なレイアウト、文言、または追加の要素が表示されている。あるいは、ネットワークログに実験の割り当てを行うリクエスト（LaunchDarkly、Optimizely、Split）や、このセッションがデフォルト以外のバリアントに振り分けられたことを示すバリアントのCookieが記録されている。特定のデプロイから始まって失敗し続ける恒久的な変更である「リグレッション」や、想定どおりのUIが単に読み込み終わっていないだけの「タイミングの問題」より、こちらを優先します。例：セッションの半数で「Continue」ボタンを「Next」に変更する実験が適用されるために、サインアップのテストが断続的にこのボタンを見つけられず失敗する。

詳細情報

• テスト失敗の理由 — デフォルトとカスタムのテスト失敗の理由、およびカスタム理由のフィールドについて説明します。