ios-simulator-skill

iOS Simulator Skill

ピクセル座標ではなく、アクセシビリティに基づくナビゲーションと構造化データを使用して、iOS アプリケーションのビルド、テスト、自動化を行います。

クイックスタート

# 1. Check environment
bash scripts/sim_health_check.sh

# 2. Launch app
python scripts/app_launcher.py --launch com.example.app

# 3. Map screen to see elements
python scripts/screen_mapper.py

# 4. Tap button
python scripts/navigator.py --find-text "Login" --tap

# 5. Enter text
python scripts/navigator.py --find-type TextField --enter-text "[email protected]"

すべてのスクリプトで、詳細なオプションを表示する --help と、機械可読形式で出力する --json を利用できます。

本番環境向けスクリプト 21 本

ビルドと開発（2 本）

1. build_and_test.py - Xcode プロジェクトをビルドしてテストを実行し、段階的な情報開示によって結果を解析します

   • ビルド結果をリアルタイムでストリーミング
   • xcresult バンドルからエラーと警告を解析
   • 必要に応じて詳細なビルドログを取得
   • オプション：--project、--scheme、--clean、--test、--verbose、--json

2. log_monitor.py - インテリジェントなフィルタリングによるリアルタイムのログ監視

   • ログをストリーミング、または指定時間分を取得
   • 重大度（error/warning/info/debug）でフィルタリング
   • 繰り返されるメッセージを重複排除
   • オプション：--app、--severity、--follow、--duration、--output、--json

ナビゲーションと操作（5 本）

3. screen_mapper.py - 現在の画面を分析し、操作可能な要素を一覧表示

   • 要素タイプの内訳
   • 操作可能なボタンの一覧
   • テキストフィールドの状態
   • オプション：--verbose、--hints、--json

4. navigator.py - 要素を意味的に検索して操作

   • テキストで検索（あいまい一致）
   • 要素タイプで検索
   • アクセシビリティ ID で検索
   • テキストを入力、または要素をタップ
   • オプション：--find-text、--find-type、--find-id、--tap、--enter-text、--json

5. gesture.py - スワイプ、スクロール、ピンチ、複雑なジェスチャーを実行

   • 方向を指定したスワイプ（上／下／左／右）
   • 複数回のスワイプによるスクロール
   • ピンチによるズーム
   • 長押し
   • 引っ張って更新
   • オプション：--swipe、--scroll、--pinch、--long-press、--refresh、--json

6. keyboard.py - テキスト入力とハードウェアボタンの操作

   • テキストを入力（高速または低速）
   • 特殊キー（return、delete、tab、space、矢印）
   • ハードウェアボタン（ホーム、ロック、音量、スクリーンショット）
   • キーの組み合わせ
   • オプション：--type、--key、--button、--slow、--clear、--dismiss、--json

7. app_launcher.py - アプリのライフサイクル管理

   • バンドル ID でアプリを起動
   • アプリを終了
   • .app バンドルからインストール／アンインストール
   • ディープリンクによるナビゲーション
   • インストール済みアプリを一覧表示
   • アプリの状態を確認
   • オプション：--launch、--terminate、--install、--uninstall、--open-url、--list、--state、--json

テストと分析（5 本）

8. accessibility_audit.py - 現在の画面の WCAG 準拠状況を確認

   • 重大な問題（ラベルの欠落、空のボタン、代替テキストなし）
   • 警告（ヒントの欠落、小さなタッチターゲット）
   • 情報（ID の欠落、深いネスト）
   • オプション：--verbose、--output、--json

9. visual_diff.py - 2 枚のスクリーンショットを比較し、視覚的な変化を検出

   • ピクセル単位で比較
   • しきい値に基づく合格／不合格判定
   • 差分画像を生成
   • オプション：--threshold、--output、--details、--json

10. test_recorder.py - テストの実行を自動的に記録

    • 各ステップでスクリーンショットとアクセシビリティツリーを取得
    • 時間データを含む Markdown レポートを生成
    • オプション：--test-name、--output、--verbose、--json

11. app_state_capture.py - 包括的なデバッグ用スナップショットを作成

    • スクリーンショット、UI 階層、アプリログ、デバイス情報
    • バグ報告用の Markdown サマリー
    • オプション：--app-bundle-id、--output、--log-lines、--json

12. sim_health_check.sh - 環境が適切に設定されていることを確認

    • macOS、Xcode、simctl、IDB、Python を確認
    • 利用可能なシミュレーターと起動済みのシミュレーターを一覧表示
    • Python パッケージ（Pillow）を確認

高度なテストと権限（4 スクリプト）

13. clipboard.py - ペーストテスト用にシミュレーターのクリップボードを管理します

    • テキストをクリップボードにコピーします
    • 手動入力なしでペーストの流れをテストします
    • オプション：--copy、--test-name、--expected、--json

14. status_bar.py - シミュレーターのステータスバーの表示を変更します

    • プリセット：clean（9:41、バッテリー 100%）、testing（11:11、50%）、low-battery（20%）、airplane（オフライン）
    • 時刻、ネットワーク、バッテリー、WiFi の設定をカスタマイズできます
    • オプション：--preset、--time、--data-network、--battery-level、--clear、--json

