momentic-test

Momentic モデル

Momentic は、フォークした Playwright、CDP、カスタムエージェントを使用して、構造化された自然言語をブラウザー自動化に変換します。インタラクティブなステップでは自然言語のターゲットを解決し、アサーションではマルチモーダルモデルを使用でき、AI アクションではより広範な目標を達成できます。

プロジェクトファイルと形式

テストには *.test.yaml を使用し、再利用可能なモジュールには *.module.yaml を使用します。テスト ID はテストファイルの id フィールドにあります。プロジェクトのデフォルトが適用されると決めつける前に、momentic.config.yaml とテストレベルのメタデータを確認してください。

fileType: momentic/test/v2 と fileType: momentic/module/v2 は v2 ファイルを示します。fileType がない場合、または異なる値の場合は、非推奨の v1 として扱います。v1 の YAML を直接編集してはいけません。変更は momentic_test_splice_steps を通じて保存してください。

v2 テストでは defaultEnv で環境を選択し、--env <name> で上書きします。設定内の環境が 1 つだけでも、その環境へのフォールバックはありません。ベース URL は --url-override、テスト独自の url、env.BASE_URL の順に決まるため、url を設定したテストでは、どの環境でもその URL が保持されます。ベース URL がない場合、実行は失敗し、「Cannot run test with no base URL and no BASE_URL variable defined in its environment」と表示されます。

v2 では、相対パスを使ってモジュール、JavaScript、認証状態を参照できます。パスは、参照を記述した YAML ファイルを基準に解決されます。./... または ../... を使用し、絶対パスや ~ は使用しないでください。参照先ファイルを移動、名前変更、削除する前に、そのパスを grep で検索し、すべての参照を更新または削除してください。v2 YAML に内部フィールドや生成フィールドを追加しないでください。

ワークフローを選択する

ユーザーが別の方法を求めない限り、次の簡潔なワークフローを優先してください。

• 既知の v2 変更： 近くのパターンを確認 -> YAML を編集 -> 構文や参照に不確かな点があれば lint を実行 -> 検証する場合は再読み込みまたは再起動 -> 関連する範囲を実行します。これが最も速く、レビューしやすい差分になります。
• v1、未知の UI、またはインタラクティブな検証： MCP セッションを開始 -> 前提条件を実行 -> 論理的なチェックポイントをプレビュー -> splice する -> 保存した範囲を検証 -> 終了します。テスト全体を何度も実行せずに、ライブアプリに基づいて各編集を行えます。
• 新しいテスト： momentic_test_create で作成 -> 既知の v2 シーケンスを 1 回の YAML 編集で記述するか、調査が必要な場合は MCP でステップごとに進めます。 momentic_session_start は既存のテストのみを開きます。

インタラクティブなインターフェースとしては、MCP をデフォルトで使用してください。MCP は構造化された結果、スクリーンショット、アーティファクト、ステップ参照、ポーリング可能な実行を返します。プレビューと実行の各ツールはデフォルトで 30 秒間待機し、その後、処理の継続中は stepRunnerId を返します。ほとんどの呼び出し、特に単一のプリセットステップでは、timeoutSeconds を設定しないでください。コーディングエージェントのツール呼び出しタイムアウトが 30 秒より短い場合に限り、30 秒未満に設定してください。より長く待つ必要がある場合は、より大きなツール呼び出しタイムアウトの範囲内でのみ値を増やし、返されたハンドルを momentic_poll_runner でポーリングしてください。

ポーリングには別個の timeoutSeconds（デフォルトは 0、最大 30）があります。返された stepRunnerId を渡し、待機せずに繰り返しポーリングするのではなく、コーディングエージェントのツール呼び出しタイムアウトの範囲内で、ゼロ以外の待機時間を指定してください。

編集する前に

テストの目的、ユーザーから見える成功条件、開始環境、認証、環境要件を確認してください。送信、購入、削除、送信、作成、またはその他の非冪等な副作用を引き起こす可能性のあるステップや AI アクションをプレビューまたは実行する前に、ユーザーに確認してください。承認された場合でも、実行は最大 1 回にしてください。また、共有モジュールの編集、長いフローの再起動、コストのかかるテスト全体の実行についても、事前に確認してください。

