agent-mobile

AI-powered mobile app E2E testing CLI with semantic locators and efficient element reference system.

Overview

agent-mobile は AI エージェント向けのモバイルアプリ E2E テストツールです。iOS シミュレータ、Android エミュレータ、実機をサポートし、自然言語に近いセマンティックロケーターと効率的な要素参照システム (@e1, @e2) を提供します。

主な特徴:

• Semantic Locators: テキスト、タイプ、ラベルで UI 要素を検索
• Element References: トークン効率的な @e1 形式の短縮参照
• Cross-Platform: iOS と Android を統一 API でサポート
• Session Management: 永続的な状態管理でマルチデバイスワークフロー対応
• JSON Output: すべてのコマンドで --json オプションをサポート
• Auto-Detection: プラットフォームとデバイスを自動検出

Quick Start

# 1. UI スナップショットを取得（要素参照を生成）
agent-mobile snapshot

# 2. セマンティックロケーターで要素を検索してアクション実行
agent-mobile find text "Login" tap
agent-mobile find label "Email" fill "[email protected]"

# 3. 要素参照を使用（トークン効率的）
agent-mobile tap @e1
agent-mobile fill @e2 "password"

# 4. スクリーンショットで検証
agent-mobile screenshot

Core Concepts

Element References (@e1, @e2)

最も重要な概念: トークン使用量を劇的に削減する短縮 ID システム。

# snapshot を取得すると @e1, @e2, ... が生成される
agent-mobile snapshot
# 出力:
# @e1 Button "Login" (enabled)
# @e2 TextField "Email" (enabled)
# @e3 SecureTextField "Password" (enabled)

# 参照を使用（繰り返しスナップショット不要）
agent-mobile tap @e1
agent-mobile fill @e2 "[email protected]"
agent-mobile fill @e3 "password123"

重要な制約:

• 参照は最後の snapshot に紐づく（画面変更後は無効）
• 画面外の要素は参照できない
• セッションをまたいで永続化しない

詳細: [references/element-references.md](references/element-references.md)

Semantic Locators

UI 要素を人間が理解しやすい方法で検索:

# タイプで検索
agent-mobile find type Button

# テキスト内容で検索（label または value）
agent-mobile find text "Login"

# ラベルで検索
agent-mobile find label "Email"

# プレースホルダーで検索
agent-mobile find placeholder "Enter your email"

# 状態で検索
agent-mobile find enabled
agent-mobile find disabled

位置指定:

• --first (デフォルト): 最初の要素
• --last: 最後の要素
• --nth N: N 番目の要素（0-indexed）
• --all: すべての要素（アクションなし時のみ）

マッチングモード:

• デフォルト: 部分一致（大文字小文字区別なし）
• --exact: 完全一致

詳細: [references/semantic-locators.md](references/semantic-locators.md)

Session Management

複数デバイスで並行作業する際の状態管理:

# セッション作成
agent-mobile session create ios-dev --udid ABC-123 -p ios
agent-mobile session create android-dev --udid emulator-5554 -p android

# セッションを使用
agent-mobile --session ios-dev snapshot
agent-mobile --session android-dev snapshot

# または環境変数で設定
export AGENT_MOBILE_SESSION=ios-dev
agent-mobile snapshot

詳細: [references/session-management.md](references/session-management.md)

Command Reference

Navigation & Interaction

Tap Targets:

• Element reference: @e1, @e2
• Coordinates: 100,200 (x,y)
• Special keys (iOS): home, lock, siri, volumeUp, volumeDown, applePay

Element Discovery

Snapshot Options:

• -i, --interactive: インタラクティブ要素のみ表示
• -c, --compact: 空要素を削除
• -d, --depth N: 階層深さを N に制限
• -o, --output <file>: ファイルに保存
• -f, --format json: JSON 形式で出力
• --no-scroll: スクロール無効化（デフォルトは有効）

Find Locators:

• type <element-type>: 要素タイプで検索 (Button, TextField, etc.)
• text <text>: テキスト内容で検索 (label または value)
• label <label>: ラベルで検索
• placeholder <placeholder>: プレースホルダーで検索
• enabled: 有効な要素
• disabled: 無効な要素

Find Actions:

• tap: タップ
• long-press: 長押し
• fill <text>: クリア + 入力
• clear: クリア

Media & Debugging

Application Management

iOS Permissions: camera, location, contacts, photos, microphone, calendar, reminders, siri, health, homekit, etc.

