ios-simulator-automation

Xcode 27 の iOS シミュレータをコマンドと MCP で操作・検証するときの道具の選び方と落とし穴。Device Hub を開かずに済む経路と、開くしかない操作の区別。タップ・スワイプ・撮影・回転・要素ツリーの取得、状態の作り込み、xcodebuildmcp / axe / simctl / devicectl / Device Hub / Xcode MCP の使い分けを扱う。シミュレ

SKILL.md

GitHub

iOS シミュレータの自動操作

シミュレータを操作する道具は複数あり、同じことができる道具でも、動くものと動かないものが混ざっている。 何を使うかだけでなく、なぜそれを選んだのかを区別して持っておく。壊れているから避けているのか、 それが本来の道なのかが分からないと、下の層が直ったときに見直せない。

対象バージョン

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 で一覧が出る。