momentic-maintain

Momentic テストを保守する

実行が不良状態に入った最も早い時点を見つけ、証拠に基づいて原因を分類し、長期的に維持できるテスト変更が適切な場合はテストを修正します。対象を絞った調査には MCP を使用し、新たな分類結果を得るには momentic ai classify を使用し、自動修正と検証には momentic ai triage を使用します。

アプリケーションのバグ、フィクスチャの不足、認証情報の無効、サービス停止、Momentic の不具合を隠すためにテストを弱めてはいけません。テストが通るように変更するのではなく、それらの原因を報告してください。

よくあるワークフロー

• 自分のブランチで何が起きましたか？ 正確な gitBranchName と範囲を絞った start／end を指定して momentic_list_runs を呼び出します。まずステータスフィルターなしで開始し、その後 FAILED、CANCELLED、または recovered=true に絞り込みます。該当する候補を正確に開き、具体的なブランチ間の比較が必要な場合に限り、main と比較します。
• main が失敗しているのはなぜですか？ インシデント期間について、実際の main ブランチの FAILED 実行を一覧表示し、主張の根拠に必要なすべてのページをページネーションで確認します。既知のカテゴリを調査する場合は failureCategory で絞り込みますが、代表的な実行とステップの証拠を調べてから症状をまとめてください。各実行に保存された分類を確認してから、必要に応じて再分類します。
• フレークを減らし、復旧時間を短縮します。 隔離されたテストには momentic_quarantine_list を使い、復旧が必要だった成功実行には recovered=true を使い、リトライの多い実行には minAttempts を使います（2 は少なくとも 1 回のリトライ、3 は少なくとも 2 回のリトライを意味します）。以前の試行を調べ、同じ意図に対する失敗の繰り返しを優先し、最も早い不安定な事後条件を修正してから、再度測定します。

検出範囲の制限を把握してください。

• momentic_list_runs は、テスト、ブランチ、ステータス、隔離、復旧、有効な失敗カテゴリ、最小試行回数、時刻で絞り込みます。failureCategory は、手動分類があればそれを使い、なければ自動分類を使います。
• momentic_quarantine_list は隔離日で絞り込み、各アクティブな隔離について、保持されている最新の失敗した CLI 実行を返します。ブランチや分類では絞り込みません。
• カテゴリやリトライのしきい値を指定しても、複数のページにまたがる場合があります。網羅的な一覧だと判断する前に、必要な pageCount のすべてのページをページネーションで確認してください。

保守ワークフロー

1. 正確な実行、ブランチ、実行グループ、コミット、またはローカル結果の対象から開始します。
2. 既存の自動／手動分類とヒール状態を最初に確認します。
3. MCP と必要最小限の実行履歴を使って、失敗を正確に再構成します。
4. 編集する前に、最も早い分岐点と満たされていない事後条件を説明します。
5. 役立つ場合にのみ再分類し、求められた場合にのみ判定を保存します。
6. アプリケーションとフィクスチャを適切な状態に準備してから、修正が適切な場合にトリアージを行います。
7. 差分と再実行の証拠を確認し、結論の出ない修正は再実行します。
8. 診断、修正、検証、引き渡し、残っている障害要因を報告します。

既存の分類を確認する

API キーが利用可能な場合は、MCP による調査の前に生の実行メタデータを取得します。

RUN_ID="<run-id>"
MOMENTIC_SERVER_URL="${MOMENTIC_SERVER:-https://api.momentic.ai}"
RUN_INSPECTION_DIR="$(mktemp -d)"

curl --fail --silent --show-error \
  -H "Authorization: Bearer ${MOMENTIC_API_KEY:?Set MOMENTIC_API_KEY}" \
  "${MOMENTIC_SERVER_URL}/v1/runs/${RUN_ID}/metadata" \
  -o "${RUN_INSPECTION_DIR}/metadata.json"

jq '{
  runId: .id,
  status,
  failureReason,
  classification: .failureDetails.classification,
  manualClassification: .failureDetails.manualClassification,
  healStatus,
  healDetails
}' "${RUN_INSPECTION_DIR}/metadata.json"

正確な実行と組織についてメタデータのリクエストが成功するまでは、フィールドがないことを、人間が失敗をレビューしていない証拠として扱わないでください。API キーを表示、ログ出力、コミットしてはいけません。ダウンロードしたメタデータと署名付きアーティファクト URL は、機密性の高い実行データとして扱ってください。

