momentic-mobile-test

Momentic モデル

Momentic Mobile は、構造化された自然言語を Android エミュレーターおよび iOS シミュレーター上のネイティブアプリと WebView の自動化に変換します。インタラクティブなステップでは対象をデバイス操作に解決し、アサーションではスクリーンショット、ネイティブ階層、WebView の状態を調べることができます。

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

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

fileType: momentic/mobile-test/v2 と fileType: momentic/mobile-module/v2 はモバイル v2 を示します。fileType がない場合や異なる場合は、非推奨の v1 として扱ってください。v1 の YAML を直接編集しないでください。変更は momentic_test_splice_steps を通じて反映してください。

モバイル v2 のテストには platform: ANDROID または platform: IOS が必要です。コマンドはプラットフォームごとに異なります。

モバイル v2 のテストには、独自のデフォルト設定があります。環境変数用の defaultEnv、アプリのチャンネル用の defaultChannel、タグまたは nightly のようなエイリアス用の defaultTag です。--env、--channel、--tag を指定すると、これらの設定が上書きされます。defaultTag は省略可能です。設定されていない場合、実行時にはチャンネル内の最新タグがインストールされます。local リージョンでは、代わりに defaultApkFilePath または defaultAppFilePath がインストールされます。

v2 では、相対パスを使ってモジュール、JavaScript、注入ファイルを参照できます。パスは参照を記述した YAML ファイルを基準に解決されます。./... または ../... を使い、絶対パスや ~ は使わないでください。参照先のファイルを移動、名前変更、削除する前に、そのパスを grep で検索し、すべての参照を更新または削除してください。ファイルベースの JavaScript が使えるのは v2 のみです。v1/MCP のステップ文字列にはコードがインラインで含まれます。v2 YAML に内部フィールドや生成フィールドを追加しないでください。

ワークフローを選ぶ

ユーザーから別の指示がない限り、次の簡潔なワークフローを優先してください。

• 既知の v2 の変更： 周辺のパターンを確認 -> YAML を編集 -> 構文や参照が不確かな場合は lint を実行 -> 検証する場合は再読み込みまたは再起動 -> 該当範囲を実行します。
• v1、未知の UI、またはインタラクティブな検証： MCP セッションを開始 -> 必要な前提処理を実行 -> 論理的なチェックポイントをプレビュー -> splice で適用 -> 保存した範囲を検証 -> 終了します。
• 新しいテスト： momentic_test_create で作成 -> 既知の v2 シーケンスを 1 回の YAML 編集で記述するか、ライブでの探索が必要な場合は MCP を使ってステップごとに記述します。momentic_session_start で開けるのは既存のテストのみです。

インタラクティブ操作には、デフォルトのインターフェースとして MCP を使用してください。プレビューと実行はデフォルトで 30 秒待機し、その後、処理が続行中の場合は stepRunnerId を返します。ほとんどの呼び出し、特に単一のプリセットステップでは timeoutSeconds を設定しないでください。コーディングエージェント側のツールのタイムアウトがそれより短い場合のみ短くし、より長いツールのタイムアウトの範囲内でのみ延長してください。返されたハンドルは momentic_poll_runner でポーリングしてください。

テストに設定されたリモートデバイスとアプリの設定を優先してください。ローカルデバイスまたはアプリのオーバーライドは、ユーザーから明示的に指示された場合にのみ使用してください。

セットアップの前提条件

初期セットアップや、起動、ドライバー、デバイス、接続に関する問題が発生した場合は、npx momentic-mobile doctor を実行してください。サポートレポートを収集する場合は --json を使用してください。詳しくは doctor のリファレンスを参照してください。

リモート Android には adb と ANDROID_HOME が必要です。ローカル Android には Java と Android Studio も必要です。ローカル iOS には macOS と Xcode が必要ですが、シミュレータービルドを利用できる場合、リモート iOS では不要です。不足している依存関係を推測せず、 Android または iOS のセットアップガイドに従ってください。

Android の WebView を自動化するには、WebView のデバッグを有効にしたビルドが必要です。通常、デバッグビルドでは有効になっています。リリースビルドでは明示的に有効にする必要があります。デバッグが無効な場合、一般に No browser controller is attached to the requested webview というエラーが表示されます。モバイル WebView はデバイス経由で実行されるため、ローカルの Chromium のインストールは不要です。

編集前

目的、ユーザーにとっての成功基準、プラットフォーム、アプリのソース、プロバイダー、認証、環境要件を確認してください。送信、購入、削除、送信、作成、またはその他の非冪等な副作用を引き起こす可能性がある手順や AI アクションをプレビューまたは実行する前に、必ず確認してください。承認された場合も、実行は最大 1 回にしてください。また、ローカルデバイスのオーバーライドの使用、共有モジュールの編集、長いフローの再起動、高コストな全テストの実行についても、事前に確認してください。

