claude-mods/skills/mapbox-ops/references/verification.md

Headless verification

Verify a Mapbox page renders and markers land where expected by driving headless Chromium with Playwright and screenshotting. Pixel-accurate alignment checks use map.project(lngLat).

Serve, don't file://

A page that fetches GeoJSON/photos at runtime must be served (same-origin, or the canvas taints and createImageBitmap throws — see markers.md):

python -m http.server 8777 --directory <site-dir>
# open http://localhost:8777/preview/index.html

The 'load'-in-background-tab quirk

Mapbox's 'load' event may not fire in a throttled / backgrounded / headless tab — a known harness quirk; the map renders fine in the foreground. Guard your init so either event triggers it exactly once:

let _inited = false;
function init() { if (_inited) return; _inited = true; /* setup layers, render */ }
map.on("load", init);
map.on("idle", init);   // fallback if the first 'load' frame was missed

In Playwright, wait on a DOM/JS signal you control rather than the map's 'load': e.g. set window.__mapReady = true at the end of init() and page.wait_for_function("window.__mapReady === true").

Marker-alignment check via map.project

map.project([lng, lat]) returns the pixel coords relative to the map canvas. Add the canvas's page offset to compare against a screenshot or a DOM-space click:

const m = map.getCanvas().getBoundingClientRect();
const p = map.project([lng, lat]);
const pageXY = { x: m.left + p.x, y: m.top + p.y };   // where the marker's anchor lands

The runnable harness — launch chromium, wait for ready, screenshot, and assert a known lng/lat projects to the expected pixel — is in ../scripts/screenshot_map.py.

What to assert

• No console errors (page.on("console", …)), especially Image "<name>" already exists (double-addImage) or style-load failures.
• The canvas isn't blank (screenshot non-uniform, or map.loaded() === true).
• A representative marker's projected pixel falls within the canvas and (optionally) over a non-background colour in the screenshot.