178 lines
6.2 KiB
Markdown
178 lines
6.2 KiB
Markdown
---
|
|
name: qa-test-flows
|
|
description: >
|
|
Automated UI test flow framework using CDP + agent-device for native apps and
|
|
agent-browser for web apps. Zero-framework approach — bash scripts orchestrate
|
|
simulators with no Detox, Maestro, or Appium dependencies. Provides test lifecycle,
|
|
screenshot capture, assertion helpers, and JSON report generation.
|
|
Invoke when user says "run tests", "test the app", "smoke test", "regression test",
|
|
"verify flows", "run e2e tests", or any task requiring automated UI testing.
|
|
allowed-tools: Bash(agent-device:*) Bash(agent-browser:*) Bash(xcrun:*) Bash(adb:*) Bash(open:*) Bash(find:*) Bash(npx:*) Bash(node:*) Read
|
|
---
|
|
|
|
# qa-test-flows
|
|
|
|
Automated UI test flow framework using a **dual-driver architecture**: **CDP** for navigation/state control and **agent-device** for screenshots/visual assertions in native apps, plus **agent-browser** for web app testing. This is a zero-framework approach — bash scripts orchestrate the entire test lifecycle with no Detox, Maestro, or Appium dependencies.
|
|
|
|
## Key Innovation: CDP + agent-device + agent-browser
|
|
|
|
Native mobile apps with complex gesture handlers (full-screen video players, swipe-based feeds) often make coordinate-based tapping unreliable. We solve this by connecting directly to the React Native Hermes runtime via Metro's CDP WebSocket, giving us:
|
|
|
|
- **Direct navigation control** via `navigationRef.current.navigate()` — no touch coordinates needed
|
|
- **Runtime state inspection** — check current route, user state, storage
|
|
- **Module access** via Metro's `__r()` require — load any app module at runtime
|
|
- **Screenshots & visual verification** via agent-device (best-in-class for simulators)
|
|
- **Web app testing** via agent-browser when the same app has a web version
|
|
|
|
## When to Use
|
|
|
|
- Smoke testing before submission or release builds
|
|
- Regression testing after navigation or feature changes
|
|
- Flow verification (auth, navigation, data entry, checkout)
|
|
- Platform parity checks (iOS vs Android)
|
|
- Pre-PR validation of multi-screen flows
|
|
- State persistence verification
|
|
|
|
## Test Architecture
|
|
|
|
### Dual Driver System
|
|
|
|
| Driver | Purpose | Use For |
|
|
|--------|---------|---------|
|
|
| **CDP (WebSocket)** | Navigation, state queries, JS execution | React Native apps (Hermes runtime) |
|
|
| **agent-device** | Screenshots, coordinate taps, swipes, accessibility | Native app simulators/emulators |
|
|
| **agent-browser** | Full browser automation, DOM interaction | Web apps, PWAs, browser testing |
|
|
|
|
### Test Flow Format
|
|
|
|
All test flows follow a consistent bash template:
|
|
|
|
```bash
|
|
#!/bin/bash
|
|
source "$(dirname "$0")/../../lib/test-helpers.sh"
|
|
source "$(dirname "$0")/../../lib/cdp-helpers.sh"
|
|
|
|
TEST_NAME="my-flow"
|
|
setup_test "$TEST_NAME"
|
|
|
|
# Step 1: Navigate
|
|
step "Navigate to target screen"
|
|
cdp_navigate "TargetScreen"
|
|
sleep 2
|
|
take_screenshot "01-target-screen"
|
|
assert_screenshot "01-target-screen"
|
|
|
|
# Step 2: Interact
|
|
step "Perform action"
|
|
tap 200 400
|
|
sleep 1
|
|
take_screenshot "02-after-action"
|
|
|
|
# Step 3: Verify
|
|
step "Verify result"
|
|
route=$(cdp_get_route)
|
|
log_info "Route: $route"
|
|
|
|
teardown_test
|
|
```
|
|
|
|
## Running Tests
|
|
|
|
### Single Test
|
|
```bash
|
|
bash .pi/skills/qa-automation/qa-test-flows/flows/smoke/example-smoke.sh
|
|
```
|
|
|
|
### All Tests
|
|
```bash
|
|
bash .pi/skills/qa-automation/qa-test-flows/run-all.sh
|
|
```
|
|
|
|
### With Logging
|
|
```bash
|
|
bash .pi/skills/qa-automation/qa-test-flows/flows/smoke/example-smoke.sh 2>&1 | tee /tmp/smoke.log
|
|
```
|
|
|
|
## Writing New Tests
|
|
|
|
### 1. Copy the template
|
|
```bash
|
|
cp .pi/skills/qa-automation/qa-test-flows/templates/new-flow.sh.template \
|
|
.pi/skills/qa-automation/qa-test-flows/flows/my-suite/my-test.sh
|
|
chmod +x .pi/skills/qa-automation/qa-test-flows/flows/my-suite/my-test.sh
|
|
```
|
|
|
|
### 2. Edit the template
|
|
Replace `CUSTOMIZE` markers with your app-specific details.
|
|
|
|
### 3. Find coordinates
|
|
```bash
|
|
agent-device screenshot /tmp/debug.png
|
|
open /tmp/debug.png # Measure tap targets
|
|
```
|
|
|
|
### 4. Run and verify
|
|
```bash
|
|
bash .pi/skills/qa-automation/qa-test-flows/flows/my-suite/my-test.sh
|
|
ls /tmp/qa-tests/screenshots/my-test/
|
|
```
|
|
|
|
## Helper Libraries
|
|
|
|
### test-helpers.sh
|
|
|
|
| Function | Purpose |
|
|
|----------|---------|
|
|
| `setup_test "name"` | Initialize test, create directories |
|
|
| `teardown_test` | Report results, cleanup |
|
|
| `step "description"` | Log a numbered test step |
|
|
| `log_pass/fail/info/warn` | Status logging |
|
|
| `take_screenshot "name"` | Capture screenshot |
|
|
| `tap x y` | Tap at coordinates |
|
|
| `swipe x1 y1 x2 y2` | Swipe gesture |
|
|
| `scroll_dir direction` | Scroll up/down/left/right |
|
|
| `assert_app_foreground` | Verify app is running |
|
|
| `assert_screenshot "name"` | Verify screenshot exists |
|
|
| `assert_text_visible "text"` | Check accessibility tree |
|
|
| `launch_app` | Launch/relaunch the app |
|
|
| `close_app` | Terminate the app |
|
|
|
|
### cdp-helpers.sh
|
|
|
|
| Function | Purpose |
|
|
|----------|---------|
|
|
| `cdp_eval "expression"` | Execute JS in Hermes |
|
|
| `cdp_eval_safe "expression"` | Eval with ErrorUtils suppression |
|
|
| `cdp_navigate "Screen"` | Navigate to screen |
|
|
| `cdp_navigate_tab "TabScreen"` | Navigate to tab |
|
|
| `cdp_get_route` | Get current route name |
|
|
| `cdp_get_state` | Get full nav state |
|
|
| `cdp_go_back` | Go back |
|
|
| `nav_explore/search/home/profile` | Quick tab navigation |
|
|
|
|
## File Structure
|
|
|
|
```
|
|
qa-test-flows/
|
|
├── SKILL.md # This file
|
|
├── lib/
|
|
│ ├── test-helpers.sh # Core test framework
|
|
│ └── cdp-helpers.sh # CDP interaction helpers
|
|
├── flows/
|
|
│ └── smoke/
|
|
│ └── example-smoke.sh # Example smoke test
|
|
├── templates/
|
|
│ └── new-flow.sh.template # Template for new tests
|
|
└── run-all.sh # Master test runner
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Solution |
|
|
|---------|----------|
|
|
| agent-device click hangs | Commands run in background with timeout — if still hanging, increase `DEVICE_CMD_TIMEOUT` |
|
|
| Dev console overlay covers screen | Call `dismiss_error_overlay` from scroll-helpers, or use CDP to suppress LogBox |
|
|
| Accessibility tree is sparse | React Native trees are thinner than web — prefer coordinates + screenshots |
|
|
| CDP timeout | Check dev server is running: `curl $DEV_SERVER_HEALTH` |
|
|
| Module ID changed after code update | Delete cache: `rm $NAV_MODULE_CACHE` — setup guard will re-scan |
|