作成ルール

• 自然言語で対象を指定してください。座標は、キャンバス、マップ、ゲーム、セマンティクスのないカスタムビューなど、AI が認識できない画面領域に限って使用してください。
• デバイスの操作や確認には、ネイティブのモバイル手順を使用してください。例外については、Test execution behavior の JavaScript を参照してください。
• テストでアプリを切り替える必要がある場合や、アプリの状態を復元する必要がある場合を除き、最初にアプリを起動または開く手順を追加しないでください。
• アサーションは最小限にし、ユーザー主導のものにしてください。後続の操作に依存する重要な状態変化を確認してください。
• 決定論的な状態には要素または画面の確認を優先し、意味的な視覚状態には AI による確認を優先してください。条件が完全に可視で、階層データが利用できない、信頼できない、または関係ない場合に限り、視覚情報のみを使った AI 確認を使用してください。
• AI アクションは、ユーザーが要求した場合、または既存のテストですでに使用されている場合に限って使用してください。
• AI アクションはデフォルトでキャッシュされます。フローが正常に完了すると保存され、再生時には失敗したステップが自己修復されます。毎回エージェントを新たに実行するには、AI_ACTION に --disable-cache を追加してください。チャット、エージェント型ワークフロー、探索的テスト、その他の動的または非決定的な動作では、これを優先してください。
• 正確性のために必要な場合を除き、任意フィールドやデフォルト値のフィールドを追加しないでください。
• 変更範囲は限定してください。関係のない値、コメント、順序、ステップのスタイルを維持してください。アプリ、アセット、権限、データ、バックエンドの問題を隠すために、テストを弱めないでください。
• テストの意図に変更が必要な場合を除き、既存の before / steps / after 構造を維持してください。

テスト実行時の動作

キャッシュとメモリ

Momentic は、ネイティブセレクター、XML ノード、表示テキスト、WebView の状態、座標、その他のメタデータをキャッシュします。AI による確認でも、過去の結果のメモリが再利用される場合があります。古くなったキャッシュやメモリが、誤った対象への素早い操作や、境界的な判定の繰り返しにつながることがあります。

キャッシュはブランチを含む Git メタデータに紐付けられます。保護されたブランチでは、--save-cache が使用されているか、CI が設定されていない限り、キャッシュの読み込みは行われますが、書き込みは行われません。

• ステップの意図が変わった場合は、説明を変更してください。通常、ロケーターステップに DANGEROUS_FORCE_DYNAMIC や --disable-cache を追加しないでください。組み込みのキャッシュ検証によって、変化する対象は再検索されます。キャッシュを無効にしても、曖昧な説明の明確化や、タイミングまたは競合状態の問題の修正にはなりません。指示された場合、またはキャッシュ済みのロケーターが失敗を引き起こし、ほかの修正でも解決しない場合に限り、追加してください。
• 成功したプレビューの CacheId を、挿入する対象のステップに引き継いでください。
• 古いメモリが意図する条件と一致しなくなった場合は、アサーションの表現を変えてください。

準備完了状態とタイミング

emulator.smartWaitingTimeoutMs は、AI による検索、キャッシュ済み要素の再試行、その他の単一操作の待機前に、準備完了状態を待つ時間を設定します。一方、emulator.waitForStability は、各操作ステップの後に待機し、その効果が反映されてから次のステップを開始します。段階的に読み込まれるアプリ、画面間でアニメーションするアプリ、または全体的に動作の遅いアプリでは、waitForStability を有効にしてください。これは対象の特定前の待機には影響しません。

スマート待機中は、スリープを追加しないでください。より長い待機や意味的な準備完了状態が必要な場合は、必要な肯定的状態を記述する要素、画面、または AI による確認を使用してください。確認はタイムアウトまで再試行されるため、JavaScript でポーリングするのではなく、タイムアウトを延長してください。プロジェクト全体のタイミング設定については、 モバイル設定を参照してください。

よくある実行上の落とし穴

• キーボードや入力のアニメーションと文字入力が競合することがあります。iOSで入力に時間がかかる場合は、TYPEのキーボード安定待ちオプションを使用してください。カーソルが移動するマスク付きまたは書式設定されたフィールドでは、入力欄を明示的に指定し、必要に応じてキー入力の遅延を追加してください。
• Scrollは表示するコンテンツを指定し、swipeは指のジェスチャーを指定します。下にスクロールすると下方のコンテンツが見つかり、上にスワイプすると指が上に移動してコンテンツが表示されます。

