How to Use the QA Map Source Tray Helper in God’s Eye View: A Complete Testing Guide

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.

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.

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.

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.

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: Observes tray elements and toggles CSS classes like dock-has-pinned-tray and dock-has-two-pinned-trays
• src/ui/panelDisclosure.js: Manages the disclosure button (#control-panel-toggle) and focus-visible timing
• 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. 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, the disclosure button handling is in src/ui/panelDisclosure.js, and the overall command-dock coordination happens in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}