isc (iOS Simulator Control)

iOS Simulator Controlは、WebDriverAgentとxcrun/simctlを利用して、iOS SimulatorをCLIから操作できるツールです。

概要

このツールを使うことで、CLIからiOS Simulatorの管理や立ち上げ、スクリーンショットの取得、画面録画、UI要素の操作、タップ・スワイプ操作などを実行できます。

目的

このツールの主な目的は、AI Agentが利用するMCPサーバーとしての活用です。iscを基盤としたMCPサーバーを通じて、AI AgentによるiOSアプリの自動テスト実現のためのインフラを提供します。

isc mcpコマンドでMCPサーバーを起動することで、AI Agentは全てのiscコマンドをツールとして利用できるようになります。

インストール

npm install -g isc

前提条件

• Node.js 18以上
• Xcode (iOS Simulatorが必要)
• WebDriverAgent (UI要素操作に必要)

対応操作

• iOS Simulatorの管理 (起動・停止・再起動・ステータス確認)
• WebDriverAgentの実行と管理
• アプリ管理 (インストール・アンインストール・起動・終了・一覧・情報取得)
• スクリーンショットの取得と保存
• 画面録画の開始・停止・保存
• UI要素の検索・操作・情報取得
• ページソース・アクセシビリティツリーの取得
• タップ・スワイプ操作
• ホームボタン操作
• MCPサーバー機能 (AI Agent統合)

コマンド使用方法

iOS Simulator管理

# iOS Simulator一覧の表示
isc simulator list

# iOS Simulatorの起動
isc simulator boot --udid <udid>

# iOS Simulatorの停止
isc simulator shutdown --udid <udid>

# iOS Simulatorの再起動
isc simulator reboot --udid <udid>

# iOS Simulatorのステータス確認
isc simulator status --udid <udid>

WebDriverAgent管理

# WebDriverAgentの実行 (指定パスでビルド&実行)
isc wda run --udid <udid> --path <path>

# WebDriverAgentの停止
isc wda stop --udid <udid>

# WebDriverAgentのステータス確認
isc wda status --udid <udid>

# 実行中のWebDriverAgent一覧
isc wda list

# 全WebDriverAgentプロセスの停止
isc wda stop-all

環境変数での設定

WebDriverAgentのパスは環境変数WDA_PATHで設定することも可能です：

# 環境変数を設定
export WDA_PATH="/path/to/WebDriverAgent"

# パスを省略してMCPサーバー経由で実行可能
# （CLIでは--pathパラメータは必須）

環境変数が設定されている場合、MCPサーバー経由での実行時にpathパラメータを省略できます。

アプリ管理

# インストール済みアプリの一覧表示
isc app list --udid <udid>

# システムアプリも含む一覧表示
isc app list --udid <udid> --system

# アプリのインストール (.app bundle または .ipa ファイル)
isc app install --udid <udid> --path <app_path>

# アプリのアンインストール
isc app uninstall --udid <udid> --bundle-id <bundle_id>

# アプリの起動
isc app launch --udid <udid> --bundle-id <bundle_id>

# 起動引数と環境変数を指定してアプリを起動
isc app launch --udid <udid> --bundle-id <bundle_id> --args '["--debug", "--verbose"]' --env '{"DEBUG": "1", "LOG_LEVEL": "debug"}'

# アプリの終了
isc app terminate --udid <udid> --bundle-id <bundle_id>

# アプリの詳細情報取得
isc app info --udid <udid> --bundle-id <bundle_id>

スクリーンショット

# スクリーンショットの取得 (デフォルトファイル名)
isc screenshot --udid <udid>

# 指定パスにスクリーンショットを保存
isc screenshot --udid <udid> --output <path>

画面録画

# 画面録画の開始
isc record start --udid <udid>

# 画面録画の停止
isc record stop --udid <udid>

# 指定パスに録画を保存して停止
isc record stop --udid <udid> --output <path>

# 録画状態の確認
isc record status --udid <udid>

# アクティブな録画一覧
isc record list

# 録画保存ディレクトリの表示
isc record dir

UI要素操作

要素の検索

# 単一要素の検索
isc elements find --udid <udid> --using "accessibility id" --value "ButtonID"

# 複数要素の検索
isc elements find-all --udid <udid> --using "class name" --value "XCUIElementTypeButton"

# 要素の詳細情報取得
isc elements info --udid <udid> --using "accessibility id" --value "ButtonID"

要素の操作

# 要素のクリック
isc elements click --udid <udid> --using "accessibility id" --value "ButtonID"

# 要素のテキスト取得
isc elements text --udid <udid> --using "accessibility id" --value "LabelID"

# 要素へのテキスト入力
isc elements send-keys --udid <udid> --using "accessibility id" --value "TextFieldID" --text "Hello World"

要素検索戦略

サポートされている検索戦略（--usingパラメータ）:

• accessibility id: アクセシビリティID
• class name: クラス名 (例: XCUIElementTypeButton)
• xpath: XPath式
• predicate string: NSPredicate形式

ページソース取得

# ページソース（JSON形式）の取得
isc elements source --udid <udid>

# ページソースをファイルに保存
isc elements source --udid <udid> --output page_source.json

# アクセシビリティツリーの取得
isc elements accessible-source --udid <udid>