デバイス、アプリ、設定

テストレベルの設定は、プロジェクトのプラットフォーム、アプリのアセット、エミュレーター、ロケール、タイムゾーン、位置情報、タイムアウト、ヘッダー、環境のデフォルト値を上書きできます。動作を変更する前に、両方のレベルを確認してください。

管理対象アセットについては、momentic_get_artifactsのchannelsアーティファクトを、有効なプラットフォームチャンネル、タグ、エイリアスの信頼できる情報源として使用してください。defaultChannelとdefaultTagの動作については、現在のツールの説明に従ってください。

テストコンテキスト

各実行には、ステップやモジュールをまたいで保持されるテストスコープの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、アサーション、ネイティブステップでは表現できないコンテキストへの書き込みには、モバイルJavaScriptを使用してください。単発のコードは短く保ち、再利用可能なv2スクリプトでは、近くにあるプロジェクトの規約に従ってください。現在の構文については、モバイルJavaScriptコマンドを参照してください。

モバイルv2 YAMLの操作

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

変更は最小限にし、近くにある構文に合わせてください。よくある落とし穴は次のとおりです。

• iOSテストでAndroid専用コマンドを使う。
• v2 YAMLで0..100、MCPのステップ文字列で0..1の範囲外の座標を指定する。
• ID、キャッシュデータ、アーティファクト、または誤った詳細ターゲットフィールドを追加する。

トップレベルの構造についてはファイル形式、ステップの構文についてはステップを参照してください。スキーマやファイル参照にリスクがある場合は、npx momentic-mobile lintを実行してください。

ディスク上で編集した後、可能であればアクティブなMCPテストを再読み込みしてください。そうでなければ、セッションを終了して再起動してください。momentic_test_getは永続化された状態を読み取りますが、アクティブなセッションを更新しません。

MCPデバイスのワークフロー

現在の引数とステップ構文については、ツールの説明と、セッション開始時に返されるプラットフォーム固有のステップ作成ガイドを使用してください。このスキル内で、その参考資料を重複して記載しないでください。

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

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

• テスト ID が分かっている場合は、momentic_session_start を単独で開始してください。その Test Content に有効なステップと実行可能な ID が含まれています。プラットフォームはテストから取得されます。
• momentic_get_artifacts は、不明なテスト、モジュール、環境、ローカルデバイス、シミュレーター、または管理対象のアセットチャネルを特定する場合に限り使用してください。不要な再取得は避けてください。
• 開始前に保存済みの状態を確認する場合や、別のテストを読み込む場合は、momentic_test_get を使用してください。その後は、アクティブなセッションと splice の応答を優先してください。
• ステップに必要な環境データが、すでに分かっている情報に含まれていない場合に限り、フィルターを指定して momentic_get_environment_variables を使用してください。
• 再利用を評価する場合に限り、momentic_module_recommend -> momentic_module_get を使用してください。推奨では AI が呼び出されますが、セッションの開始には必要ありません。

1 つのセッションで実行できるデバイス操作は 1 つだけです。同じセッションに対して、プレビュー、実行、状態取得、または splice の操作を並行して実行しないでください。

プレビュー -> splice -> 検証

1. テスト途中から作業する場合は、直前のステップまで一度実行し、作成作業を正しい画面から始められるよう、同じセッションを使用してください。
2. ログイン完了、権限処理完了、フォームの準備完了、送信完了、確認画面の表示など、論理的なチェックポイントまで先にプレビューしてください。
3. まず返されたスクリーンショットを確認してください。対象の特定や診断に十分な情報が画像にない場合に限り、エミュレーターの状態を要求してください。アプリがまだ安定していない可能性がある場合は、状態をもう一度要求してください。
4. 成功したチェックポイントを splice してください。返された各 CacheId は、対応する正確なステップにのみ割り当ててください。その後、splice の応答を確認し、現在のステップ参照を取得してください。
5. 次に依存する保存済みステップまたは範囲を実行してください。プレビューまたは実行で stepRunnerId が返された場合は、別のデバイス操作を開始せず、その ID の完了をポーリングしてください。
6. 完了前に、安全な場合は、前提条件、変更したステップ、次に依存する契約を含む最小範囲の保存済みステップを実行してください。蓄積された状態によって失敗が隠れる可能性がある場合に限り、先にリセットしてください。
7. 終了したら、セッションを終了してください。

明らかにリスクの低いステップはまとめて実行してください。対象が不確かな場合は、個別にプレビューしてください。冪等でない操作の場合は、セットアップをプレビューし、チェックポイントを splice してから、承認済みの保存アクションを最大 1 回だけ実行してください。

