261 lines
6.3 KiB
Markdown
261 lines
6.3 KiB
Markdown
---
|
|
name: qa-device-management
|
|
description: >
|
|
Boot and control iOS Simulators and Android Emulators for QA testing using agent-device CLI.
|
|
Manage sessions, capture screenshots, launch apps, and control devices across platforms.
|
|
Invoke when user says "bring up simulators", "boot the device", "take a screenshot",
|
|
"launch the app", "compare iOS and Android", "test both platforms", "visual parity check",
|
|
or any task requiring device/simulator lifecycle management.
|
|
allowed-tools: Bash(agent-device:*) Bash(xcrun:*) Bash(adb:*) Bash(open:*) Bash(find:*) Bash(npx:*) Read
|
|
---
|
|
|
|
# qa-device-management
|
|
|
|
Side-by-side iOS Simulator and Android Emulator control using the `agent-device` CLI. Manages the device lifecycle for all QA Automation skills.
|
|
|
|
## When to Use
|
|
|
|
- Bringing up simulators/emulators for testing
|
|
- Launching your app on one or both platforms
|
|
- Capturing baseline or comparison screenshots
|
|
- Checking device state, app state, or accessibility tree
|
|
- Managing agent-device sessions across platforms
|
|
|
|
## Configuration
|
|
|
|
All device settings are in `qa.config.sh`. Set these before using:
|
|
|
|
```bash
|
|
# In qa.config.sh or qa.config.local.sh:
|
|
export APP_BUNDLE_ID="com.yourapp.dev" # Your app's bundle/package ID
|
|
export SIMULATOR_UDID="auto" # "auto" or specific UDID
|
|
export SIMULATOR_DEVICE_NAME="iPhone 16 Pro" # For creating simulators
|
|
export ANDROID_AVD="Pixel_8" # Android AVD name
|
|
export ANDROID_SERIAL="emulator-5554" # Android serial
|
|
```
|
|
|
|
## Quick Start — Full Startup Sequence
|
|
|
|
### Boot iOS Simulator
|
|
|
|
```bash
|
|
# Auto-detect a booted simulator, or boot one
|
|
source .pi/skills/qa-automation/qa.config.sh
|
|
UDID=$(qa_detect_simulator_udid)
|
|
|
|
# Or boot a specific one
|
|
xcrun simctl boot "$SIMULATOR_UDID" 2>&1 || true
|
|
open -a Simulator
|
|
```
|
|
|
|
### Boot Android Emulator
|
|
|
|
```bash
|
|
nohup $EMULATOR_PATH -avd "$ANDROID_AVD" -no-snapshot-load > /tmp/qa-emu.log 2>&1 &
|
|
|
|
# Wait for boot
|
|
for i in $(seq 1 30); do
|
|
BOOT=$($ADB_PATH shell getprop sys.boot_completed 2>/dev/null | tr -d '\r')
|
|
if [ "$BOOT" = "1" ]; then
|
|
echo "Android emulator booted after ~$((i*2))s"
|
|
break
|
|
fi
|
|
sleep 2
|
|
done
|
|
```
|
|
|
|
### Verify Both Devices
|
|
|
|
```bash
|
|
agent-device devices --json
|
|
```
|
|
|
|
### Launch App on iOS
|
|
|
|
```bash
|
|
agent-device open "$APP_BUNDLE_ID" --platform ios --session default
|
|
```
|
|
|
|
### Launch App on Android
|
|
|
|
```bash
|
|
agent-device open "$APP_BUNDLE_ID" --platform android --serial "$ANDROID_SERIAL" --session android
|
|
```
|
|
|
|
### Capture Baseline Screenshots
|
|
|
|
```bash
|
|
agent-device screenshot /tmp/qa-ios-baseline.png --session default
|
|
agent-device screenshot /tmp/qa-android-baseline.png --session android
|
|
```
|
|
|
|
## Session Management
|
|
|
|
agent-device binds each session to one platform. Use the correct session flag:
|
|
|
|
| Platform | Session Flag | Example |
|
|
|----------|-------------|---------|
|
|
| iOS | `--session default` (or omit) | `agent-device snapshot --session default` |
|
|
| Android | `--session android` | `agent-device snapshot --session android` |
|
|
|
|
```bash
|
|
# List active sessions
|
|
agent-device session list
|
|
|
|
# Release a session
|
|
agent-device close --session default
|
|
```
|
|
|
|
## Common Operations
|
|
|
|
### Screenshots (Both Platforms)
|
|
|
|
```bash
|
|
agent-device screenshot /tmp/qa-ios.png --session default
|
|
agent-device screenshot /tmp/qa-android.png --session android
|
|
```
|
|
|
|
### Accessibility Snapshots
|
|
|
|
```bash
|
|
agent-device snapshot --session default # iOS
|
|
agent-device snapshot --session android # Android
|
|
|
|
# With options
|
|
agent-device snapshot -i --session default # Interactive elements only
|
|
agent-device snapshot --depth 3 # Limit depth
|
|
```
|
|
|
|
### Navigate and Interact
|
|
|
|
```bash
|
|
# Tap
|
|
agent-device click 200 400 --session default
|
|
|
|
# Swipe
|
|
agent-device swipe 200 800 200 200 --session default
|
|
|
|
# Scroll
|
|
agent-device scroll down --session default
|
|
|
|
# Type
|
|
agent-device fill @e3 "hello world" --session default
|
|
```
|
|
|
|
### Go Home / Go Back
|
|
|
|
```bash
|
|
agent-device home --session default
|
|
agent-device back --session android
|
|
```
|
|
|
|
### Check Foreground App
|
|
|
|
```bash
|
|
agent-device appstate --session default
|
|
agent-device appstate --session android
|
|
```
|
|
|
|
### Relaunch App (Fresh State)
|
|
|
|
```bash
|
|
agent-device open "$APP_BUNDLE_ID" --session default --relaunch
|
|
```
|
|
|
|
## Building and Installing Your App
|
|
|
|
### iOS — Expo
|
|
|
|
```bash
|
|
cd "$PROJECT_DIR"
|
|
npx expo run:ios --device "$SIMULATOR_DEVICE_NAME"
|
|
```
|
|
|
|
### iOS — React Native CLI
|
|
|
|
```bash
|
|
cd "$PROJECT_DIR"
|
|
npx react-native run-ios --simulator "$SIMULATOR_DEVICE_NAME"
|
|
```
|
|
|
|
### Android — Expo
|
|
|
|
```bash
|
|
cd "$PROJECT_DIR"
|
|
npx expo run:android
|
|
```
|
|
|
|
### Android — React Native CLI
|
|
|
|
```bash
|
|
cd "$PROJECT_DIR"
|
|
npx react-native run-android
|
|
```
|
|
|
|
### Check If App Is Installed
|
|
|
|
```bash
|
|
# iOS
|
|
xcrun simctl listapps booted 2>/dev/null | grep "$APP_BUNDLE_ID"
|
|
|
|
# Android
|
|
$ADB_PATH shell pm list packages | grep "$APP_BUNDLE_ID"
|
|
```
|
|
|
|
## Shutdown Sequence
|
|
|
|
```bash
|
|
# Close agent-device sessions
|
|
agent-device close --session default
|
|
agent-device close --session android
|
|
|
|
# Shutdown simulators
|
|
xcrun simctl shutdown "$SIMULATOR_UDID"
|
|
$ADB_PATH emu kill
|
|
```
|
|
|
|
## CDP Connection (for React Native apps)
|
|
|
|
When coordinate-based tapping fails (e.g., full-screen video players intercept touches), use CDP to control navigation directly via the React Native Hermes runtime.
|
|
|
|
### Prerequisites
|
|
- Dev server running (e.g., `npx expo start`)
|
|
- `ws` npm package available
|
|
|
|
### Discover CDP Endpoints
|
|
|
|
```bash
|
|
# List available debug targets
|
|
curl -s http://localhost:$METRO_PORT/json
|
|
|
|
# Get WebSocket URL (auto-detected by qa.config.sh)
|
|
source qa.config.sh
|
|
qa_detect_cdp_ws_url
|
|
```
|
|
|
|
### Navigate via CDP
|
|
|
|
```bash
|
|
source .pi/skills/qa-automation/qa-test-flows/lib/cdp-helpers.sh
|
|
|
|
# Navigate to a screen
|
|
cdp_navigate "SettingsScreen"
|
|
|
|
# Navigate to a tab
|
|
cdp_navigate_tab "ProfileScreen"
|
|
|
|
# Get current route
|
|
cdp_get_route
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Solution |
|
|
|---------|----------|
|
|
| "No device found" | Verify simulator is booted: `xcrun simctl list devices \| grep Booted` |
|
|
| Session bound to wrong platform | Use `--session android` for Android, close session and rebind |
|
|
| Simulator already booted (error 149) | Safe to ignore — simulator is already running |
|
|
| App not installed | Build and install: `npx expo run:ios` or `npx expo run:android` |
|
|
| agent-device click hangs | Wrap with timeout: `timeout 5 agent-device click 100 200` |
|
|
| CDP "Connection refused" | Ensure dev server is running: `curl http://localhost:$METRO_PORT/status` |
|