momentic_get_run は、古い判定に引きずられずに新たな調査を行えるよう、返す証拠から以前の分類フィールドとヒール関連フィールドを意図的に除外します。既存の判定はメタデータエンドポイントまたはダッシュボードで確認し、その後、基となる証拠の調査に MCP を使用してください。

役立つ MCP ツール

momentic_get_run - 実行メタデータと、結果ツリー全体の概要を返します。 試行、失敗したセクション、失敗したステップ、ネストされた親のチェーンを特定するために使用します。現在の実行がすでに読み込まれている場合は、別の試行を確認するとき、またはデータが不足しているときに限り、再度呼び出してください。

momentic_list_runs - テストの最近の実行を一覧表示します。対象の実行にgitBranchNameがある場合は、比較対象が同じテストバージョンになる可能性を高めるため、必ず渡してください。ブランチをまたいだ履歴が特定の質問への回答に役立つ場合に限り、省略してください。復旧した実行を調べるには、recovered=trueを渡してください。 有効な手動／自動の分類を選択するにはfailureCategoryを渡し、再試行された実行を探すにはminAttempts: 2以上を渡してください。

momentic_quarantine_list - 有効なローカルテストの隔離と、各テストで直近に保持された失敗済み CLI 実行を一覧表示します。範囲を限定した隔離日時を指定してください。

momentic_get_step_result - 1つのステップについて、コマンドの詳細、実行前後のスクリーンショット、および必要に応じて完全なトレースを返します。ネストされたステップの場合は、parentStepIdChainを渡してください。スクリーンショットと通常のフィールドで質問に回答できない場合に限り、includeTrace=trueを指定してください。

momentic_get_test_steps_for_run - 実行時に記録された簡略版のテスト定義を返します。テストの意図がまだ不明な場合や、作成されたテストが実行間で変更されたかを比較する場合に使用してください。

momentic_submit_result_classification - 手動の MCP 分類を保存します。調査が完了し、ユーザーから判定を記録するよう求められた場合に限り、呼び出してください。同じ結論についてai classify --saveと併用しないでください。

調査ワークフロー

履歴に頼る前に、現在の実行から調べ始めてください。

1. momentic_get_runを呼び出し、失敗した試行、セクション（beforeSteps、メインステップ、またはafterSteps）、失敗したステップ、およびparentStepIdChainがあればそれを特定します。
2. スクリーンショットとトレースを含めて、失敗したステップの結果を取得します。ステップがネストされている場合は、最も近い親コンテナーまたはモジュールの結果も取得します。
3. 失敗したステップの実行前スクリーンショットが、その操作に対する正しいベースラインかどうかを判断します。すでに誤っている場合は、誤った状態を生じさせたステップ／コンテナーが見つかるまで、現在の実行をさかのぼります。
4. モジュールやワークフローが繰り返される場合は、過去の実行と比較する前に、現在の実行内の呼び出しを比較します。後の失敗は、先に実行されて成功または復旧した呼び出しや、無効な事後条件を残した呼び出しが原因であることがよくあります。
5. 子ステップに失敗や復旧がある成功済みコンテナーは、コンテナーの最後の実行後スクリーンショットと URL を確認するまで、部分的な失敗として扱います。
6. 現在の実行の動作を理解してから、特定の比較上の疑問に答えるためにのみ過去の実行を使用します。

分類する前に、次の質問に答えられるようにしてください。

• テストが意図する動作は何ですか？
• 最初に食い違いが生じたステップ／コンテナーはどれですか？
• そのステップが意図していた操作は何ですか？
• 実際にはどの要素／状態を操作または確認しましたか？
• ステップの後、スクリーンショット、URL、DOM、トレース、または復旧ログにどのような変化がありましたか？
• それより後の失敗は、なぜその先行する食い違いの結果なのですか？

「セットアップが不安定だった」「ページが正しくない状態だった」といった曖昧な根本原因は避けてください。壊れた事後条件を具体的に示してください。たとえば、「行単位のプラスボタンをクリックしたが、アプリは子ページのエディターを開かず、親ページにとどまった。続くグローバルなAdd toのアサーションは無関係なページテキストに対して成功したため、対象を指定しない入力ステップでは子ページのタイトルが入力されなかった」のように記述します。