MCP のスクリーンショットをデフォルトの判断材料としてください。アクセシブル名、ネイティブ XML、WebView の構造、画面の境界、または画面外のコンテキストが必要な場合は、シリアライズされたエミュレーターの状態を要求してください。データ、起動、またはインストールの動作を診断する場合に限り、環境およびインストール済みアプリのアーティファクトを確認してください。

モジュール

およそ 4 つ以上の再利用可能なステップで構成される論理フローでは、momentic_module_recommend -> momentic_module_get を確認し、再利用するか、インラインで記述してください。モジュール内にモジュールを含めることはできません。共有モジュールを変更する前に、確認を取ってください。

宣言されているパラメーター、デフォルト値、列挙値を守ってください。モジュールの入力は JavaScript フラグメントであり、{{ }} テンプレートではありません。

トラブルシューティング

デバイスの状態とタイミング

• 画面が誤っている、または古い場合：最新のスクリーンショットまたはエミュレーターの状態を確認してください。アプリが安定している途中であれば、状態の取得をもう一度試してください。
• あるチェックポイントだけ準備に時間がかかる場合：対象を絞った要素、画面、または AI のチェックを追加するか、既存のチェックのタイムアウトを延長してください。チェックはすでに再試行されるため、JavaScript でポーリングしないでください。
• プロジェクト全体で対象の特定に時間がかかる場合：emulator.smartWaitingTimeoutMs の値を増やすことを検討してください。1 つの遅いアサーションを隠すために使用しないでください。
• 時間のかかるジョブやアップロードの場合：スリープではなく、適切なタイムアウトを設定し、安定した成功結果を確認してください。
• 権限ダイアログやシステムシートの場合：続行する前に、明示的に処理してください。
• セッションの状態がずれた場合：必要な保存済み範囲を resetSession: true で再実行してください。

インフラストラクチャとアプリの健全性

• WDA、Appium、adb、エミュレーターの起動処理や停止、プロバイダーとの接続、WebView コンテキストの喪失、デバイス状態のキャプチャー失敗の繰り返しは、インフラストラクチャまたはアプリ環境のシグナルとして扱います。まず上記の doctor チェックを行い、ログとデバイスの健全性を調べてから、テストを編集する前にクリーンなセッションで再試行します。
• アプリがアイドル状態にならない場合、アニメーション、動画、バックグラウンド UI 処理が継続していると、iOS のアクセシビリティスナップショットが妨げられることがあります。それらを無効にするテストモードの切り替えを優先します。待ち時間を延ばしても、継続的にビジー状態のアプリがアイドル状態になるわけではありません。
• インフラストラクチャの失敗を隠すためにアサーションを弱めたり、ステップのタイムアウトを増やしたりしないでください。失敗したサブシステムとその裏付けとなる証拠は、テストロジックとは分けて報告します。

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

• 要素が存在しない場合：前提条件またはスクロール状態をデバッグします。要素が表示されているのに見つからない場合：表示テキスト、ロール／名前、周辺のコンテキストを使います。
• 誤ったターゲットへの操作が速やかに行われた場合：まずキャッシュが古くなっていないか確認し、その後、説明を修正します。
• セマンティックなターゲット指定ができない場合に限り、座標ターゲットを使います。MCP の小数値は 0..1、v2 YAML の割合は 0..100 です。
• ターゲットを探すときは SCROLL_TO を使います。ターゲットが存在しない場合、またはスクロールが適切でない場合に限り、手動で SWIPE を使います。
• 引用符で囲んだテキストは文字どおりに扱われます。完全一致のテキストが必要な場合にのみ引用符を使い、それ以外の場合は意味を説明します。
• アサーションでは、領域、オブジェクト、数、状態を具体的に指定します。視覚のみのチェックでは、画面外のコンテンツや階層を調べられません。
• AI チェックはタイムアウトまで、瞬間的なスナップショットを再試行します。安定した最終状態を優先し、契約を表現できる場合は、決定論的な要素チェックまたは画面チェックを使います。アサーションの作成を参照してください。

フォーマットとデータ

• V2 の読み込み失敗：ファイルを lint し、プラットフォームと相対参照を確認します。
• モジュールの失敗：パラメーター、デフォルト値、列挙値、入力式を再確認します。
• 環境変数の値が見つからない場合：値を保存する処理と、使用側の env.X と {{ env.X }} の使い分けを確認します。
• アプリの起動／インストールの問題：テスト設定、チャネル／タグ、installed-apps アーティファクト、セッションがリモートかローカルかを確認します。

同じ失敗が約 3 回続いたら、そこで中止してユーザーに指示を求めます。