ios-simulator-automation
Xcode 27 の iOS シミュレータをコマンドと MCP で操作・検証するときの道具の選び方と落とし穴。Device Hub を開かずに済む経路と、開くしかない操作の区別。タップ・スワイプ・撮影・回転・要素ツリーの取得、状態の作り込み、xcodebuildmcp / axe / simctl / devicectl / Device Hub / Xcode MCP の使い分けを扱う。シミュレ
SKILL.mdSKILL.md
GitHubiOS シミュレータの自動操作
シミュレータを操作する道具は複数あり、同じことができる道具でも、動くものと動かないものが混ざっている。 何を使うかだけでなく、なぜそれを選んだのかを区別して持っておく。壊れているから避けているのか、 それが本来の道なのかが分からないと、下の層が直ったときに見直せない。
対象バージョン
Xcode 27.0 / 27.1、iOS 27.0 / 27.1 のシミュレータ、macOS 26。表の実測は 2026-09-20(iPhone Duo の項目は 2026-10-16)。
Xcode 26 以前には当てはまらない。 下の背景のとおり、土台ごと入れ替わっている。
複数の Xcode を入れている場合、xcrun も MCP も xcode-select が指すほうを使う。
別バージョンのランタイム(折りたたみ端末など)を触るときは、そのコマンドにだけ
DEVELOPER_DIR=... を付ける。
背景 — なぜ Xcode 27 で変わったのか
Xcode 27 で Simulator.app が廃止され、Device Hub に置き換わった。
ファイルの位置も <Xcode>.app/Contents/Developer/Applications/Simulator.app から
<Xcode>.app/Contents/Applications/DeviceHub.app へ移った(bundle id は com.apple.dt.Devices)。
27.0 / 27.1 とも旧パスに Simulator.app は存在しない。
置き換えの中身は統合である。Simulator は端末ごとに別ウインドウを開く作りだったが、 Device Hub は左に端末の一覧、右にその詳細という1ウインドウにまとめ、 シミュレータと実機を同じ画面で扱う。 回転・撮影・ダークモード・文字サイズ・リサイズ・ 実機へのアプリ起動が、すべて同じ場所から行える。
このスキルの内容は、ほぼすべてこの移行から導かれる。
devicectlがシミュレータも扱うようになった。devicectlはもともと実機用の CLI だったが、 統合に合わせて拡張された。simctlに無い回転がdevicectlにあるのはこのため。 新しく何かをしたいときは、simctlだけでなくdevicectlも見る- 既存のツールが軒並み壊れた。
Simulator.appのパスや前提に依存していたものが動かなくなり、 CI やテスト基盤が対応途中にある。このスキルに出てくる「成功と返すのに効かない」たぐいの失敗も、 この移行期にあたっているためと考えられる(Apple の説明があるわけではなく、こちらの推測)。 だからこそ、回避策には「いつ見直すか」を必ず書く
参考: Michael Tsai — Xcode 27's Device Hub / Bitrise — WWDC 2026: Device Hub and what it means for CI/CD
Device Hub 経由かどうか
これが最初の分かれ目になる。Device Hub は画面を占有してユーザーの作業を止めるので、 直接叩ける経路で済むならそちらを使う。
ただし前提が1つある。ここに書いた検証はすべて Device Hub が起動している状態で行った。 Device Hub を終了するとシミュレータも一緒に落ちるため、閉じた状態での可否は確かめていない。 実務上 Device Hub は常に起動しているので、区別が意味を持つのは「GUI を前面に出して人が操作するか」の 一点だと考えてよい。
道具の選び方
⚠ が付いているものは回避策。本来の道が壊れているので代わりに使っている。 いつ見直すかは表の下に書いた。印の無いものは正道で、見直す必要はない。
| やりたいこと | 使うもの | なぜ |
|---|---|---|
| タップ(縦向き) | Claude のシミュレータパネル mcp__Claude_Code_iOS_Simulator__control の tap |
確実に効く。手数が少ない |
| タップ(横向き・確実さ優先) | ⚠ axe touch -x -y --down --up |
パネルのタップが横向きで届かない。axe tap は効かない |
| 要素の座標・ラベル | axe describe-ui |
座標を取る唯一の手段。画像から目測するより正確 |
| 撮影 | ⚠ xcrun simctl io <UDID> screenshot |
パネルの screenshot が captureFailed を返す |
| 回転 | xcrun devicectl device orientation set |
simctl に回転が無い。Xcode 27 の正規の手段 |
| 回転+タップ+階層をまとめて | Xcode MCP の DeviceInteractionSynthesize |
1回でスクリーンショットと hitPoint 付き階層が返る |
| 外観・文字サイズ・コントラスト | xcrun simctl ui |
正規の手段 |
| 画面の状態づくり | ⚠ アプリの UserDefaults を直接書く | UI 自動操作は取りこぼす。シートが開かない・別の項目に当たる |
| キー入力 | ⚠ Device Hub で人に押してもらう | どの経路も届かない(下記) |
| 折りたたみ端末の開閉・半開き | duoctl open / close / half / hinge |
iPhone Duo 用の CLI |
| 折りたたみ端末の内側へのタップ | duoctl tap / long-press / swipe(--label / --id 可) |
axe・パネルのタッチは内側に届かない |
| 可変ウインドウの幅 | ⚠ Device Hub で人に操作してもらう | devicectl device appResize が非対応で弾かれる |
Device Hub と書いた2つだけは、GUI を前面に出して人に操作してもらう。残りは直接叩ける。
回避策を見直す条件:
- 横向きのタップ — axe が上がったら
axe tapと横向きのパネルを再試験する - 撮影 — パネルの
screenshotが直ったら戻す - 画面の状態づくり — 入力系が安定したら UI 操作に戻す
- キー入力 — axe 更新時、iOS / Xcode 更新時に試し直す
- 可変ウインドウの幅 —
Resizableのデバイスタイプが入ったら再試験する
使ってはいけないもの
mobilebuildmcp の tap / swipe / key_press
「成功」と返しても効かない。 返り値を信用しない。中身は同梱の axe を呼んでいるだけで、
その axe が動いていないため。snapshot_ui / describe-ui が失敗するのも同じ根。
同梱の bundled/axe
/usr/local/lib/node_modules/mobilebuildmcp/bundled/axe は describe-ui が失敗する。
Homebrew 版を使う。
brew trust --formula cameroncooke/axe/axe && brew install axe
# → /opt/homebrew/bin/axe
版はどちらも 1.8.0 で同じ。brew 版だけ動くのは、FBSimulatorControl などのフレームワークを同梱し、
インストール時にローカルで codesign されるため。版を上げれば直るという話ではない。
MOBILEBUILDMCP_AXE_PATH に brew 版を指すと mobilebuildmcp 側も差し替えられるが、
axe tap 自体が効かないので tap ツールは直らない。
axe tap
効かない。✓ Tap at (x, y) completed successfully と返すが画面は変わらない。
axe touch -x <x> -y <y> --down --up を使う。 こちらは縦向き・横向きとも届く。
キー入力は届かない
keyboardShortcut や onKeyPress の動作確認は、この環境では自動化できない。
| 試したもの | 結果 |
|---|---|
axe key <keycode> |
届かない |
axe type "<text>" |
届かない |
mobilebuildmcp key_press |
届かない(修飾キーも送れない) |
Xcode MCP sender keyboard kbd <text> |
届かない |
入力欄にフォーカスを置いて1文字送っても入らないので、アプリ側の実装の問題ではない。 シミュレータの「Simulate Hardware Keyboard」が入っていても変わらない。
検証はユーザーに Device Hub 上で押してもらうか、実機にキーボードを繋いで行う。 未確認のままコミットするなら、その旨をコミットメッセージに書く。
座標の落とし穴
describe-uiは画面上の全アプリの階層を返す。 裏のアプリの座標を拾って誤タップしやすい。 目的のアプリに絞ってから読む- 横向きではパネルのタップが届かない。
axe touchを使う - 折りたたみ端末の内側ディスプレイには、axe とパネルのタッチは届かない。
duoctl tapを使う。describe-uiは内側の座標空間で正しい値を返すのに、axe で注入したタッチだけが届かないduoctl tapも、開いた内側でduoctl-helper: no touchscreen for display <ID>と出て 失敗することがある(Duo シミュレータ iOS 27.1、2026-10-16。原因は未調査)- そのときは
duoctl closeで閉じ、外側でタップして画面を進めてから開き、duoctl screenshotで内側を確かめる。起動引数やディープリンクで開ける画面はそちらを使う - axe で届かなかっただけで「内側には届かない」と言わない。
- 再起動すると向きは縦に戻る。 ユーザーが回したあとに勝手に
shutdown/bootをしない
Device Hub を開くしかない操作
コマンドに対応が無いのは次の2つだけ。ほかは全部、直接叩ける経路がある(iPhone Duo の開閉と内側へのタップは duoctl)。
- キーボードの接続(
Device > Keyboard)とキー入力 - 可変ウインドウ(
Enter Resize Mode)。devicectl device appResizeはResizable App Management非対応で弾かれ、名前にResizableを含むディスプレイが要る。 そのデバイスタイプが入っていない環境では使えない
いずれも人にやってもらうことになる。画面まで自分で進めてから、押す操作だけを頼む。 何度も往復させない。
Device Hub を終了するとシミュレータも一緒に落ちる。 作業中は終了させない。
確認の作法
- 返り値ではなく、撮って確かめる。 成功と返して効いていない道具が複数ある
- 読み出した値を報告に書く。 「確認しました」だけでは、その確認をした証拠にならない
- 座標は目測せず
describe-uiのframeから取る。撮った画像から読むのは最後の手段 - 数値が説明できないときは、一時的な計測コードを入れて実測する。 推測で定数を置かない。
onGeometryChangeでproxy.sizeとproxy.safeAreaInsetsをオーバーレイに出し、 確認後に必ず外す
よく使う組み立て
UDID=<simulator-udid>
AXE=/opt/homebrew/bin/axe
# 要素の座標を取る
$AXE describe-ui --udid $UDID
# 押す
$AXE touch -x 344 -y 255 --down --up --udid $UDID
# 撮る
xcrun simctl io $UDID screenshot out.png
# 回す
xcrun devicectl device orientation set --device $UDID landscapeLeft
xcrun devicectl device orientation get --device $UDID
# 状態を作る(UI を触らない)
xcrun simctl status_bar $UDID override --time 9:41 --cellularBars 4 --batteryState charging
xcrun simctl ui $UDID appearance dark
複数ディスプレイを持つ端末は --display で選ぶ。xcrun simctl io <UDID> enumerate で一覧が出る。