エビデンスの基準

• ページの状態を示すデフォルトの情報源はスクリーンショットです。スクリーンショットに変化があった、またはなかった理由を説明するには、トレースのフィールドと DOM／HTML を使用してください。
• 因果関係に関する主張はすべて検証してください。該当する前後のスクリーンショット、URL、または DOM で確認できない限り、オーバーレイ、サイドピーク、モーダル、メニューが表示されていたと述べないでください。
• 「対象が現在見つからないこと」と「その対象が存在するはずの状態にブラウザーがあること」を区別してください。対象が見つからないのは、多くの場合、それ以前のアクションが失敗したことによる症状です。
• クリック、入力、アクションの各ステップについて、意図したアクション、実際に操作した要素（確認できる場合）、操作前後の URL、期待した UI の状態が表示されたかを記録してください。
• アサーションについては、意図した状態を証明できるよう、スコープが十分に限定されているかを確認してください。ページコンテンツ全体を対象とする広範なアサーションは、無関係なテキストに対しても成功する場合があります。
• リカバリーでは、失敗した子ステップと、リカバリー後のコンテナーの最終状態の両方を確認してください。リカバリーによって再試行したアサーションに合格しても、後続のステップが想定していない状態が残る場合があります。

AI 分類の実行

momentic ai classify は、Momentic の結果分類エージェントを失敗した実行に対して実行します。実行のアーティファクトを読み取り、関連する実行履歴とリポジトリのコンテキストを使用して、カテゴリ、リカバリー可能性、信頼度、推論、引用を返します。失敗の理由を説明しますが、テストは編集しません。

コマンドごとにセレクターを 1 つ使用してください。

npx momentic ai classify --run-id "$RUN_ID" --output-format json
npx momentic ai classify --run-group-id "<run-group-id>"
npx momentic ai classify --git-commit "<commit-sha>"

• 診断目的で再分類する場合は、--save を省略してください。新しい判定でローカルのアーカイブまたはクラウド上の実行に保存済みの分類を置き換える場合に限り、--save を追加してください。
• 既存のキャッシュ済み分類結果が古いと考えられ、ユーザーが最新の分析を明示的に必要としている場合は、--no-cache を使用してください。
• 保存済みの分類がある実行を再確認せずにバッチを再開する場合は、--skip-classified を使用してください。
• 自動化や複数実行の管理には、--output-format json を使用してください。
• 必要に応じて関連する複数の実行 ID をまとめて分類します。ただし、各結果が正確な実行に対応するようにしてください。

実際のターミナルで 1 つの実行を分類する場合は、分類エージェントとの会話を開いたままにしてください。

npx momentic ai classify --run-id "$RUN_ID" --interactive

チャットで、選択したカテゴリの理由、根拠としたエビデンス、現在の実行と以前の実行の違い、または恒久的な修正に必要なことを尋ねてください。対話型の分類は 1 回につき 1 つの実行のみを対象とし、stdin が TTY である必要があります。また、JSON 出力とは併用できません。

トリアージの準備

アプリケーションの準備が整っていることを必須条件として扱います。トリアージでは実際のブラウザーでテストを再実行します。利用できないアプリ、存在しないフィクスチャ、誤った環境、シードされていないデータベース、無効なアカウント、または起動直後のコンパイラーに対するテストを修正することはできません。

トリアージの前に、次の手順を行います。

