2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@softbase(FullStack ITエンジニア)

【iOS】xcrun simctl 完全入門 ― CLIだけでSimulatorを起動・アプリをインストール・操作する

2
Posted at

iOS アプリを開発していると、

  • Simulator を起動したい
  • 指定した iPhone Simulator にアプリをインストールしたい
  • CLI だけでアプリを起動したい
  • CI/CD から Simulator を操作したい
  • Push通知や位置情報をテストしたい
  • スクリーンショットや動画を自動取得したい

といった場面があります。

実は、これらの多くは Xcode の GUI を触らなくても

xcrun simctl

で操作できます。

Apple も simctl を Simulator をコントロールするためのコマンドラインツールとして案内しています。手元の Xcode で利用できる最新のサブコマンドは、次のコマンドで確認できます。

xcrun simctl help

この記事では、日常の iOS 開発でよく使う simctl を一通りまとめます。

1. simctl とは？

simctl は、

Simulator Control

の略と考えると分かりやすいです。

直接 simctl を実行するのではなく、通常は

xcrun simctl

として実行します。

ざっくり言えば、

Terminal
   ↓
xcrun
   ↓
simctl
   ↓
CoreSimulator
   ↓
iPhone / iPad Simulator

というイメージです。

Apple も WWDC で Simulator の CLI 操作に xcrun simctl を紹介しており、利用可能な機能を確認する方法として xcrun simctl help を案内しています。

2. まず覚えるべきコマンド

最初にこの4つだけ覚えると、かなりのことができます。

# Simulator一覧
xcrun simctl list devices

# Simulator起動
xcrun simctl boot <UDID>

# アプリインストール
xcrun simctl install <UDID> MyApp.app

# アプリ起動
xcrun simctl launch <UDID> com.example.MyApp

さらに、すでに起動中の Simulator に対しては

booted

という便利な指定が使えます。

たとえば、

xcrun simctl install booted MyApp.app

xcrun simctl launch booted com.example.MyApp

です。

日常開発では UDID を直接書くより booted を使う方が楽です。

3. Simulator 一覧を確認する

まずは Mac に入っている Simulator を確認します。

xcrun simctl list devices

例えば次のような一覧が表示されます。

== Devices ==
-- iOS 18.x --
    iPhone 16 Pro (A1B2C3D4-...) (Shutdown)
    iPhone 16 (E5F6G7H8-...) (Booted)
    iPhone SE (...) (Shutdown)

重要なのは次の3つです。

iPhone 16
↑ 名前

E5F6G7H8-...
↑ UDID

Booted
↑ 状態

状態には主に

Shutdown
Booted

があります。

4. UDID だけ取得する

スクリプトでは端末名ではなく UDID を取得したくなることがあります。

例えば JSON 形式で取得できます。

xcrun simctl list devices --json

jq と組み合わせると自動化しやすくなります。

xcrun simctl list devices --json | jq

例えば、