作成ルール

• 自然言語で対象を指定してください。AI が対象を認識できない場合、またはユーザーがセレクターレベルの精度を求める場合に限り、セレクターや座標を使用してください。
• ブラウザー操作と確認には、Momentic のネイティブステップを使用してください。例外については、テスト実行時の動作のJavaScriptを参照してください。
• 最初のナビゲーションは追加しないでください。セッションはテストのベース URL から開始します。
• アサーションは最小限にし、ユーザーの意図に沿ったものにしてください。ナビゲーションや重要な状態変化の後は、後続の操作に進む前に契約を検証してください。
• URL の契約には waitForUrl を、安定したテキストや構造にはページ／要素の確認を、意味的な視覚状態には AI アサーションを優先してください。
• 新しいテストでは AI Action V3 を優先してください。チェックポイントを個別に制御する必要がある場合は細分化されたステップを使用し、迅速な連続操作については時間依存のインタラクションを参照してください。
• 正しさのために必要でない限り、任意のフィールドやデフォルト値のフィールドは追加しないでください。
• 変更範囲を狭く保ってください。無関係な値、コメント、順序、ステップのスタイルは維持してください。アプリやサービスの不具合を隠すためにテストを弱めないでください。
• テストの意図から変更が必要な場合を除き、既存の before／steps／after 構造を維持してください。

AI Action V3

AI Action V3 は自然言語の目標を受け取り、ブラウザーのステップを決定します。

• デフォルトでキャッシュあり： 成功したフローを保存して再実行し、再実行に失敗したステップは自己修復します。繰り返し実行するフローで使用してください。
• キャッシュなし： 毎回エージェントを新たに実行します。v2 では cache: false を設定するか、AI_ACTION_DYNAMIC とともに --disable-cache を使用してください。チャット、エージェント型ワークフロー、探索的テスト、その他の動的または非決定的な動作には、こちらを優先してください。

ユーザーが特定のルートを指定していない場合、「X ができることを確認する」は目標ベースのテストとして扱ってください。コントロール、中間アサーション、決定論的な再実行、またはリスクのある副作用を個別に制御する必要がある場合は、細分化されたステップを使用してください。戦略の変更を求められていない限り、既存の細分化されたテストはそのまま維持してください。

時間依存のインタラクション

連続送信や起動中の割り込みなど、迅速な連続操作では、順序を明示し、操作間で待機しないよう指示した、焦点を絞った 1 つの AI Action を優先してください。対象を特定するステップを分けると、テスト対象の時間枠を過ぎることがあります。前提条件となるセットアップと安定した最終確認はそのアクションの外に置き、一時的な UI 状態については、動画に基づく実行アサーションを組み合わせてください。

AI Action はタイミングを保証しません。アクションのタイムスタンプと記録された証拠を調べ、意図した状態が実際にテストされたことを確認してください。最終結果が成功したことや、状態を観察せずに一時的な状態を推測するアサーションは、テスト範囲の証明にはなりません。正確な競合タイミングが重要で、安定して再現できない場合は、合格した最終状態をもってカバレッジを主張するのではなく、決定論的なテストまたは制御されたテストフィクスチャを使用してください。

テスト実行時の動作

キャッシュとメモリ

Momentic は、解決済みのセレクター、テキスト、座標、その他のメタデータをキャッシュするため、ほとんどの実行では AI の呼び出しを繰り返さずに済みます。AI アサーションは過去の結果のメモリを再利用することもあります。古いキャッシュやメモリが、誤った要素への素早い一致や、境界的な判定の繰り返しの原因となることがあります。

キャッシュはブランチを含む git メタデータごとにスコープされます。保護されたブランチはキャッシュを読み取りますが、--save-cache を使用するか CI が設定されていない限り、キャッシュには書き込みません。