1. momentic.config.yaml、対象のテストとそのセットアップモジュール、リポジトリのスクリプト、および通常そのテストを実行する CI ワークフローを読みます。同じ URL、環境、認証情報、ヘッダー、ファイル、サービス、データフィクスチャを使用します。
2. MOMENTIC_API_KEY、プロジェクト設定、依存関係、および要求されたブラウザーが利用可能であることを確認します。
3. git status を確認し、無関係な作業を保持します。コマンドの実行前に修正内容の反映方法を決めておきます。ダッシュボードの予期しないデフォルト設定によって、意図せずプルリクエストやコミットが作成されないようにしてください。
4. トリアージを開始する前にアプリケーションをビルドします。本番ビルド、またはそれ以外の事前コンパイル済みビルドと、安定したサーバーを優先します。ルートを段階的にコンパイルする Next.js、webpack、Vite などの開発サーバーは避けてください。
5. 必要なサービスをすべて起動し、実際の準備完了 URL を待ちます。避けられない開発専用のコンパイル経路がある場合は、トリアージの前にウォームアップし、該当ルートにコンパイル中または読み込み中の画面が表示されず、初回リクエストに長時間かからないことを確認します。
6. 必要に応じて、アプリ、フィクスチャ、認証、ブラウザーの準備が整っていることを証明するため、対象を絞ったスモークテストか失敗したテストを一度実行します。トリアージを原因と決めつける前に、セットアップの問題を修正してください。
7. --parallel 1 で開始します。1 つのブラウザーとアプリケーションのワークロードをワーカーごとに実行できるだけの CPU とメモリーがある場合に限り、並列数を増やしてください。

リポジトリに安定したサーバー起動コマンドがある場合は、サーバーを別途起動するか、--start と --wait-on を使用してトリアージにサーバーの起動を任せます。

# Build first; use the repository's actual commands and readiness URL.
pnpm build
npx momentic ai triage --run-id "$RUN_ID" \
  --start "pnpm start" \
  --wait-on "http://localhost:3000/health" \
  --parallel 1 \
  --yes \
  --on-heal-success nothing

これらのコマンド例をそのままコピーしないでください。実際のビルド、起動、準備完了の条件は、リポジトリと CI の設定から確認してください。

AI トリアージを実行する

momentic ai triage は、共通する根本原因ごとに失敗をグループ化し、修復可能かどうかを判断して、該当するテストを編集し、ブラウザーで再実行したうえで、検証に合格した修復のみを受け入れます。変更をローカルに残す、パッチを作成する、コミットする、またはプルリクエストを開くことができます。テストを変更してアプリケーションのバグ、外部サービスの停止、または不足しているフィクスチャを修正することはできません。

ユーザーが明示的な診断を求めている場合は、まず分類を実行し、その後、同じ対象をトリアージに渡します。

npx momentic ai classify --run-id "$RUN_ID" --output-format json
npx momentic ai triage --run-id "$RUN_ID" \
  --parallel 1 \
  --yes \
  --on-heal-success nothing

ローカルの実行グループでは、代わりに結果ディレクトリを渡します。

npx momentic ai triage ./test-results \
  --parallel 1 \
  --yes \
  --on-heal-success nothing

ベストプラクティス：

• バケット化エージェントが共通の原因をグループ化できるよう、複数の関連する実行 ID を 1 つの --run-id の後に渡します。実行ごとに競合するトリアージコマンドを起動しないでください。
• --on-heal-success を明示的に設定します。ローカルでのレビューには nothing、持ち運び可能な差分には patch を使用し、プルリクエストやコミットの動作は、ユーザーがその提出方法を求めた場合にのみ使用します。
• 依存関係に関するプロンプトで自動実行が停止しないよう、環境と提出方法を確認してから --yes を渡します。
• テストを編集したりトリアージのメタデータを保存したりせずにバケット化を確認するには、--dry-run --no-save を使用します。ドライランは修復の試行ではありません。
• キャッシュされた修復が古い、または失敗しており、修復を最初から生成し直す必要がある場合にのみ、--regenerate-heal を使用します。
• コマンドをアタッチしたままにし、推論、ツール呼び出し、ブラウザーの進行状況、CPU、メモリを監視します。ブラウザーの進行が数分間ない場合は、アプリケーションの起動、初回コンパイル、リソース不足、またはフィクスチャの不足が原因の可能性があります。
• 生成された差分はすべて確認します。原因を隠すだけのアサーションの削除、チェック範囲の拡大、根拠のないスリープ、タイムアウトの延長は受け入れないでください。
• トリアージでパッチが生成されたという理由だけで、隔離を解除しないでください。まず修復したテストを再実行します。

ユーザーが修復エージェントに質問したい場合は、対話型トリアージを使用します。

npx momentic ai triage --run-id "$RUN_ID" \
  --parallel 1 \
  --yes \
  --on-heal-success nothing \
  --interactive

対話型トリアージには TTY が必要です。--json と併用することはできず、コマンドがバケット化エージェントを実行する場合にのみ利用できます。修正がなぜ受け入れられたか、または拒否されたか、どのようなセットアップが確認されたか、どのような証拠が未解決のままかを質問するために使用します。