UDID=$(xcrun simctl list devices --json \
  | jq -r '
      .devices[][]
      | select(.name == "iPhone 16 Pro")
      | select(.isAvailable == true)
      | .udid
    ' \
  | head -1)

echo "$UDID"

のようなスクリプトも作れます。

5. Simulator アプリを起動する

Simulator.app 自体を開くだけなら、

open -a Simulator

です。

これは覚えておくとかなり便利です。

6. 指定した Simulator を起動する

UDID が分かっている場合、

xcrun simctl boot <UDID>

です。

例えば、

xcrun simctl boot A1B2C3D4-E5F6-...

そのあと GUI も表示したければ、

open -a Simulator

とします。

つまり、

xcrun simctl boot "$UDID"
open -a Simulator

です。

7. 起動完了を待つ

自動化するときに重要なのが、

bootstatus

です。

Simulator に boot を指示した直後は、内部的にはまだ完全起動していない場合があります。

そこで、

xcrun simctl boot "$UDID"

xcrun simctl bootstatus "$UDID" -b

のようにします。

CI やスクリプトでは、

xcrun simctl boot "$UDID"
xcrun simctl bootstatus "$UDID" -b

# この後にアプリをインストール

という流れにすると扱いやすくなります。

8. Simulator を終了する

起動中の Simulator を終了するには、

xcrun simctl shutdown <UDID>

です。

起動している Simulator を全部終了したい場合は、

xcrun simctl shutdown all

とできます。

9. Simulator を初期化する

「Simulator の状態がおかしい」

というときによく使うのが、

erase

です。

xcrun simctl erase <UDID>

すべてリセットするなら、

xcrun simctl shutdown all
xcrun simctl erase all

となります。

⚠️ erase を実行すると Simulator 内のアプリやデータなどが消えるため注意してください。

10. Simulator にアプリをインストールする

ビルド済みの .app がある場合、

xcrun simctl install <UDID> /path/to/MyApp.app

です。

起動中の Simulator なら、

xcrun simctl install booted /path/to/MyApp.app

で OK です。

例えば、

xcrun simctl install booted \
  ./build/MyApp.app

です。

11. アプリを起動する

インストール後は Bundle Identifier を指定して起動します。

xcrun simctl launch <UDID> <BUNDLE_ID>

例えば、

xcrun simctl launch booted com.example.MyApp

です。

Bundle Identifier は Xcode の

TARGETS
→ Signing & Capabilities
→ Bundle Identifier

などから確認できます。

12. アプリを終了する

起動中のアプリを終了するには、

xcrun simctl terminate booted com.example.MyApp

です。

つまり、

xcrun simctl launch booted com.example.MyApp

# ↓

xcrun simctl terminate booted com.example.MyApp

という操作ができます。

13. アプリをアンインストールする

xcrun simctl uninstall booted com.example.MyApp

です。

開発中に状態を完全にリセットしたいなら、

xcrun simctl terminate booted com.example.MyApp

xcrun simctl uninstall booted com.example.MyApp

xcrun simctl install booted MyApp.app

xcrun simctl launch booted com.example.MyApp

という流れも便利です。

14. xcodebuild で Simulator 用にビルドする

ここまでで Simulator の操作方法は分かりました。

次は Swift / SwiftUI アプリを CLI からビルドします。

.xcodeproj の場合、

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination "id=$UDID" \
  build

です。

Workspace を使っている場合は、

xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination "id=$UDID" \
  build

となります。

xcodebuild では -destination を利用して Simulator をビルドやテストの対象として指定できます。

15. 利用可能な destination を確認する

「Simulator 名が合っているはずなのに xcodebuild が失敗する」

という場合に便利なのが、

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -showdestinations

です。

Workspace の場合は、

xcodebuild \
  -workspace MyApp.xcworkspace \
  -scheme MyApp \
  -showdestinations

とします。

表示された id をそのまま

-destination "id=..."

に使えます。

16. DerivedData の出力先を固定すると便利

通常、Xcode のビルド結果は

~/Library/Developer/Xcode/DerivedData/

以下に生成されるため、CLI から .app を探すのが少し面倒です。

そこで、

-derivedDataPath

を指定すると便利です。

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination "id=$UDID" \
  -derivedDataPath ./build \
  build

するとアプリを、

./build/Build/Products/Debug-iphonesimulator/MyApp.app

のように扱えるため、

xcrun simctl install booted \
  ./build/Build/Products/Debug-iphonesimulator/MyApp.app

と書きやすくなります。

17. ビルド → インストール → 起動を全部 CLI で行う

ここまでをつなげます。

UDID="<SIMULATOR_UDID>"
APP_PATH="./build/Build/Products/Debug-iphonesimulator/MyApp.app"
BUNDLE_ID="com.example.MyApp"

# Simulator起動
xcrun simctl boot "$UDID" 2>/dev/null || true

# 起動完了待ち
xcrun simctl bootstatus "$UDID" -b

# Simulator.app表示
open -a Simulator

# Build
xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination "id=$UDID" \
  -derivedDataPath ./build \
  build

# Install
xcrun simctl install "$UDID" "$APP_PATH"

# Launch
xcrun simctl launch "$UDID" "$BUNDLE_ID"

これで、

Simulator起動
    ↓
Swiftアプリをビルド
    ↓
.app生成
    ↓
Simulatorへインストール
    ↓
アプリ起動

まで CLI で完結します。

18. URL を開く

Safari や Custom URL Scheme のテストには、

xcrun simctl openurl booted "https://example.com"

のような操作が便利です。

Custom URL Scheme なら例えば、

xcrun simctl openurl booted "myapp://users/123"

として Deep Link のテストに利用できます。

19. スクリーンショットを撮る

Simulator のスクリーンショットは CLI から保存できます。

xcrun simctl io booted screenshot screenshot.png

例えば、

mkdir -p screenshots

xcrun simctl io booted screenshot \
  screenshots/home.png

です。

Apple の Simulator ガイドでも simctl io ... screenshot によるスクリーンショット取得が紹介されています。

これは、

  • App Store 用画像の作成
  • Snapshot Test
  • UI Test
  • CI での失敗画面保存

などにも便利です。

20. Simulator の画面を録画する

動画も撮れます。

xcrun simctl io booted recordVideo demo.mov

録画を終了するときは、

Ctrl + C

です。

Apple も Simulator の CLI 操作例として simctl io ... recordVideo を紹介しています。

例えば、

xcrun simctl io booted recordVideo \
  simulator-demo.mp4

として、デモ動画を簡単に作れます。

21. 写真を Simulator に追加する

写真選択 UI などをテストしたい場合は addmedia が便利です。

xcrun simctl addmedia booted photo.jpg

複数ファイルも指定できます。

xcrun simctl addmedia booted \
  photo1.jpg \
  photo2.jpg

22. Push Notification を送る

Simulator では Push Notification のテストもできます。

例えば payload.json を作ります。

{
  "aps": {
    "alert": {
      "title": "テスト通知",
      "body": "SimulatorからPush通知を送信しました"
    },
    "sound": "default"
  }
}

そして、

xcrun simctl push \
  booted \
  com.example.MyApp \
  payload.json

です。

Apple も simctl push による Simulator への Push Notification の送信方法を紹介しています。

Push 通知 UI の確認をしたいときにかなり便利です。

23. 権限を CLI から変更する

カメラ、写真、位置情報などの権限テストでは、

simctl privacy

が便利です。

基本形は、

xcrun simctl privacy \
  <device> \
  grant \
  <service> \
  <bundle-id>

です。

例えば、

xcrun simctl privacy \
  booted \
  grant \
  photos \
  com.example.MyApp

のようにします。

Apple は simctl privacy を、ユーザーが選択するプライバシー権限のテストに利用できる機能として紹介しています。

逆に取り消す場合は、

xcrun simctl privacy \
  booted \
  revoke \
  photos \
  com.example.MyApp

です。

実際に利用可能な service 名は Xcode のバージョンによって確認した方が確実なので、

xcrun simctl help privacy

で確認しましょう。

24. 権限状態をリセットする

権限ダイアログを最初からテストしたい場合は、

xcrun simctl privacy \
  booted \
  reset \
  photos \
  com.example.MyApp

のようにリセットできます。

これにより、

初回起動
↓
「写真へのアクセスを許可しますか？」

のようなフローを繰り返しテストしやすくなります。

25. ステータスバーを固定する

スクリーンショットを撮るとき、

現在時刻
Wi-Fi状態
電波状態

が毎回変わると困ることがあります。

そんなときは、

xcrun simctl status_bar booted override

が使えます。

例えば、

xcrun simctl status_bar booted override \
  --time "9:41"

などです。

Apple は status_bar で時刻、電波、ネットワークなどの表示を上書きできることを紹介しています。

解除するときは、

xcrun simctl status_bar booted clear

です。

スクリーンショット自動生成では非常に便利です。

26. アプリのコンテナを確認する

Simulator 上のアプリデータを調べたい場合、

xcrun simctl get_app_container \
  booted \
  com.example.MyApp

を利用できます。

シェル変数にすると、

APP_CONTAINER=$(xcrun simctl get_app_container \
  booted \
  com.example.MyApp)

echo "$APP_CONTAINER"

のように使えます。

アプリのデータ調査や SQLite ファイルなどのデバッグで便利です。

利用できる引数は、

xcrun simctl help get_app_container

で確認してください。

27. Simulator 内でコマンドを実行する

より高度な操作には、

simctl spawn

があります。

基本形は、

xcrun simctl spawn booted <command>

です。

例えば Simulator 内のプロセスを見るなら、

xcrun simctl spawn booted launchctl print system

のように、Simulator 環境内で利用可能なコマンドを実行できます。

28. Simulator のログを見る

かなり便利なのがこれです。

xcrun simctl spawn booted log stream

アプリに絞り込みたい場合は、Unified Logging の predicate を組み合わせます。

例えば、

xcrun simctl spawn booted log stream \
  --predicate 'process == "MyApp"'

のような使い方ができます。

Terminal だけでアプリの挙動を追いたい場合に便利です。

29. launch 時にコンソールを接続する

アプリ起動時に Terminal へ出力を接続できるオプションもあります。

例えば、

xcrun simctl launch \
  --console-pty \
  booted \
  com.example.MyApp

とすることで、CLI デバッグをしやすくできます。

Apple の WWDC セッションでも simctl launch とコンソールを組み合わせたデバッグ方法が紹介されています。

30. アプリに起動引数を渡す

simctl launch ではアプリに引数を渡すこともできます。

例えば、

xcrun simctl launch \
  booted \
  com.example.MyApp \
  -UITestMode YES

とします。

Swift 側では起動引数を利用して、

UITestMode
DebugMode
MockAPI
OnboardingSkip

などを切り替える構成にできます。

これは UI Test や E2E Test の自動化で便利です。

Apple も simctl launch からアプリへ起動引数を渡す利用例を紹介しています。

31. Simulator を新しく作る

Simulator 自体を CLI から作成することもできます。

まず device type と runtime を確認します。

xcrun simctl list devicetypes

xcrun simctl list runtimes

そのうえで、

xcrun simctl create \
  "CI iPhone" \
  <DEVICE_TYPE_ID> \
  <RUNTIME_ID>

のように作成します。

Apple の Xcode Release Notes でも simctl create を使った Simulator 作成方法が紹介されています。

32. Simulator を削除する

作った Simulator を削除する場合、

xcrun simctl delete <UDID>

です。

不要になった Simulator をまとめて整理するときには、

xcrun simctl delete unavailable

も覚えておくと便利です。

実際に利用できる delete オプションは、

xcrun simctl help delete

で確認してください。

33. Simulator Runtime がない場合

必要な iOS Simulator Runtime がインストールされていない場合があります。

現在の Xcode では追加のプラットフォームコンポーネントを Xcode または CLI から取得できます。Apple は xcodebuild -downloadPlatform によるプラットフォーム取得方法も案内しています。

例えば、

xcodebuild -downloadPlatform iOS

です。

34. 実務で便利なシェルスクリプト

最終的には、よく使う処理をスクリプト化するとかなり快適です。

例えば、

#!/bin/bash

set -e

UDID="YOUR_SIMULATOR_UDID"
BUNDLE_ID="com.example.MyApp"

BUILD_DIR="./build"

APP_PATH="$BUILD_DIR/Build/Products/Debug-iphonesimulator/MyApp.app"

echo "==> Boot Simulator"

xcrun simctl boot "$UDID" 2>/dev/null || true

xcrun simctl bootstatus "$UDID" -b

open -a Simulator

echo "==> Build"

xcodebuild \
  -project MyApp.xcodeproj \
  -scheme MyApp \
  -configuration Debug \
  -sdk iphonesimulator \
  -destination "id=$UDID" \
  -derivedDataPath "$BUILD_DIR" \
  build

echo "==> Terminate old app"

xcrun simctl terminate \
  "$UDID" \
  "$BUNDLE_ID" \
  2>/dev/null || true

echo "==> Install"

xcrun simctl install \
  "$UDID" \
  "$APP_PATH"

echo "==> Launch"

xcrun simctl launch \
  "$UDID" \
  "$BUNDLE_ID"

例えば、

run-simulator.sh

として保存して、

chmod +x run-simulator.sh

実行します。

./run-simulator.sh

これだけで、

Simulator起動
        ↓
起動完了待ち
        ↓
SwiftアプリをBuild
        ↓
既存アプリ停止
        ↓
.appをInstall
        ↓
アプリLaunch

まで自動化できます。

35. よく使うコマンド チートシート

一覧

xcrun simctl list devices

起動

xcrun simctl boot <UDID>

起動完了待ち

xcrun simctl bootstatus <UDID> -b

Simulator.appを開く

open -a Simulator

シャットダウン

xcrun simctl shutdown <UDID>

全端末シャットダウン

xcrun simctl shutdown all

初期化

xcrun simctl erase <UDID>

アプリインストール

xcrun simctl install booted MyApp.app

アプリ起動

xcrun simctl launch booted com.example.MyApp

アプリ終了

xcrun simctl terminate booted com.example.MyApp

アンインストール

xcrun simctl uninstall booted com.example.MyApp

URLを開く

xcrun simctl openurl booted "https://example.com"

スクリーンショット

xcrun simctl io booted screenshot screenshot.png

動画

xcrun simctl io booted recordVideo demo.mp4

写真追加

xcrun simctl addmedia booted photo.jpg

Push通知

xcrun simctl push booted com.example.MyApp payload.json

権限付与

xcrun simctl privacy \
  booted \
  grant \
  photos \
  com.example.MyApp

ステータスバー固定

xcrun simctl status_bar booted override \
  --time "9:41"

ステータスバー解除

xcrun simctl status_bar booted clear

ログ

xcrun simctl spawn booted log stream

アプリコンテナ

xcrun simctl get_app_container \
  booted \
  com.example.MyApp

36. 困ったら help

simctl は Xcode とともに更新されるため、ネット上の記事よりも 自分の Mac にインストールされている Xcode の help を優先するのがおすすめです。

Apple 公式ドキュメントでも simctl の詳細確認方法として次のコマンドが案内されています。

xcrun simctl help

特定コマンドについて知りたい場合は、

xcrun simctl help launch

xcrun simctl help privacy

xcrun simctl help io

xcrun simctl help status_bar

のように確認できます。

個人的には、

xcrun simctl help

まで含めて simctl の使い方だと思っています。

まとめ

CLI から iOS Simulator を操作するときの中心となるのが、

xcrun simctl

です。

特に最初に覚えておきたいのは、

xcrun simctl list devices

xcrun simctl boot <UDID>

xcrun simctl install booted MyApp.app

xcrun simctl launch booted com.example.MyApp

の4つです。

さらに、

xcodebuild

と組み合わせれば、

Build
  ↓
Simulator Boot
  ↓
Install
  ↓
Launch
  ↓
Test
  ↓
Screenshot
  ↓
Log

まで CLI で自動化できます。

普段は Xcode の ▶︎ ボタンで実行していても、simctl を覚えると、

  • CI/CD
  • UIテスト
  • E2Eテスト
  • スクリーンショット自動生成
  • Push通知テスト
  • 権限テスト
  • Deep Linkテスト
  • 開発環境セットアップ

などの自動化がかなりやりやすくなります。

最後にもう一度。

xcrun simctl help

これが一番重要なコマンドです。

参考

  • Apple Developer Documentation — Xcode command-line tool reference
  • Apple Developer — Getting the Most Out of Simulator (WWDC19)
  • Apple Developer — Become a Simulator Expert (WWDC20)
  • Apple Developer — Building from the Command Line with Xcode
  • Apple Developer — Interacting with Simulator
2
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
2
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?