Skip to main content

Architecture Decision Record: Playwright & React Native Web for Mobile E2E Testing 📱🎭

Status​

Decided (May 2026)

Context​

Athena Helm features a dedicated React Native companion application under mobile/. To prevent regressions and verify that context-loaders, rig calibrations, and UI layouts operate correctly on every commit, we need an automated End-to-End (E2E) testing framework.

Standard mobile E2E tools (like Detox or Maestro) require running a full Android Emulator or iOS Simulator. Running these virtualization layers inside standard GitHub Actions virtual machines has severe drawbacks:

  • High Resource Cost & Latency: Virtualization is extremely slow on standard runners (tests take 20 to 30 minutes to complete).
  • Flakiness: Native emulators inside standard CI are prone to sudden startup timeouts and memory exhaustion.
  • Complexity: Managing virtual SDK states, ADB ports, and target device profiles increases developer environment configuration overhead.

Decision​

We elected to compile the React Native mobile application for the Web Platform using Expo's web target exports, and execute our E2E tests against this web build using Playwright with viewport emulation.

  1. Compilation: The mobile app is exported to a static bundle inside mobile/dist/ via npx expo export --platform web.
  2. Server: The static files are served locally using http-server on port 8081.
  3. Runner: Playwright runs tests inside a unified project configuration, emulating a mobile device (Pixel 5) and hitting http://localhost:8081.
  4. Debugging Captures: Playwright is configured to capture screenshots (screenshot: 'on'), video recordings (video: 'on'), and execution trace timelines (trace: 'on') for all test runs (both successful and failed) to provide comprehensive visual assets for human and AI inspection.

Consequences​

  • Ultra-Fast Executions: Running the mobile E2E tests on web takes under 1 minute on CI compared to 20+ minutes with full native virtualization.
  • Zero virtualization requirements: Works natively on standard Linux GitHub Action runners without requiring nested virtualization or paid macOS/bare-metal machines.
  • Early Bug Detection: Catches standard JS/TS crashes, React state bugs, React Navigation setup issues, and import-time native module exceptions before physical device deployment.
  • Unified Reporting: E2E test results, visual screenshots, and trace recordings for both Web Dashboard and Mobile Client are merged into a single, beautiful Playwright HTML report on every commit.
  • UX & Aesthetic Reviews: Unconditional capture of screenshots and videos allows developers and AI LLMs to download and visually inspect every layout, background gradient, and font styling after every single CI run to suggest layout improvements.
  • Native-Only Boundary: While this catches 95% of application logic, navigation, and state issues, it cannot test platform-specific low-level native bugs (e.g., direct bluetooth serial connections or actual device microphone hardware levels), which will continue to be validated via local manual physical device testing (Option B in README).