実行アーティファクトを手動でダウンロードする

通常の確認には MCP を優先してください。momentic_get_run はクラウドでの試行を自動的にダウンロードして展開するためです。MCP の出力に不足がある場合、未加工ファイルを grep する必要がある場合、またはエージェントを独立して検証する場合は、API を使用します。

エクスポートエンドポイントは、実行メタデータと試行ごとの有効期限付き署名付き ZIP URL を返します。実行全体をまとめた ZIP は返しません。URL を表示せずにダウンロードして展開します。

RUN_ID="<run-id>"
MOMENTIC_SERVER_URL="${MOMENTIC_SERVER:-https://api.momentic.ai}"
RUN_INSPECTION_DIR="$(mktemp -d)"

curl --fail --silent --show-error \
  -H "Authorization: Bearer ${MOMENTIC_API_KEY:?Set MOMENTIC_API_KEY}" \
  "${MOMENTIC_SERVER_URL}/v1/runs/${RUN_ID}/export" \
  -o "${RUN_INSPECTION_DIR}/export.json"

jq '.run' "${RUN_INSPECTION_DIR}/export.json" \
  > "${RUN_INSPECTION_DIR}/metadata.json"

jq -r '.attemptZipUrls | to_entries[] | select(.value != null) |
  [(.key + 1), .value] | @tsv' "${RUN_INSPECTION_DIR}/export.json" |
  while IFS=$'\t' read -r attempt url; do
    mkdir -p "${RUN_INSPECTION_DIR}/attempts/${attempt}"
    curl --fail --silent --show-error "$url" \
      -o "${RUN_INSPECTION_DIR}/attempt-${attempt}.zip"
    unzip -q "${RUN_INSPECTION_DIR}/attempt-${attempt}.zip" \
      -d "${RUN_INSPECTION_DIR}/attempts/${attempt}"
  done

metadata.json、各試行の metadata.json、スクリーンショット、DOM スナップショット、コンソールログ、HAR ログ、動画、リソース使用状況、クラッシュアーカイブを確認します。試行番号はそのまま保持してください。エクスポートレスポンス、実行アーティファクト、署名付き URL、認証情報、顧客データをコミットしないでください。調査が完了したら一時ディレクトリを削除します。

背景

テスト実行結果の構造

CLI で momentic のテストを実行すると、結果は「実行グループ」に保存されます。この実行グループのデータは、momentic プロジェクト内の 1 つのディレクトリに保存されます。デフォルトのディレクトリ名は test-results ですが、momentic プロジェクトの設定、または実行グループの個別の実行時に変更できます。実行グループの結果フォルダーは次の構造です。

test-results/
├── metadata.json         data about the run group, including git metadata and timing info.
└── runs/                 On zip for each test run in the run group.
    ├── <runId_1>.zip         a zipped run directory containing data about this specific test run.  Follows the structure described below.
    └── <runId_2>.zip

展開すると、実行ディレクトリは次の構造になります。

<runId>/
├── metadata.json           run-level metadata.
└── attempts/<n>/           one folder per attempt (1-based n).
    ├── metadata.json       attempt outcome and step results.
    ├── console.json        optional browser console output.
    └── assets/
        ├── <snapshotId>.jpeg     before/after screenshot for each step (see attempt metadata.json for snapshot ID).
        ├── <snapshotId>.html     before/after DOM snapshot for each step (see attempt metadata.json for snapshot ID).
        ├── har-pages.log         HAR pages (ndjson).
        ├── har-entries.log       HAR network entries (ndjson).
        ├── resource-usage.ndjson CPU/memory samples taken during the attempt.
        ├── <videoName>           video recording (when video recording is enabled).
        └── browser-crash.zip     browser crash dump (only present on crash).

momentic MCP 経由で実行結果を取得すると、momentic_get_run などのツールは MCP の作業ディレクトリ（デフォルトは .momentic-mcp）へのリンクを返します。このディレクトリには、上記の構造に従った、run-result-<runId> という名前の展開済み実行結果フォルダーが含まれます。

要素ロケーター

要素を操作する特定のステップタイプには、「target」プロパティ、つまりロケーターがあり、ステップが操作する要素を指定します。

