iOS Simulator Skill

アクセシビリティドリブンなナビゲーションと構造化データを使用して、ピクセル座標の代わりに iOS アプリケーションをビルド、テスト、自動化します。

クイックスタート

# 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 "Login" --tap

# 5. テキストを入力
python scripts/navigator.py --find-type TextField --enter-text "user@example.com"

すべてのスクリプトは詳細なオプション用に --help と、マシン可読出力用に --json をサポートしています。

ナビゲーション戦略

ナビゲーションではスクリーンショットよりアクセシビリティツリーを常に優先してください。 アクセシビリティツリーは要素タイプ、ラベル、フレーム、タップ対象などの構造化データを提供し、画像解析よりも安価で信頼性が高いです。

優先順位を以下のように使用してください:

1. screen_mapper.py → 構造化された要素リスト (5-7 行、約 10 トークン)
2. navigator.py --find-text/--find-type/--find-id → セマンティック相互作用
3. スクリーンショット → ビジュアル確認、バグレポート、ビジュアル差分のみ

スクリーンショットはサイズに応じて 1,600～6,300 トークンのコストがかかります。アクセシビリティツリーはデフォルトモードで 10～50 トークンのコストです。

22 個の本番用スクリプト

ビルド・開発 (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 - テキスト入力とハードウェアボタンコントロール

   • テキスト入力 (高速または低速)
   • 特殊キー (リターン、削除、タブ、スペース、矢印)
   • ハードウェアボタン (ホーム、ロック、ボリューム、スクリーンショット)
   • キーの組み合わせ
   • オプション: --type, --key, --button, --slow, --clear, --dismiss, --json

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

   • バンドル ID でアプリを起動
   • アプリを終了
   • .app バンドルからインストール/アンインストール
   • ディープリンク遷移
   • インストール済みアプリをリストアップ
   • アプリ状態を確認
   • オプション: --launch, --terminate, --install, --uninstall, --open-url, --list, --state, --json

テスト・分析 (6 スクリプト)

8. accessibility_audit.py - 現在のスクリーンの WCAG コンプライアンスをチェック

   • 重大問題 (ラベル欠落、空ボタン、代替テキストなし)
   • 警告 (ヒント欠落、タッチ対象が小さい)
   • 情報 (ID 欠落、ネストが深い)
   • オプション: --verbose, --output, --json

9. visual_diff.py - 2 つのスクリーンショットを比較してビジュアル変更を検出

   • ピクセル単位の比較
   • 閾値ベースのパス/フェイル
   • 差分画像を生成
   • オプション: --threshold, --output, --details, --json

10. test_recorder.py - テスト実行を自動的にドキュメント化

    • ステップごとにスクリーンショットとアクセシビリティツリーをキャプチャ
    • タイミングデータ付きマークダウンレポートを生成
    • オプション: --test-name, --output, --verbose, --json

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

    • スクリーンショット、UI 階層、アプリログ、デバイス情報
    • バグレポート用マークダウンサマリー
    • オプション: --app-bundle-id, --output, --log-lines, --json

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

    • macOS、Xcode、simctl、IDB、Python をチェック
    • 利用可能およびブートされたシミュレータをリストアップ
    • Python パッケージ (Pillow) を確認

13. model_inspector.py - プロジェクトファイルから Core Data と SwiftData モデルを検査

    • .xcdatamodeld パッケージを解析 (エンティティ、属性、リレーションシップ)
    • モデルバージョンと現在のアクティブバージョンを検出
    • SwiftData @Model クラスの最善の抽出
    • 任意のモデルについてのオンデマンド生ソースダンプ (--raw ModelName)
    • オプション: --project-path, --core-data-only, --swiftdata-only, --show-versions, --raw, --verbose, --json

高度なテスト・パーミッション (4 スクリプト)

14. clipboard.py - ペーストテスト用シミュレータクリップボード管理

    • テキストをクリップボードにコピー
    • 手動入力なしでペーストフローをテスト
    • オプション: --copy, --test-name, --expected, --json

15. status_bar.py - シミュレータステータスバーの外観をオーバーライド

    • プリセット: clean (9:41, 100% バッテリー)、testing (11:11, 50%)、low-battery (20%)、airplane (オフライン)
    • カスタム時刻、ネットワーク、バッテリー、WiFi 設定
    • オプション: --preset, --time, --data-network, --battery-level, --clear, --json

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

    • シンプルモード (タイトル + 本文 + バッジ)
    • カスタム JSON ペイロード
    • 通知処理とディープリンクをテスト
    • オプション: --bundle-id, --title, --body, --badge, --payload, --json

17. privacy_manager.py - アプリパーミッションを許可、取り消し、リセット

    • 13 個のサポートされたサービス (カメラ、マイク、位置情報、連絡先、写真、カレンダー、ヘルス等)
    • バッチ操作 (カンマ区切りサービス)
    • テストシナリオ追跡付き監査証跡
    • オプション: --bundle-id, --grant, --revoke, --reset, --list, --json

デバイスライフサイクル管理 (5 スクリプト)

18. simctl_boot.py - オプションの準備状態確認付きでシミュレータをブート

    • UDID またはデバイス名でブート
    • タイムアウト付きでデバイス準備完了を待機
    • バッチブート操作 (--all, --type)
    • パフォーマンスタイミング
    • オプション: --udid, --name, --wait-ready, --timeout, --all, --type, --json

19. simctl_shutdown.py - シミュレータをグレースフルシャットダウン

    • UDID またはデバイス名でシャットダウン
    • シャットダウン完了の検証オプション
    • バッチシャットダウン操作
    • オプション: --udid, --name, --verify, --timeout, --all, --type, --json

20. simctl_create.py - 動的にシミュレータを作成

    • デバイスタイプと iOS バージョンで作成
    • 利用可能なデバイスタイプとランタイムをリストアップ
    • カスタムデバイス命名
    • CI/CD 統合用に UDID を返却
    • オプション: --device, --runtime, --name, --list-devices, --list-runtimes, --json

21. simctl_delete.py - シミュレータを永続的に削除

    • UDID またはデバイス名で削除
    • デフォルトで安全確認 (--yes でスキップ)
    • バッチ削除操作
    • スマート削除 (--old N でデバイスタイプごとに N 個保持)
    • オプション: --udid, --name, --yes, --all, --type, --old, --json

22. 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 をサポートしています。

スクリーンショットサイジング: トークンを節約するためスクリーンショットはリサイズされます。プリセット: full (3-4 タイル、約 5K トークン)、half (1 タイル、約 1.6K トークン、デフォルト)、quarter (1 タイル、約 800 トークン、詳細度低)。クイックビジュアルチェックには quarter、読みやすい UI には half、ピクセルレベルの詳細が必要な場合のみ full を使用してください。スクリーンショットをキャプチャするスクリプト (app_state_capture.py, test_recorder.py) はデフォルトで half です。

典型的なワークフロー

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 で自動的に呼び出させることができます。