Switchify Android Agentic QA

QA tooling for Switchify.

This repo contains QA tooling for ADB-driven manual scanning tests against debug builds of the Switchify Android app.

The TypeScript runner can take a human goal, ask an isolated read-only Codex child agent what to do next from screenshots and state, execute only approved Switchify ADB bridge actions, and write reproducible evidence under runs/.

The runner embeds a Switchify operating guide into each child prompt so Codex has app-specific context for ScanTree levels, scan colors, menu behavior, keyboard escape, and weird-finding search hints.

Requirements

• Android SDK with ADB and the Android Emulator installed.
• SwitchifyStorePhone AVD (or pass --avd <name>).
• Sibling ../switchify-android checkout with a buildable debug configuration.
• Switchify accessibility service already authorized on the emulator.
• Switchify debug ADB testing bridge available in the app.
• adb available on PATH, via ANDROID_HOME, via ANDROID_SDK_ROOT, or passed with -AdbPath.

Commands

Install the TypeScript runner dependencies:

npm install

Run a Codex-driven QA goal:

npm run qa -- --goal "Open YouTube and watch a video" --device <device-id>

Normal runs ignore physical devices, reuse the sole ready emulator, or launch SwitchifyStorePhone in a visible window. They then build/install the sibling debug app, preflight it, prime manual item scanning, run the goal, restore the prior Switchify state, and leave the emulator open.

Manual command pad

Launch the compact Electron controls when a person should drive scanning while watching the visible emulator:

npm run desktop

Click Prepare & Prime before sending commands. The app acquires the emulator, builds and installs ../switchify-android, completes preflight, backs up the current device state, primes manual item scanning, reloads settings, and reads the installed files back. Ready means it verified scan_mode=manual, access_technique=item_scan, and the 131/132/133 Next/Previous/Select mappings.

Use the large buttons or focused-window shortcuts (Left Arrow, Enter, Right Arrow) for Previous, Select, and Next. Other validated debug-bridge actions are under Advanced commands. The emulator remains the visual display; Capture Evidence writes a snapshot to the session run directory.

Click End & Restore when finished. Closing the window also captures final evidence and restores the backup before quitting. If restoration fails, the window remains open with retry, run-folder, and manual-command controls; a forced process termination is still covered by the detached cleanup watchdog. The debug APK and visible emulator are retained.

Use a different AVD or explicitly opt into headless emulation:

npm run qa -- --goal "Open YouTube" --avd Pixel_10_Pro
npm run qa -- --goal "Open YouTube" --headless

Run with opt-in full bridge actions:

npm run qa -- --goal "Find YouTube from the launcher and open it" --device <device-id> --action-profile full

Validate the runner without priming or sending ADB actions:

npm run qa -- --goal "Dry run validation" --dry-run

Preserve QA settings only when debugging cleanup-sensitive behavior:

npm run qa -- --goal "Inspect the final scan state" --keep-qa-state

Run static checks:

npm test

See docs/codex-runner.md for the runner architecture, evidence format, and finding handoff workflow. See docs/switchify-operating-guide.md for the scanning model that is embedded into each child prompt.

Manual Harness

Run a device/environment check:

.\switchify-manual-scan-qa.ps1 doctor -DeviceId <device-id>

Prime Switchify for manual item scan QA:

.\switchify-manual-scan-qa.ps1 prime -DeviceId <device-id>

Send switch actions through the Switchify ADB testing bridge:

.\switchify-manual-scan-qa.ps1 press next -DeviceId <device-id>
.\switchify-manual-scan-qa.ps1 press previous -DeviceId <device-id>
.\switchify-manual-scan-qa.ps1 press select -DeviceId <device-id>

Capture evidence:

.\switchify-manual-scan-qa.ps1 capture -DeviceId <device-id>

Create a report from a run directory:

.\switchify-manual-scan-qa.ps1 report -RunDir <run-dir>

Restore app data from a priming run:

.\switchify-manual-scan-qa.ps1 restore -DeviceId <device-id> -RunDir <run-dir>

Safety

prime backs up Switchify switch mappings and preferences before applying QA settings. The TypeScript runner and Electron command pad prime only after emulator, build/install, and preflight succeed; they capture final evidence and then restore automatically on every terminal outcome. If cleanup reports failed, use restore with that run directory before starting another test.

Generated run evidence is written under runs/ and intentionally ignored by git. That directory can contain screenshots, logcat output, window dumps, preference backups, device IDs, local paths, and app state.

Prefer the Switchify debug ADB testing bridge over raw adb shell input keyevent for scan actions. Synthetic key events do not reliably reach Android accessibility services.

The runner defaults to the single-switch profile: next, previous, select, capture, and stop. Use --action-profile full only when a test intentionally needs system or service bridge actions such as home, back, recents, notifications, lock_screen, or reload_settings.

Avoid uiautomator dump during service overlay testing unless you explicitly need it. UiAutomation can temporarily disrupt accessibility service state.