Troubleshooting

"no map registered" although the line is there

Wrappers call onLoad on MapLibre's load event, and load needs every declared source. If a data request is blocked or fails in the test, load never fires and the map is never registered. Look at the network, not at the hook: answer every request the app makes with page.route (the harness fails a test listing the URLs nobody answered — copy that idea).

The map never becomes idle

An animated source, a setData loop, a rotating camera: waitForIdle() times out and says which of these it saw. Do not wait for idle on such a page — assertions and actions retry by themselves. To act on a feature that never stops moving: click({ moving: 'allow' }) (README, "What an action waits for"; the reasoning: DESIGN, "Targets that never stop moving").

Re-pointing an image (updateImage), vector tiles (setTiles), or GeoJSON URL (setData) faster than loads finish also counts as never idle when overlapping starts keep occurring through the wait (for example, every 200 ms with 400 ms loads). .not and counts can pass from the current map while the newest data is still loading. One load, two replacements, or sequential completed loads still wait for the data; another pending source also prevents a never-idle verdict.

A static map that times out with "… DEAD WORKER …" (or, for sources loaded from a URL, "source(s) … have not finished loading") is usually not a test problem: the app's map is broken in the browser too. The common case is MapLibre GL JS 6 under Vite's DEV server — the dependency optimizer moves maplibre-gl and its worker file is not found (the dev server's log says maplibre-gl-worker.mjs … does not exist … Try adding it to optimizeDeps.exclude), so no source ever loads. In vite.config: optimizeDeps: { exclude: ['maplibre-gl'] }, or test the built app (vite build && vite preview), which is what this repository does. Note also that MapLibre 6 is ESM with named exports only: import { Map } from 'maplibre-gl' (or import * as maplibregl), not a default import.

Slow pages (terrain, a globe, software GL in CI)

test.slow() — geowright's default timeouts follow the test's timeout: a third of it for actions (at least 10 s), two thirds for waitForIdle() (the first idle is a page load, not an action). Assertions (expect(map)…) use Playwright's expect timeout, which test.slow() does not change: raise it in the config (expect: { timeout: 15_000 }) or per assertion ({ timeout }). An action's timeout is wall-clock until its input is sent, also on a page too busy to answer. Real input is never abandoned half-way, and a feature's click() / tap() then wait for the page to say where it landed. As in Playwright, timeout: 0 means no timeout.