Initial: pi-skill — 68 skills, 43 extensions, 11 themes for Pi
This commit is contained in:
Kunthawat Greethong
260
skills/qa-automation/qa-device-management/SKILL.md
Normal file
260
skills/qa-automation/qa-device-management/SKILL.md
Normal file
@@ -0,0 +1,260 @@
|
||||
---
|
||||
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` |
|
||||
Reference in New Issue
Block a user