qa-test-flows

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 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 .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  # Measure tap targets

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