ロケーターキャッシュ

ロケーターは、ページの状態を表す HTML/XML とスクリーンショットを LLM に送信することで要素を特定します。LLM は、ページ上でユーザーが指している要素を特定します。Momentic は、今後の実行で AI の呼び出しが不要になるよう、LLM の回答を「キャッシュ」しようとします。次回以降の実行では、ページの状態をキャッシュ済みの要素と照合して、その要素が引き続き使用可能か、またはページが十分に変更されていて別の AI 呼び出しが必要かを判断します。

ロケーターキャッシュは、さまざまな理由で無効になることがあります。

• 要素の説明が変更された場合。この場合、キャッシュは常に無効になります。
• 現在のページの状態でキャッシュ済みの要素を見つけられなかった場合。
• ページの状態でキャッシュ済みの要素が見つかったものの、特定の位置、形状、コンテンツを必須とするなど、キャッシュエントリーに指定されたチェックに失敗した場合。

特定のステップの結果にある trace プロパティで cacheBustReason を確認できます。ただし、includeTrace=true を明示的に指定した場合に限ります。また、結果には cache プロパティも記載されており、その要素に保存されたキャッシュ全体を確認できます。

不適切なキャッシュの特定

キャッシュされた要素が、ユーザーが意図した対象と異なることがあります。これにより、テストが失敗したり、予期しない動作が発生したりする可能性があります。このような場合は、なぜ誤ったキャッシュが最初に保存されたのかを正確に確認すると役立ちます。includeTrace=true は、これらのキャッシュのデバッグ時、または Momentic の実行データに誤りがあると疑われる場合にのみ指定してください。誤ったキャッシュの targetUpdateLoggerTags にある runId プロパティを使って、momentic_get_run をこの runId で呼び出し、元の実行の詳細を取得します。これにより、キャッシュ対象が更新された実行が返されます。

モジュールキャッシュ

モジュールのキャッシュキーと解決済みの入力に変更がない場合、キャッシュ済みのモジュールはステップの実行を省略し、モジュールの最後のステップからキャッシュされた戻り値を再利用します。

認証モジュールでは、モジュールキャッシュからブラウザーの認証状態（Cookie、localStorage、IndexedDB を含む）を保存および復元することもできます。認証状態の復元後、ページコンテンツを確認してキャッシュが引き続き有効かどうかを判断する場合があります。

ファイルのアップロード

ファイルアップロードのステップでは、次に開くネイティブのファイル選択ダイアログに渡すファイルを 1 つ準備するため、ダイアログを開くアクションより前に実行する必要があります。

ファイルのソースには、リモート URL、以前にダウンロードしたファイルへの file:// 参照、CLI のローカルパス、またはアップロードされたユーザーファイルを指定できます。このステップでは、表示されるファイル名を変更することもでき、Momentic は準備したファイルをブラウザーのファイル選択処理に連携します。

過去の実行を利用する

過去の実行は比較の根拠であり、現在の実行を再構成する代わりにはなりません。現在の実行だけでは次の点がわからない場合に利用してください。

• このテストが失敗し始めたのはいつですか？
• 前回の成功時と比べて、何が違いましたか？
• 以前の実行では、同じアクションの動作が異なっていましたか？
• テストの弱点、アプリケーションの変更、実際のアプリケーションのバグ、一時的な遅延のどれに該当しますか？

これらの質問に答えるには、過去の実行のステップ結果とスクリーンショットを確認してください。テスト実行で何が起きたかを把握するために、momentic_get_run または momentic_list_runs の概要だけに頼らないでください。過去の実行を根拠として示す前に、ステップ結果やスクリーンショットを含む実行の詳細を確認してください。

過去の実行を確認する際は、次のワークフローを使用してください。

1. momentic_list_runs ツールを呼び出し、詳細を確認する実行を特定します。対象の実行に gitBranchName がある場合は、必ず渡してください。他のブランチの実行が必要な場合は省略してください。
2. 対象の実行に対して momentic_get_run を呼び出し、実行の詳細を取得します。
3. 比較対象と同じステップ／コンテナ、または最も近い同等のものに対して momentic_get_step_result を呼び出します。特にスクリーンショットを確認してください。

現在の実行ですでに根本原因が明らかになっていて、過去の実行が関係ない場合は、過去の実行を無理に根拠として持ち出さず、その旨を簡潔に伝えてください。

