limrun-maestro-testing

Limrun iOS での Maestro

ストック版のアップストリーム Maestro CLI を、リモートの Limrun iOS シミュレーターに対して実行します。 lim ios maestro は maestro test をインスタンスに透過的に接続します。必要に応じてシミュレーターに Maestro XCTest ランナーをインストールして起動し、ドライバーの通信をランナーに転送します。Maestro のフォーク、ローカルシミュレーター、ローカル Xcode は不要です。

前提条件

• lim CLI 0.22.0 以降：npm install --global lim。認証には lim login または LIM_API_KEY を使用します（.env やシェルに表示されなくても、ユーザーの環境にすでに設定されている場合があります。要求する前に確認してください）。
• PATH 上に Maestro CLI があること：curl -fsSL https://get.maestro.mobile.dev | bash。 Maestro には Java 17 以降が必要です（確認するには java -version を実行します）。Maestro 2.5.x と 2.6 以降のどちらも動作します。lim はインストール済みのバージョンに自動的に対応します。

CLI が唯一の信頼できる情報源です。フラグでエラーが発生した場合や、ここに記載されていないフラグが必要な場合は、推測せずに lim ios <subcommand> --help を確認してください。

セットアップを確認する

ユーザーのアプリに触れる前に、組み込みの Settings アプリを使ったフローを実行し、パイプライン全体が動作することを確認してください。アプリのインストール、トンネル、ビルドは不要です。

ID=$(lim ios create --install-asset appstore/maestro-ios-runner-2.5.1.tar.gz \
  --no-open --quiet --json | jq -r .metadata.id)

cat > hello-flow.yaml <<'EOF'
appId: com.apple.Preferences
---
- launchApp
- assertVisible: General
- takeScreenshot: settings-check
EOF

lim ios maestro --id "$ID" test hello-flow.yaml

3 つのステップすべてで COMPLETED と報告されれば、Maestro、ランナー、リモート接続がすべて動作しています。ここから先で失敗する場合は、セットアップではなくアプリまたはフローに問題があります。

フローを実行する

lim ios maestro test flow.yaml
lim ios maestro test flows/
lim ios maestro --id <ios-id> test flow.yaml

--id を指定しない場合、現在のワークスペース（ワークスペースは、実行元の git リポジトリまたは worktree に従います）で最後に作成された iOS インスタンスが対象になります。スクリプト、エージェントで実行する場合、または別のディレクトリから実行する場合は、--id <ios-id> を test の前に指定してください。インスタンスで初めて実行するときは、ランナーの起動に数秒余分にかかります（未インストールの場合は、インストールにも時間がかかります）。2 回目以降の実行では、この処理は省略されます。追加の Maestro フラグは -- の後に指定します。

lim ios maestro -- test flow.yaml --include-tags smoke --test-output-dir artifacts

--platform、--device、--udid、--no-reinstall-driver、--driver-host-port は渡さないでください。これらは lim が設定するため、重複指定は拒否されます。 Maestro 本来の終了コードとレポートが保持されるため、ローカルの Maestro と同様に CI に接続できます。

インスタンスのセットアップ

実行中の iOS インスタンスであればどれでも使用できます。ランナーは初回使用時にインストールされます。ランナーを事前インストールしてインスタンスを作成すると、この手順を省略できます。

lim ios create --install-asset appstore/maestro-ios-runner-2.5.1.tar.gz --no-open

--no-open を指定すると、ブラウザーでストリーム URL を開きません（ヘッドレス環境や CI マシンでは重要です）。上記のランナーアセット名は公開されている唯一の名前で、Maestro のバージョンに依存しません。同じランナーで Maestro 2.5.x から 2.7.x まで動作するため、使用する Maestro のバージョンに一致するアセットを探す必要はありません。

テスト対象のアプリは通常どおりインストールしてください（lim ios create --install app.ipa、lim ios install-app、またはビルドスキルを使用）。その後、フローの appId: でバンドル ID を指定します。Expo Go をテストする場合は、appstore/Expo-Go-54.0.6.tar.gz も事前にインストールし、openLink でプロジェクト URL を開いてください（フロー内で環境変数を参照できるようにするには、MAESTRO_ をプレフィックスとして付ける必要があります）。

MAESTRO_EXPO_URL='exp://<tunnel-host>' lim ios maestro test flow.yaml

Expo dev-client ビルド

Expo Go が最も手軽な方法ですが、dev-client ビルドも使用できます。launchApp ではアプリではなく dev launcher が開くため、代わりに dev-client URL を開いてください。- stopApp の後に - openLink: <scheme>://expo-development-client/?url=<url-encoded-metro-url> を実行します。dev-client のビルド、Metro の起動、および URL の導出には limrun-expo-development を使用してください。

Limrun でのフローに関する注意点

• startRecording／stopRecording の YAML コマンドはサポートされていません（シミュレーターがリモートのためです）。実行の前後で録画してください。lim ios record start --id <ios-id> はすぐに戻ります（録画はインスタンス上で行われます）。フローの実行後に lim ios record stop --id <ios-id> -o video.mp4 を実行すると、動画がローカルパスにダウンロードされます。
• takeScreenshot は動作し、標準の Maestro と同様に PNG を作業ディレクトリ（または --test-output-dir）にローカル保存します。
• addMedia と、シミュレーターのローカルファイルパスを参照するフローコマンドはサポートされていません。
• runScript／evalScript からの HTTP 呼び出しでは、https:// URL を使用する必要があります。Maestro の平文 HTTP トラフィックは、リモートシミュレーターへの転送のみを行うローカルブリッジ経由でルーティングされるため、http:// の呼び出しは拒否されます（ドライバー自体への呼び出しを除く）。
• すでに開いているアプリ（Expo Go など）に対してフローを再実行する場合は、openLink／launchApp の前に - stopApp を指定して開始してください。フォアグラウンドで動作中のアプリはディープリンクを受け取れないことがあり、古い画面では初期のアサーションが失敗します。
• インスタンスごとの差異に備え、タイミングではなく、安定したアクセシビリティ識別子とテキストを基準にアサーションを設定してください。アプリの初回起動時は、十分に長いタイムアウトを指定した extendedWaitUntil を使用してください。
• テキストセレクターは要素のアクセシビリティラベルと照合します。iOS では、ラベルに兄弟要素の内容（アイコン名や隣接するテキストなど）や改行なしスペースが含まれることがよくあります。画面表示から推測するのではなく、セレクターを書く前に lim ios element-tree で正確なラベルを確認してください。

検証の手がかり

• Running maestro <version> against <ios-id>... に続いて Running on Limrun iPhone - iOS ... と表示される場合、ドライバーはエンドツーエンドで接続されています。
• Launching the Maestro runner...：このインスタンスでの初回実行です。ランナーのアセットなしでインスタンスが作成された場合に限り、さらに Installing the Maestro runner... も表示されます。以降の実行では、どちらも省略されます。
• Maestro 自身は毎回、JDK の WARNING 行（リフレクション、ネイティブアクセス）を複数出力します。これらは無害な上流由来のノイズであり、Limrun のエラーではありません。
• フローが失敗すると、Maestro 独自のデバッグ出力ディレクトリが表示されます。そこにはスクリーンショットと UI 階層が含まれます。セレクターのデバッグ時には、lim ios element-tree --id <ios-id> で現在の画面を確認できます。

クリーンアップ

作業が終わったら、インスタンスを削除してください：lim ios delete <ios-id>（delete では --id は無効です）。lim ios maestro が起動した接続設定は、コマンドの終了時に破棄されます。