Skip to content

AGENTS.md

Latest commit

 

History

History
23 lines (15 loc) · 2.18 KB

AGENTS.md

File metadata and controls

23 lines (15 loc) · 2.18 KB
Raw

Switchify Manual-Scanning QA

This repository exists to exercise Switchify Android manual scanning through the debug ADB bridge and preserve reproducible visual evidence. Normal QA runs must use an Android emulator, never a physical device.

Required lifecycle

  1. Start with npm run qa -- --goal "<goal>". The runner reuses the sole ready emulator or launches the visible SwitchifyStorePhone AVD.
  2. Let the runner build and install the debug app from ../switchify-android, then verify the package, debug bridge, run-as, and accessibility service.
  3. Prime only after preflight succeeds and immediately before the first evidence capture. Priming backs up switch mappings and preferences in the run directory, then applies manual item-scanning settings.
  4. Use only approved Switchify bridge actions during the test. Do not substitute raw taps, key events, or UIAutomator dumps for scanning actions.
  5. Capture final evidence before cleanup. The runner restores the backed-up mappings and preferences on success, stop, step limit, failure, or interruption. A detached watchdog restores from the backup if the parent process is forcibly terminated. Leave the emulator open for review.

For human-driven scanning, use npm run desktop. Its explicit lifecycle is Prepare & Prime → verified Ready → manual commands/captures → End & Restore. Ready is allowed only after the installed preferences and mappings read back as manual item scanning with keys 131/132/133. Closing an active desktop session must run final capture and restore before the window exits; if restore fails, keep the recovery controls and manual restore command visible.

--headless is an explicit opt-in; visible emulation is the default. --keep-qa-state is only for deliberate debugging and skips automatic restoration. --no-prime is only for continuing a device state prepared elsewhere and performs no restoration.

If automatic cleanup fails or a second interrupt forces the process to exit, restore manually with:

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

Do not delete a run directory until its cleanup status is restored or the manual restore has completed.