複数回の試行を含む実行

momentic_list_runs で attempts > 1 の成功した実行が表示された場合は、問題のない成功として扱わず、調査が必要な部分的な失敗として扱ってください。attemptNumber パラメーターを使って、その実行で先に失敗した試行の結果を取得し、再試行が成功するまで何が問題だったのかを確認してください。

不安定なテストと断続的な失敗

• 同じアプリとテストの動作で断続的に失敗する場合に限り、テストを不安定と判断してください。 失敗が1回だけでは不十分です。不安定さが原因だと判断する前に、実行結果の証拠に基づいてアプリとテストの変更がなかったかを確認してください。

テストの時期による差異

• 過去の結果が、必ずしも今日のテストファイルと一致するとは限りません。テストが変更され、結果が異なるバージョンのテストに対するものになっている場合があります。
• get_test_steps_for_run を呼び出して、実行間でテスト自体が変更されたかを確認できます。ただし、このツールが返すのは各テストステップの_概要_です。テスト実行間で特定のステップの詳細が変わったと考えられる場合は、詳細なステップ情報が momentic_get_step_result のレスポンスに含まれています。それらのフィールドとスクリーンショットでも不十分な場合に限り、includeTrace=true をリクエストしてください。

よくある失敗パターン

• セットアップモジュールが成功したように見えても、誤ったページ、オーバーレイ、フィルター、検索、選択行、またはサイドピークを開いたままにすることがあります。失敗した次のステップだけでなく、望ましくない事後条件を残したステップまたはコンテナーに基づいて分類してください。
• クリックが成功したと報告され、対象の要素も意図したものでも、アプリケーションが意図した状態に遷移しないことがあります。事後状態を確認し、ロケーターが正しいからといってクリックが機能したと思い込まないでください。
• 「ページに X が含まれている」といった弱いグローバルアサーションは、ページ内の無関係なテキストが一致しても成功します。その結果、次のステップで誤ったコンテキストに入力またはクリックすることがあります。
• 特定の対象が指定されていない入力ステップは、先行するアクションが意図したフィールドにフォーカスできていないと、役に立つ場所に何も入力されないままになることがあります。
• ロケーターやキャッシュは技術的に有効でも、意味的に誤っていることがあります。操作した要素を確認し、キャッシュに問題がある場合は targetUpdateLoggerTags.runId の元のキャッシュ更新実行を調べてください。
• 回復したステップによって最初の失敗が隠れることがあります。回復したモジュール内の失敗した子ステップを確認し、回復後の最終状態を次のステップで想定されるベースラインと比較してください。
• タイムアウトだからといって、自動的に INFRA になるわけではありません。まず、データ不足、誤ったページ状態、アプリのフロー変更、不適切なロケーターやアサーション、セットアップの失敗を除外してください。

関連する問題と無関係な問題の特定

• テスト名、説明、簡略化されたステップから意図を判断してください。その意図から外れた失敗は、ほとんどのセットアップ／ティアダウンの失敗も含め、無関係として扱ってください。関連性はバグと変更の分類に関係しますが、INFRA の失敗を別のカテゴリに変えるものではありません。

バグと変更

• バグ：本来起きるべきではないことが明らかに起きた場合です。たとえば、エラーメッセージが表示された場合などです。1つか2つのステップを見るだけで、バグだと明らかに分かります。
• 変更：スクリーンショットによって証明できる、アプリケーションの動作の明確な変化です。

回復可能性

カテゴリに加えて、次のいずれかの回復可能性を判定してください。

• RECOVERABLE — テスト自体を更新すれば、今後の実行が成功するように失敗を自動的に修正できます。
  • 例：テストの更新が必要となるアプリケーションの変更、安定して成功するように書き換えられる曖昧なロケーターやアサーション。
• ONE_TIME_RECOVERABLE — テスト変更を永続化せずに、この特定の実行に限って失敗から回復できます。
  • 例：テストの目的に影響を与えずに閉じられるランダムなモーダル、待機または再試行すれば成功する可能性が高い一時的な遅延。
• NON_RECOVERABLE — 自動的に対処できず、手動での介入が必要な失敗です。
  • 例：認証情報の不足、アップロードに必要なローカルファイルの不足、テストステップでは修正できない、サードパーティーシステムが原因と考えられる障害。