# アクセシビリティツリーをファイルに保存
isc elements accessible-source --udid <udid> --output accessibility_tree.json

タップ操作

# 指定座標をタップ
isc tap --udid <udid> --x <x> --y <y>

# タップ時間を指定（ミリ秒）
isc tap --udid <udid> --x <x> --y <y> --duration 1000

スワイプ操作

座標指定スワイプ

# 開始・終了座標を指定してスワイプ
isc swipe coord --udid <udid> --from-x <x1> --from-y <y1> --to-x <x2> --to-y <y2>

# スワイプ時間を指定（ミリ秒）
isc swipe coord --udid <udid> --from-x <x1> --from-y <y1> --to-x <x2> --to-y <y2> --duration 500

方向指定スワイプ

# 上方向にスワイプ（画面下部中央から）
isc swipe up --udid <udid>

# 下方向にスワイプ（画面上部中央から）
isc swipe down --udid <udid>

# 左方向にスワイプ（画面右端中央から）
isc swipe left --udid <udid>

# 右方向にスワイプ（画面左端中央から）
isc swipe right --udid <udid>

# スワイプ距離を指定
isc swipe up --udid <udid> --distance 300

# スワイプ時間を指定
isc swipe up --udid <udid> --duration 1000

ホームボタン操作

# ホームボタンを押す
isc home --udid <udid>

MCP (Model Context Protocol) サーバー

# MCPサーバーを起動 (AI Agent統合用)
isc mcp

# MCPサーバーを起動すると、以下の32個のツールが利用可能:
# - iOS Simulator管理: simulator_list, simulator_boot, simulator_shutdown, simulator_reboot, simulator_status
# - WebDriverAgent管理: wda_run, wda_stop, wda_status, wda_list, wda_stop_all
# - アプリ管理: app_list, app_install, app_uninstall, app_launch, app_terminate, app_info
# - スクリーンショット: screenshot
# - 画面録画: record_start, record_stop, record_status, record_list
# - UI要素操作: elements_find, elements_find_all, elements_click, elements_text, elements_send_keys, elements_info, elements_source, elements_accessible_source
# - タッチ操作: tap, swipe_coord, swipe_directional, home

MCPサーバーはstdioトランスポートを使用し、AI Agentが直接接続してiOS Simulatorを制御できます。全てのレスポンスは構造化されたJSON形式で返されます。

設定とオプション

WebDriverAgentポート設定

デフォルトのWebDriverAgentポートは8100ですが、--wda-portオプションで変更可能です：

isc elements find --udid <udid> --using "accessibility id" --value "ButtonID" --wda-port 8101

ファイル出力

スクリーンショット、録画、ページソースなどは、--outputオプションで保存先を指定できます。指定しない場合は、デフォルトの保存場所（~/.isc/以下）に保存されます。

使用例

基本的なiOSアプリテストフロー

# 1. iOS Simulatorを起動
isc simulator boot --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378

# 2. WebDriverAgentを起動
isc wda run --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --path /path/to/WebDriverAgent

# 3. インストール済みアプリの確認
isc app list --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378

# 4. テスト対象アプリを起動
isc app launch --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --bundle-id com.example.testapp

# 5. スクリーンショットを取得
isc screenshot --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --output initial_screen.png

# 6. ログインボタンをタップ
isc elements click --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --using "accessibility id" --value "LoginButton"

# 7. テキストフィールドに入力
isc elements send-keys --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --using "accessibility id" --value "UsernameField" --text "testuser"

# 8. 画面をスワイプ
isc swipe up --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --distance 300

# 9. ページソースを取得して確認
isc elements source --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --output current_state.json

# 10. アプリを終了
isc app terminate --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378 --bundle-id com.example.testapp

# 11. WebDriverAgentを停止
isc wda stop --udid 45A09C64-147D-4BFB-ADE0-AB33DE0BF378

エラー処理

• WebDriverAgentが実行されていない場合、適切なエラーメッセージが表示されます
• 不正なUDIDや存在しない要素を指定した場合も、明確なエラー情報が提供されます
• タイムアウトやネットワークエラーも適切にハンドリングされます

AI Agent統合例

MCPサーバーを使用したAI Agent統合の例：

# 1. MCPサーバーを起動
isc mcp

# 2. AI AgentがMCPプロトコル経由で接続し、以下のような操作が可能:
# - シミュレータの起動: simulator_boot
# - WebDriverAgentの実行: wda_run
# - アプリ管理: app_list → app_launch → app_terminate
# - 要素の検索とクリック: elements_find → elements_click
# - スクリーンショット取得: screenshot
# - ページソース解析: elements_source

AI Agentは全ての操作をJSON形式のリクエスト/レスポンスで実行できます。

技術仕様

• 言語: TypeScript
• ランタイム: Node.js 18+
• 依存: WebDriverAgent, xcrun/simctl, @modelcontextprotocol/sdk
• テスト: Jest (290テストケース)
• アーキテクチャ: Commander.jsベースのCLI、サービス層分離、MCPサーバー統合
• プロトコル: Model Context Protocol (MCP) for AI Agent integration

ライセンス

MIT License

貢献

プルリクエストや Issue の報告を歓迎します。

サポート

バグ報告や機能リクエストは GitHub Issues にてお願いします。