agentleFS
capsrockcapsrock/ios-simulator-automation-skill/SKILL.md

ios-simulator-automation

Skill3 starsChanged 9 days agoMITView on GitHub

Xcode 27 の iOS シミュレータをコマンドと MCP で操作・検証するときの道具の選び方と落とし穴。Device Hub を開かずに済む経路と、開くしかない操作の区別。タップ・スワイプ・撮影・回転・要素ツリーの取得、状態の作り込み、mobilebuildmcp / axe / simctl / devicectl / Device Hub / Xcode MCP の使い分けを扱う。シミュレータで画面を確認したい、タップが効かない、要素の座標が取れない、回転させたい、スクリーンショットを撮りたい、UI 自動操作が不安定、Device Hub を開かずに済ませたい、といったときに使う。

  • Installs packages

1 other project uses a version of this.

Adopted by

Most recently taken up by

  • Other versions1 project uses a version of this.

    Word for word · 0

    None found.

    Edited · 0

    None found.

    Wrote their own version · 1

    1. miketikh/claude-skillz-conversion★ 4same name

    How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.

The file

Files
SKILL.md

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

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

対象バージョン

Xcode 27.1 以降、iOS 27.1 以降のシミュレータ、macOS 27.2 以降。表の実測は 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 setsimctl に回転が無い。Xcode 27 の正規の手段
回転+タップ+階層をまとめてXcode MCP の DeviceInteractionSynthesize1回でスクリーンショットと hitPoint 付き階層が返る
外観・文字サイズ・コントラストxcrun simctl ui正規の手段
画面の状態づくり⚠ アプリの UserDefaults を直接書くUI 自動操作は取りこぼす。シートが開かない・別の項目に当たる
キー入力⚠ Device Hub で人に押してもらうどの経路も届かない(下記)
折りたたみ端末の開閉・半開きduoctl open / close / half / hingeiPhone 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 で一覧が出る。

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.