正式な分類結果

• カテゴリ ID は 1 つだけにしてください。新しいラベルの追加や、複数のラベルの付与はできません。
• データに基づいて判断してください。カテゴリを割り当てる前に、実行内容を最後まで十分に調査してください。
• ステップ／モジュールを通称で特定できる場合は、UUID より人が読みやすい参照を優先してください。例：module create-subpage-under-parent-page、the last invocation of module <name>、substep 4 (0-indexed)、the failed setup assertion など。ツール呼び出しでは正確な ID が必要ですが、最終的な推論は読みやすい表現にしてください。
• 最終出力で過去の実行に言及する場合は、UUID をそのまま記載せず、クリック可能な Momentic URL を使用してください。例：https://app.momentic.ai/runs/<runId>。URL 内の UUID は省略しないでください。
• 推論には、最初に逸脱したステップ／コンテナーと、それによって発生した未達成の事後条件を含めてください。最終的に失敗したステップだけを記載してはいけません。

Reasoning: <a few sentences tied to the earliest divergence, screenshots/traces, past runs if used, and test intent>
Category: <one id from the list>
Recoverable: <RECOVERABLE | ONE_TIME_RECOVERABLE | NON_RECOVERABLE>
Confidence: <high | medium | low>

信頼度レベル：

• high — ラベルの変更やクラッシュが明確に示されたスクリーンショットなど、直接的な証拠がある
• medium — 複数のシグナルから強く推測できるが、決定的なスクリーンショットやデータポイントが 1 つもない
• low — 証拠が曖昧で、分類にかなりの推測が必要だった、または根本原因が不明である

カテゴリ ID

以下の文字列をそのまま使用してください。

• NO_FAILURE — 実行に失敗はありませんでした。すべての試行が成功しました。
• APPLICATION_CHANGE — アプリケーションのフローまたは UI が変更されたため、テストが古くなっています。新しい動作に合わせてテストを更新すれば、失敗を恒久的に解消できます。
• BUG — エラーメッセージが表示された、期待されるコンテンツがレンダリングされなかったなど、アプリケーションで明らかに発生すべきでない問題が起きました。
• TEST_AUTHORSHIP — テスト本来の意図を維持しつつ、テストを恒久的に更新して失敗を防ぐことができ、ステップの追加または変更、曖昧なアサーションの書き換え、ロケーターの説明の具体化など、具体的なテスト作成上の変更を提案できます。具体的な変更を挙げられない場合は、別のカテゴリを選択してください。タイムアウト、ページ読み込みの遅延、「もっと長く待つ」またはタイムアウトを延長することが推奨される失敗は、たとえ技術的にはテストを編集して対処できる場合でも、テスト作成上の問題ではありません。これらは INFRA に分類してください。
  • 例：待機／タイムアウト以外のステップを追加または変更して修正できる競合状態（たとえば、「入力して Enter キーを押す」ステップを、明示的にリストから選択するステップに置き換えて、アプリケーションとの競合を回避する）、曖昧なアサーションまたはロケーターの説明をより具体的に書き換える。
• TEST_SETUP — テストの実行に必要なテストデータまたはファイルが不足しており、修正にはテスト自体の外でユーザーの操作が必要です。
  • 例：ファイルアップロードステップに必要なファイルがない、テストに必要な認証情報が不足または誤っている。
• INFRA — 失敗はアプリケーションまたはアプリケーションコードとは無関係で、インフラストラクチャの停止、読み込みの長時間化、その他の外部要因によって発生しました。
  • 例：ブラウザーのクラッシュ、リソース使用率の高さ、レート制限、ページまたはアプリケーションが遅延後に最終的に到達する状態を待つステップまたはアサーションのタイムアウト。
• MOMENTIC_ISSUE — テストの実行または Momentic のデータに問題が発生しました（例：キャッシュが誤っている、グローバルロケーターのリダイレクトが予期しない動作をした、AI が幻覚を起こした）。
  • 例：実行トレースの表示に予期しない動作があった、スクリーンショットでは明らかな内容を AI が誤読または幻覚しており、AI ステップを避けるための合理的なテスト代替手段がない。
• OTHER — 失敗が他のどのカテゴリにも当てはまりません。