Android Permissions: camera, location, contacts, calendar, storage, microphone, phone, sms, etc.

Device Management

Session Management

Global Options

すべてのコマンドで使用可能:

Common Workflows

1. Basic Login Flow

# 1. アプリを起動
agent-mobile app launch com.example.app

# 2. UI をスナップショット
agent-mobile snapshot -i  # インタラクティブ要素のみ

# 3. セマンティックロケーターでログイン
agent-mobile find label "Email" fill "[email protected]"
agent-mobile find label "Password" fill "password123"
agent-mobile find text "Login" tap

# 4. 成功を確認
agent-mobile wait @e1 --timeout 5
agent-mobile screenshot -o login_success.png

2. Form Automation with Element References

# 1. スナップショット取得
agent-mobile snapshot > snapshot.txt

# 2. 参照を使用して高速入力
agent-mobile fill @e1 "John"
agent-mobile fill @e2 "Doe"
agent-mobile fill @e3 "[email protected]"
agent-mobile tap @e4  # Submit button

3. Multi-Device Testing

# セッション作成
agent-mobile session create ios16 --udid ABC-123 -p ios
agent-mobile session create android13 --udid emulator-5554 -p android

# 並行実行
agent-mobile --session ios16 app launch com.example.app &
agent-mobile --session android13 app launch com.example.app &

# 同じテストを両方で実行
for session in ios16 android13; do
  agent-mobile --session $session find text "Login" tap
  agent-mobile --session $session screenshot -o ${session}_result.png
done

4. Regression Testing

# ベースラインスナップショット
agent-mobile snapshot -o baseline.json -f json

# ... コード変更後 ...

# 新しいスナップショット
agent-mobile snapshot -o current.json -f json

# 差分比較（外部ツール使用）
diff baseline.json current.json

Future Commands (Planned)

以下のコマンドは現在実装中です（todo.md を参照）:

Priority: High (Phase 1)

• is visible <target> - 可視性判定
• is checked <target> - チェック状態判定
• get count <locator> - マッチング要素数
• get box <target> - バウンディングボックス取得
• wait --text <text> - テキスト出現待機
• wait --timeout <ms> - タイムアウト設定

Priority: Medium (Phase 2)

• check <target> - チェックボックス/スイッチをオン
• uncheck <target> - チェックボックス/スイッチをオフ
• get attr <target> <attribute> - 任意属性取得
• select <target> <value> - Picker/ドロップダウン選択

Priority: Low (Phase 3)

• snapshot -s <selector> - スコープ限定スナップショット

これらのコマンドの詳細な仕様は /Users/r0227n/Dev/agent-mobile/todo.md を参照してください。

Best Practices

Token Efficiency

Always use element references after snapshot:

❌ Bad (繰り返しスナップショット):

agent-mobile snapshot
agent-mobile find text "Email" fill "[email protected]"
agent-mobile snapshot  # 不要！
agent-mobile find text "Password" fill "password"

✅ Good (参照を再利用):

agent-mobile snapshot
# @e1: Email TextField
# @e2: Password SecureTextField
agent-mobile fill @e1 "[email protected]"
agent-mobile fill @e2 "password"

スナップショットのフィルタリング:

# 大きなアプリでは -i (interactive only) を使用
agent-mobile snapshot -i

# さらに -c (compact) と -d (depth) で絞り込み
agent-mobile snapshot -i -c -d 3

Reliability

明示的な待機を使用:

# アニメーション後に待機
agent-mobile tap @e1
sleep 1  # または wait コマンド
agent-mobile screenshot

エラーハンドリング:

# is コマンドの exit code を使用
if agent-mobile is @e1 enabled; then
  agent-mobile tap @e1
else
  echo "Button is disabled"
fi

Debugging

スナップショットを保存して分析:

agent-mobile snapshot -o debug.json -f json
agent-mobile snapshot -o debug.txt

スクリーンショットで証跡を残す:

agent-mobile screenshot -o before.png
agent-mobile tap @e1
agent-mobile screenshot -o after.png

コンソールログを監視:

agent-mobile console --level error &
# テスト実行...

AI Agent Optimization

JSON 出力を活用:

# プログラムで解析可能な出力
devices=$(agent-mobile device list -f json)
echo "$devices" | jq -r '.[0].udid'

セッションで状態を永続化:

# セッションは最後のスナップショットを保存
export AGENT_MOBILE_SESSION=test
agent-mobile snapshot  # 保存される
agent-mobile tap @e1   # セッションから参照を解決

