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 にてお願いします。

Name		Name	Last commit message	Last commit date
Latest commit History 28 Commits
.claude		.claude
.github/workflows		.github/workflows
docs		docs
src		src
tests		tests
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
README.md		README.md
jest.config.js		jest.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

henteko/isc

Folders and files

Latest commit

History

Repository files navigation