• 意図が変わった場合は、細分化されたステップの説明を変更してください。通常、ロケーターステップに DANGEROUS_FORCE_DYNAMIC や --disable-cache を追加しないでください。組み込みのキャッシュ検証が、変化するコンテンツに対応します。キャッシュを無効にしても、曖昧な説明の明確化やタイミングまたは競合状態の修正の代わりにはなりません。指示された場合、またはキャッシュ済みロケーターが失敗の原因となり、他の修正で解決できなかった場合に限り、追加してください。
• 成功したプレビューの CacheId は、差し込む対象のステップに正確に引き継いでください。
• 古いメモリが意図する条件と一致しなくなった場合は、アサーションの表現を変更してください。
• AI Action V3 のキャッシュ動作については、上記のAI Action V3を参照してください。

準備状態とタイミング

スマート待機はターゲット指定ステップの前に実行され、デフォルトでは5秒間待機します。この時間内にスリープを追加しないでください。より長い待機や意味的な準備状態が必要な場合は、URLを待つか、必要な肯定的状態を示すページ、要素、またはAIチェックを使用してください。チェックはタイムアウトまで再試行されます。JavaScriptでUIをポーリングするのではなく、タイムアウトを延長してください。プロジェクト全体のタイミング設定については、ブラウザー設定を参照してください。

テストコンテキスト

各実行には、ステップやモジュールをまたいで値が保持される、テスト単位のenvがあります。

• v2では、戻り値をsaveAsで保存します。MCPステップ文字列では--env-keyを使用します。複数の値を保存する場合は、JavaScriptでsetVariable(name, value)を使用します。
• JavaScriptとモジュール入力式ではenv.NAMEを使用します。文字列フィールドでは{{ env.NAME }}を使用しますが、JavaScriptソース内では使用しないでください。
• モジュール入力は文字列として保存されたJavaScriptフラグメントです。リテラル文字列は引用符で囲み、変数にはenv.Xを使用します。

JavaScript

ブラウザーの操作には、ネイティブのクリック、入力、ホバー、待機、チェックの各ステップを使用してください。これらを使うと、Momenticのスマート待機、キャッシュ、トレース、再試行が適用されます。ブラウザーJavaScriptでクリックや入力を行わないでください。また、チェックがタイムアウトまで再試行できる場合は、UIをポーリングしないでください。

テストのセットアップ、データ生成、API、データベース、OTP／メール／SMS、およびMomenticヘルパーには、Node JavaScriptを使用してください。ネイティブのステップで処理を表現できない場合は、window、document、クライアント側の状態へのアクセスや、ページスクリプトの挿入にBrowser JavaScriptを使用してください。単発のコードは短く保ち、再利用可能なv2スクリプトでは周辺のプロジェクト規約に従ってください。ランタイムAPIとタイムアウトの詳細については、JavaScriptガイドを参照してください。

Playwrightのevaluateコールバックはブラウザー内で実行され、Nodeの値をクロージャーで参照できません。値をコールバック引数として渡すか、customWindow._momenticを使用してください。

v2 YAMLの操作

v2は人が編集できます。テストではbefore、steps、afterを使用し、モジュールではstepsを使用します。各ステップにはコマンドキーが1つあり、その下にオプションをネストします。時間の単位はミリ秒で、ステップIDはYAMLに保存されません。

変更は最小限にとどめ、周辺の構文に合わせてください。構文が不明な場合は、Momenticモノレポで作業しているときは、生成されたv2形式のリファレンスinfra/scripts/v2-json-schema/build/v2-format-reference.mdを参照してください。インストール済みのスキルでは、https://static.momentic.ai/v2-format-reference.mdを参照してください。スキーマやファイル参照に問題が生じるおそれがある場合は、`npx momentic lintを実行してください。momentic appとmomentic run`も自動的にlintを実行します。

ディスク上のファイルを編集した後、ツールが利用可能であれば、アクティブなMCPテストを再読み込みしてください。利用できない場合は、セッションを終了して再起動してください。momentic_test_getは永続化された状態を読み取りますが、説明に記載がない限り、アクティブなセッションを更新しません。

MCPブラウザーのワークフロー

最新の引数とステップ構文については、セッション開始時に返されるツールの説明とStep Authoring Guideを使用してください。このスキル内で、それらのリファレンス資料を重複して記載しないでください。

開始してコンテキストを取得する