15. push_notification.py - シミュレートされたプッシュ通知を送信します

    • シンプルモード（タイトル＋本文＋バッジ）
    • カスタム JSON ペイロード
    • 通知処理とディープリンクをテストします
    • オプション：--bundle-id、--title、--body、--badge、--payload、--json

16. privacy_manager.py - アプリの権限を付与、取り消し、リセットします

    • 13 のサービスに対応（カメラ、マイク、位置情報、連絡先、写真、カレンダー、ヘルスケアなど）
    • 一括操作（サービスをカンマ区切りで指定）
    • テストシナリオの追跡を含む監査証跡
    • オプション：--bundle-id、--grant、--revoke、--reset、--list、--json

デバイスのライフサイクル管理（5 スクリプト）

17. simctl_boot.py - 準備完了の確認を任意で行い、シミュレーターを起動します

    • UDID またはデバイス名で起動します
    • タイムアウトを指定して、デバイスの準備が整うまで待機します
    • 一括起動操作（--all、--type）
    • パフォーマンス計測
    • オプション：--udid、--name、--wait-ready、--timeout、--all、--type、--json

18. simctl_shutdown.py - シミュレーターを正常にシャットダウンします

    • UDID またはデバイス名でシャットダウンします
    • シャットダウン完了の確認は任意です
    • 一括シャットダウン操作
    • オプション：--udid、--name、--verify、--timeout、--all、--type、--json

19. simctl_create.py - シミュレーターを動的に作成します

    • デバイスの種類と iOS バージョンを指定して作成します
    • 利用可能なデバイスの種類とランタイムを一覧表示します
    • デバイス名をカスタマイズできます
    • CI/CD 連携用に UDID を返します
    • オプション：--device、--runtime、--name、--list-devices、--list-runtimes、--json

20. simctl_delete.py - シミュレーターを完全に削除します

    • UDID またはデバイス名で削除します
    • デフォルトでは安全確認を行います（--yes で省略）
    • 一括削除操作
    • スマート削除（--old N でデバイスの種類ごとに N 台を保持）
    • オプション：--udid、--name、--yes、--all、--type、--old、--json

21. simctl_erase.py - シミュレーターを削除せずに工場出荷時の状態にリセットします

    • デバイス UUID を保持します（削除して再作成するより高速）
    • すべて、種類別、または起動中のシミュレーターを消去します
    • 確認は任意です
    • オプション：--udid、--name、--verify、--timeout、--all、--type、--booted、--json

共通パターン

UDID の自動検出：ほとんどのスクリプトは、--udid が指定されていない場合、起動中のシミュレーターを自動検出します。

デバイス名の解決：UDID の代わりにデバイス名（例：「iPhone 16 Pro」）を使用すると、スクリプトが自動的に解決します。

一括操作：多くのスクリプトは、すべてのシミュレーターを対象にする --all や、デバイスの種類で絞り込む --type iPhone に対応しています。

出力形式：デフォルトでは、簡潔で人が読みやすい形式で出力します。CI/CD で機械可読形式を使うには、--json を指定します。

ヘルプ：すべてのスクリプトで --help を指定すると、詳細なオプションと使用例を確認できます。

一般的なワークフロー

1. 環境を確認します：bash scripts/sim_health_check.sh
2. アプリを起動します：python scripts/app_launcher.py --launch com.example.app
3. 画面を分析します：python scripts/screen_mapper.py
4. 操作します：python scripts/navigator.py --find-text "Button" --tap
5. 確認します：python scripts/accessibility_audit.py
6. 必要に応じてデバッグします：python scripts/app_state_capture.py --app-bundle-id com.example.app

要件

• macOS 12 以降
• Xcode Command Line Tools
• Python 3
• IDB（任意、インタラクティブ機能用）

ドキュメント

• SKILL.md（このファイル） - スクリプトのリファレンスとクイックスタート
• README.md - インストールと使用例
• CLAUDE.md - アーキテクチャと実装の詳細
• references/ - 特定のトピックに関する詳細なドキュメント
• examples/ - 完全な自動化ワークフロー

主な設計原則

セマンティックナビゲーション：ピクセル座標ではなく、意味（テキスト、種類、ID）で要素を検索します。UI の変更にも対応できます。

トークン効率：デフォルトでは簡潔な出力（3～5 行）を返し、詳細な結果を得るための任意の詳細モードと JSON モードを備えています。

アクセシビリティ優先：信頼性と互換性を確保するため、標準のアクセシビリティ API を基盤としています。

設定不要：Xcode があれば、あらゆる macOS ですぐに動作します。セットアップは不要です。

構造化データ：スクリプトは生のログではなく、JSON または書式設定済みのテキストを出力します。解析や統合が容易です。

自動学習：ビルドシステムがデバイスの設定を記憶します。設定はプロジェクトごとに保存されます。

---

これらのスクリプトを直接使用するか、リクエストがスキルの説明に合致した場合に Claude Code が自動的に呼び出すようにします。