Getting started

Step 1: Register the app map

Add one guarded assignment beside map creation. It exposes the map instance to scripts on the page, so keep it out of production builds. The injected adapter uses the map library's public API and runs at test time; geowright adds no production dependency.

// Vite — test and development builds only
const map = new maplibregl.Map({ /* your options */ });

if (import.meta.env.MODE !== 'production') {
  (window.__geowright_maps ??= {}).main = map;
}

This guard is the Vite form. Wrapper-specific hooks follow the same test-only rule.

Step 2: Prepare the test project

npm i -D geowright @playwright/test && npx playwright install chromium

npx geowright init

The package is on npm.

Step 3: Query, click, assert

A feature handle is lazy and strict: the action resolves one visible match, finds a usable pixel, and dispatches real pointer input. The popup matcher retries like a Playwright web-first assertion.

import { test } from '@playwright/test';
import { geowright, expect } from 'geowright';

test('opens the selected alert', async ({ page }) => {
  await page.goto('/');

  const map = geowright(page);
  await map.waitForIdle();

  await map.feature({ layer: 'alerts', id: 1 }).click();

  await expect(map).toHavePopup({
    feature: { layer: 'alerts', id: 1 },
    text: 'Gas leak',
  });
});

Use your app URL or configured Playwright baseURL. Replace the example layer, feature ID, and popup text with your app's data. The initializer supplies the software-WebGL setup; when a Playwright config already exists, it prints the changes to apply there.