セッション開始時の定型処理としてコンテキストツールを呼び出さないでください。必要に応じて使用し、特にフィルター機能がある場合や、大量のプロジェクトデータが返される場合は、その説明に従ってください。

• テスト ID が分かっている場合は、momentic_session_start を単独で開始します。Test Content にアクティブなステップと実行可能な ID が含まれます。
• momentic_get_artifacts は、まだ分かっていないプロジェクトパス、テスト、モジュール、環境を確認する場合にのみ使用します。不要な再取得は避けてください。
• 開始前に保存済み状態を確認する場合や、別のテストを読み込む場合は momentic_test_get を使用します。その後はアクティブなセッションを優先し、splice の応答を確認してください。
• ステップで、まだ分かっていない環境データが必要な場合に限り、フィルター付きの momentic_get_environment_variables を使用します。
• 再利用を評価する場合に限り、momentic_module_recommend → momentic_module_get を使用します。recommendation は AI を呼び出しますが、セッション開始には必要ありません。

V2 YAML には実行可能なステップ ID がありません。セッション開始または後続の splice の応答で返された ID を使用してください。

1 つのセッションで実行できるブラウザー操作は 1 つだけです。同じセッションに対して、preview、run、state、splice の操作を並行して実行しないでください。

Preview → splice → validate

1. テスト途中から作業する場合は、直前のステップまで一度実行し、同じセッションを維持します。これにより、誤ったページ状態を基に作業することを防げます。
2. ログイン完了、フォーム準備完了、送信完了など、論理的なチェックポイントごとに先へ進むプレビューを実行します。チェックポイントにより、ブラウザー状態を再利用でき、永続化の呼び出しを確認しやすくなります。
3. 隣接するステップには momentic_preview_steps を使用します。momentic_preview_step と同じプリセット、AI Action、モジュールステップをサポートしています。
4. プレビューと実行のスクリーンショットを主な結果として扱います。スクリーンショットやロケーターの結果だけでは不十分な場合に限り、ブラウザー状態を要求してください。ページがまだ安定していない可能性がある場合は、もう一度要求してください。
5. 成功したチェックポイントを splice します。返された各 CacheId は、対応する正確なステップにのみ割り当ててください。キャッシュのないステップも通常どおりあります。アクティブなステップ参照については、splice の応答をすぐに確認してください。
6. 次に依存する保存済みステップまたは範囲を実行します。プレビューまたは実行で stepRunnerId が返された場合は、別のブラウザー操作を開始せず、その ID の状態を確認してください。
7. 完了前に、安全な場合は前提条件、変更したステップ、次に依存する契約を含む最小の保存済み範囲を実行します。蓄積された状態によって失敗が隠れる可能性がある場合は、先にリセットしてください。
8. 完了したら、セッションを終了します。

明らかにリスクの低いフィールドはまとめて処理します。不確かなロケーターは個別にプレビューします。送信、購入、削除、送信など、冪等でない操作では、セットアップをプレビューしてチェックポイントを splice してから、承認済みの保存アクションを最大 1 回だけ実行します。

通常の編集の合間にリセットしないでください。ネストされたステップでは、アクティブなセッションまたは splice の応答で返された親チェーンを使用してください。

モジュール

再利用可能なステップが 4 つ以上ある論理フローでは、momentic_module_recommend → momentic_module_get → 再利用またはインライン化を確認してください。再利用することでセットアップの重複が減り、テスト固有の契約に集中できます。

モジュール内にモジュールを含めることはできません。共有モジュールを変更する前に、許可を得てください。宣言されているパラメーター、デフォルト値、列挙値に従ってください。モジュールの入力は JavaScript フラグメントであり、{{ }} テンプレートではありません。

トラブルシューティング

ページ状態とタイミング

• ページが間違っている、または古い場合：最新のスクリーンショットまたはセッション状態を確認します。ページが安定しつつある場合は、状態の取得を 1 回再試行します。
• あるチェックポイントで準備が遅い場合：最小範囲のページ、要素、または AI チェックを追加するか、既存のチェックのタイムアウトを延長します。チェックはすでに再試行するため、JavaScript でポーリングしないでください。
• プロジェクト全体でターゲット指定が広範囲に遅い場合：browser.smartWaitingTimeoutMs の延長を検討します。1 つの遅いアサーションを隠すために使用しないでください。
• 長時間かかるジョブやアップロードの場合：スリープではなく、適切なタイムアウトを設定して、安定した成功結果を確認します。
• セッションの状態がずれている場合：resetSession: true を指定して、必要な保存済み範囲を再実行します。