エラーメッセージを読む:

agent-mobile find text "NonExistent" tap
# エラー: "No elements found matching text containing "NonExistent"
# Hint: Run 'agent-mobile snapshot' to see the current UI state."

Platform-Specific Notes

iOS

• Implementation: XCUITest Runner (HTTP) + xcrun simctl (ライフサイクル管理)
• Device Types: Simulator
• Advantages: アクセシビリティ API、スクリーンショット、クリップボード、HID入力
• Limitations: 一部機能はシミュレータのみ

Android

• Implementation: adb (Android Debug Bridge)
• Device Types: Emulator, Physical Device
• Advantages: 追加セットアップ不要、USB デバッグのみ
• Limitations: クリップボード API 非対応、一部機能制限あり

詳細: [references/platform-differences.md](references/platform-differences.md)

Error Handling

Common Errors

"No Image available to encode"

• 原因: スクリーンショット取得時にアプリが起動していない
• 解決: agent-mobile app launch <bundle-id> でアプリを起動

"No elements found matching..."

• 原因: セマンティックロケーターがマッチしない
• 解決: agent-mobile snapshot で UI 状態を確認

"Element ref @e1 not found"

• 原因: スナップショット取得後に画面が変更された
• 解決: agent-mobile snapshot で再取得

"Session 'xxx' not found"

• 原因: セッションが作成されていない
• 解決: agent-mobile session create xxx --udid ...

詳細: [references/troubleshooting.md](references/troubleshooting.md)

Examples

Complete Login Test

#!/bin/bash
set -e

# Setup
BUNDLE_ID="com.example.app"
agent-mobile app launch $BUNDLE_ID

# Wait for app to load
sleep 2

# Capture UI
agent-mobile snapshot -i -o login_screen.txt

# Login
agent-mobile find label "Email" fill "[email protected]"
agent-mobile find label "Password" fill "password123"
agent-mobile find text "Login" tap

# Wait for next screen
sleep 2
agent-mobile wait @e1 --timeout 10

# Verify
agent-mobile screenshot -o logged_in.png
echo "Login successful"

Form Submission with Validation

#!/bin/bash

# Take snapshot
agent-mobile snapshot > /tmp/form.txt

# Extract refs
EMAIL_REF=$(grep "Email" /tmp/form.txt | grep -o "@e[0-9]*" | head -1)
PASSWORD_REF=$(grep "Password" /tmp/form.txt | grep -o "@e[0-9]*" | head -1)
SUBMIT_REF=$(grep "Submit" /tmp/form.txt | grep -o "@e[0-9]*" | head -1)

# Fill form
agent-mobile fill $EMAIL_REF "[email protected]"
agent-mobile fill $PASSWORD_REF "securepass123"

# Check if submit button is enabled
if agent-mobile is $SUBMIT_REF enabled; then
  agent-mobile tap $SUBMIT_REF
  echo "Form submitted"
else
  echo "Submit button is disabled"
  exit 1
fi

References

• [Semantic Locators](references/semantic-locators.md) - 詳細な検索パターンとマッチングルール
• [Element References](references/element-references.md) - @e1 参照システムの完全ガイド
• [Session Management](references/session-management.md) - マルチデバイスワークフローのベストプラクティス
• [Platform Differences](references/platform-differences.md) - iOS vs Android の実装詳細
• [Troubleshooting](references/troubleshooting.md) - 一般的な問題と解決策

Templates

• [Login Workflow](templates/login-workflow.sh) - 基本的なログインフロー
• [Form Automation](templates/form-automation.sh) - 複雑なフォーム自動化
• [UI Exploration](templates/ui-exploration.sh) - UI 探索スクリプト
• [Multi-Device Test](templates/multi-device-test.sh) - iOS/Android 並行テスト
• [Regression Test](templates/regression-test.sh) - リグレッションテスト

Additional Resources

• Project Repository: /Users/r0227n/Dev/agent-mobile
• Architecture Documentation: /Users/r0227n/Dev/agent-mobile/docs/ARCHITECTURE.md
• Implementation Guide: /Users/r0227n/Dev/agent-mobile/CLAUDE.md
• Feature Roadmap: /Users/r0227n/Dev/agent-mobile/todo.md
• Known Issues: /Users/r0227n/Dev/agent-mobile/docs/KNOWN_ISSUES.md (if exists)

Version: 1.0.0 Last Updated: 2026-01-23 Maintained by: Claude Code (Anthropic)