# How to Use the QA Map Source Tray Helper in God’s Eye View: A Complete Testing Guide > Master the QA map source tray helper in God's Eye View. This guide details how this Puppeteer script enhances UI testing for navigation, errors, and accessibility. - Repository: [Bilawal Sidhu/gods-eye-view](https://github.com/bilawalsidhu/gods-eye-view) - Tags: how-to-guide - Published: 2026-09-13 --- **The QA map source tray helper is a Puppeteer-based automation script that validates keyboard navigation, error handling, and accessibility of the Map Source Tray UI in a headless or headful Chromium instance.** The **Map Source Tray** sits at the bottom of the God’s Eye View command dock and lets users switch between basemaps like Photoreal, Bing Aerial, and OpenStreetMap. The repository `bilawalsidhu/gods-eye-view` ships with a dedicated QA helper in `scripts/qa-map-source-tray.mjs` that exercises every interaction path—from focus management to network failure fallbacks—ensuring the tray behaves correctly across environments. ## Environment Configuration Before running the helper, you can customize its behavior through environment variables. The script reads `QA_BASE_URL` to know where the dev server is running and `QA_SHOTS_DIR` to decide where screenshot artifacts are stored. - `QA_BASE_URL` defaults to `http://localhost:4173` - `QA_SHOTS_DIR` defaults to `qa-shots/map-source-tray` If you are testing in CI or without a Cesium Ion token, pass the `--keyless` flag. This triggers a branch in the script that clears `controller.cesiumToken` and `controller.googleTileset` before assertions, as implemented in lines 110–118 of `scripts/qa-map-source-tray.mjs`. ## Running the QA Helper The helper supports three execution modes depending on your debugging needs. All modes output `[PASS]` or `[FAIL]` lines for each assertion and exit with a non-zero code if any test fails. ### Headless Mode (Default) Run the full suite without a GUI. This is the standard mode for CI pipelines. ```bash export QA_BASE_URL=http://localhost:4173 export QA_SHOTS_DIR=$PWD/qa-shots/map-source-tray node scripts/qa-map-source-tray.mjs ``` ### Headful Mode for Visual Debugging Add the `--headful` flag to launch a visible Chrome window. You can watch the tray expand when the script presses **Enter**, collapse on **Escape**, and observe focus rings in real time. ```bash node scripts/qa-map-source-tray.mjs --headful ``` ### Testing Without API Keys Use `--keyless` to validate fallback behavior when the Cesium Ion token is missing. This mode clears the token and Google Photoreal tileset before running assertions, ensuring the UI correctly disables premium sources. ```bash node scripts/qa-map-source-tray.mjs --keyless ``` ## Core Testing Capabilities The helper doesn’t just click buttons—it validates the entire accessibility and error-resilience surface of the tray. ### Keyboard Navigation and Focus Management The script validates that the tray follows WAI-ARIA disclosure patterns. It checks `aria-expanded` states and verifies focus transfer between the disclosure button and the selected tile. - **Enter** opens the tray and moves focus to the selected basemap tile - **Space** behaves identically to Enter - **Escape** closes the tray and restores focus to the disclosure button In `scripts/qa-map-source-tray.mjs` lines 83–90, the helper polls the DOM via `waitTray` utilities until `document.activeElement` matches the expected tile. Lines 96–104 handle the close-tray assertion, ensuring focus returns to `#control-panel-toggle` managed by [`src/ui/panelDisclosure.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/panelDisclosure.js). ### Delayed Visibility and Race Conditions To test focus resilience, the helper temporarily injects `visibility:hidden` on all tiles (lines 40–58), opens the tray via keyboard, then removes the CSS block. It asserts that focus lands correctly once the tiles become visible, catching race conditions between animation frames and focus events. ### Error Handling and Fallback Logic The script simulates provider failures to verify graceful degradation. It triggers `provider.errorEvent.raiseEvent` twice against the Esri source and polls the DOM until the UI automatically switches to OpenStreetMap and removes the Esri credit. This logic lives in lines 86–105. Additionally, the helper validates global loading feedback by calling `styleManager._handleShareTrackingRestoreStatus` with various classification strings (lines 146–166) and snapshots the DOM to confirm "acquiring" and "error" notices appear and disappear at the correct lifecycle moments. ## Understanding the Test Architecture The QA helper orchestrates a hermetic browser environment and interacts with specific UI controllers. ### Browser Launch and Graphics Backend Lines 29–38 of `scripts/qa-map-source-tray.mjs` configure Puppeteer to use platform-specific GL backends: - macOS: `--use-angle=metal` - Linux/Windows: `--use-gl=angle` or `--use-angle=swiftshader` The script forces `--no-sandbox` for compatibility with containerized CI runners. ### Network Interception To keep tests deterministic, the helper intercepts external endpoints (lines 34–53), stubbing HUD-summary and Google-Places requests with static JSON payloads. This prevents network flakiness from breaking assertions about tray state. ### UI Coordination Modules The tray’s visual state is governed by three key files that the helper validates against: - **[`src/ui/panelLayoutController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/panelLayoutController.js)**: Observes tray elements and toggles CSS classes like `dock-has-pinned-tray` and `dock-has-two-pinned-trays` - **[`src/ui/panelDisclosure.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/panelDisclosure.js)**: Manages the disclosure button (`#control-panel-toggle`) and focus-visible timing - **[`src/ui/applicationShell.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/applicationShell.js)**: Coordinates stacked trays and updates CSS custom properties for pinned-tray heights (lines 2050–2135) ## Summary - The **QA map source tray helper** is located at `scripts/qa-map-source-tray.mjs` in the `bilawalsidhu/gods-eye-view` repository - Set `QA_BASE_URL` and `QA_SHOTS_DIR` to control target server and screenshot output paths - Use `--headful` for visual debugging and `--keyless` to test token-less fallback behavior - The script validates keyboard accessibility (`Enter`, `Space`, `Escape`), focus management, delayed visibility, and error fallbacks - It stubs external network calls to ensure hermetic, reliable CI execution ## Frequently Asked Questions ### What dependencies are required to run the QA map source tray helper? You need Node.js and a Chrome or Chromium installation. The script uses Puppeteer, which should be listed in the project’s [`package.json`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/package.json). Ensure the dev server is running on the port specified by `QA_BASE_URL` (default `4173`) before executing the helper. ### How do I debug a failing assertion in the tray tests? Run the helper with the `--headful` flag to watch the interaction live. Check the `QA_SHOTS_DIR` directory for PNG screenshots captured at the moment of failure. Each `[FAIL]` line in the console output includes the specific assertion that failed, such as focus state or `aria-expanded` value. ### Can I run the QA helper without a Cesium Ion API key? Yes. Pass the `--keyless` argument when running the script. This clears `controller.cesiumToken` and `controller.googleTileset` before testing, allowing you to validate that premium sources are correctly disabled and that the UI falls back to freely available basemaps like OSM. ### Where are the UI components that the helper tests? The tray’s layout logic resides in [`src/ui/panelLayoutController.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/panelLayoutController.js), the disclosure button handling is in [`src/ui/panelDisclosure.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/panelDisclosure.js), and the overall command-dock coordination happens in [`src/ui/applicationShell.js`](https://github.com/bilawalsidhu/gods-eye-view/blob/main/src/ui/applicationShell.js). The QA helper validates that these modules correctly manage CSS classes, focus states, and tray stacking during its automated interaction sequence.