ブラウザーとホストのリソース負荷

ブラウザー、CDP、ページ読み込み、スクリーンショット、またはスナップショットがタイムアウトした場合は、一度だけ再試行するかリセットしてください。再発する場合、または複数のブラウザーツールに影響する場合は、テストの変更を中止してください。待機時間を延ばす、アサーションを弱める、キャッシュフラグを使用する、ブラウザー呼び出しを繰り返すといった方法で、リソース負荷を覆い隠さないでください。

兆候には、応答しないページ、ドキュメントツリーまたはページ実行のタイムアウト、空の HTML スナップショット、ブラウザーまたはインスペクターのクラッシュ、data-momentic-id のタイムアウトなどがあります。ページ読み込みのタイムアウトだけであれば、アプリまたはネットワークに原因がある可能性もあります。

利用可能なホストツールで CPU、メモリ、上位プロセスを調査してください。ブラウザー、Momentic、アプリサーバー、コンパイラー／バンドラー、データベース、無関係なワークロードを確認してください。完了した実行では、存在する場合は attempts/<n>/assets/resource-usage.ndjson と照合してください。

エラー、ステップ、URL、再試行結果、リソース負荷、最大のリソース消費元、裏付けのある原因を報告してください。ホスト、アプリ、サービス、Momentic のどれが原因か証拠から判断できない場合は、その旨を伝えてください。

ターゲット指定とアサーション

• 要素が存在しない場合：前提条件をデバッグしてください。要素が表示されているのに見つからない場合は、表示テキスト、ロール、近くのコンテキストに基づく安定した説明を使用してください。
• 誤った要素にすばやく一致する場合：まず古いキャッシュを検討し、その後説明を修正してください。
• 通常モードで、要素が非表示、無効、切り離されている、覆われている、移動中、またはビューポートの外にあるというエラーは、Playwright のアクション可能性の判定に由来し、Momentic はそのエラーを表面化させています。Momentic のロケーター AI による失敗ではありません。ページの状態または前提条件を修正してください。アクション可能性の判定を回避することが意図した動作の一部である場合に限り、force を使用してください。
• 一部のリッチテキストエディターなど、Playwright のアクション可能性の条件を意図的に満たせないコントロールでは、browser.visualActions: true を使うと座標ベースのアクションが使用されます。この設定は該当するチェックを回避しますが、安定性の保証も失われます。ビジュアルアクションを参照してください。
• 正確なテキストが必要な場合に限り、引用符で囲んだテキストを使用してください。それ以外の場合は意味を説明してください。アサーションでは、領域、オブジェクト、件数、または状態を具体的に指定してください。
• 条件が視覚的なもので、現在のビューポート内に完全に収まっている場合は、assertVisually を使用してください。たとえば、カレンダーグリッドの 11:30～12:00 の行にイベントブロックが表示されていることや、動画フレームまたはキャンバスの描画内に詳細が表示されていることを確認する場合です。必要に応じて呼び出し前に対象をスクロールして表示してください。それ以外の場合は assert を使用してください。
• ステップアサーションで、安定した最終状態をアサートしてください。短時間だけ表示されるトーストや、時間の経過に伴う比較には、動画に基づく実行アサーションを使用してください。

フォーマットとデータ

• V2 の読み込みに失敗した場合：ファイルを lint し、相対参照を確認してください。
• モジュールの実行に失敗した場合：パラメーター、デフォルト値、列挙型、入力式を再確認してください。
• 環境変数の値が欠落している場合：値を生成する保存処理と、使用側の env.X と {{ env.X }} の違いを確認してください。
• JavaScript の実行に失敗した場合：Node コンテキストか Browser コンテキストかを確認してください。

同じ失敗が約 3 回発生したら、試行を中止してユーザーに方針を尋ねてください。