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

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

cdp-helpers.sh

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