| 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:
#!/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 "Navigate to target screen"
cdp_navigate "TargetScreen"
sleep 2
take_screenshot "01-target-screen"
assert_screenshot "01-target-screen"
step "Perform action"
tap 200 400
sleep 1
take_screenshot "02-after-action"
step "Verify result"
route=$(cdp_get_route)
log_info "Route: $route"
teardown_test
Running Tests
Single Test
bash .pi/skills/qa-automation/qa-test-flows/flows/smoke/example-smoke.sh
All Tests
bash .pi/skills/qa-automation/qa-test-flows/run-all.sh
With Logging
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
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
agent-device screenshot /tmp/debug.png
open /tmp/debug.png
4. Run and verify
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 |
