From 42ce46b6112fb20280ee5d75e0171f6cdc4ada7e Mon Sep 17 00:00:00 2001
From: Kevin Walker <kevin@smartive.ch>
Date: Thu, 8 Oct 2026 09:42:31 +0200
Subject: [PATCH 1/4] feat: add testing helpers for sitemap-driven smoke tests

Add `@smartive/utils/testing` (sitemap parsing, route limits, ignore
rules, browserless URL check) and `@smartive/utils/testing/playwright`
(fixtures that fail a test on client-side errors, third-party request
blocking, global setup that hands sitemap routes to the specs).

`@playwright/test` is an optional peer and only imported as types, so
each project runs the version pinned to its CI image. Both subpaths have
a `default` export condition so CommonJS projects can require them.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/test.yml     |  15 ++
 .gitignore                     |   5 +
 README.md                      | 165 ++++++++++++++++
 e2e/fixtures.spec.ts           |  93 +++++++++
 e2e/fixtures.ts                |   5 +
 e2e/global-setup.ts            |   3 +
 e2e/http.spec.ts               |  12 ++
 e2e/pages.spec.ts              |  17 ++
 e2e/playwright.config.ts       |  20 ++
 e2e/require-check.cts          |  14 ++
 e2e/server.ts                  |  90 +++++++++
 e2e/tsconfig.json              |  13 ++
 package-lock.json              |  50 +++++
 package.json                   |  25 ++-
 src/testing/http-check.test.ts | 118 ++++++++++++
 src/testing/http-check.ts      |  96 ++++++++++
 src/testing/ignore.test.ts     |  36 ++++
 src/testing/ignore.ts          |  32 ++++
 src/testing/index.ts           |   5 +
 src/testing/patterns.test.ts   |  29 +++
 src/testing/patterns.ts        |  19 ++
 src/testing/playwright.test.ts | 339 +++++++++++++++++++++++++++++++++
 src/testing/playwright.ts      | 300 +++++++++++++++++++++++++++++
 src/testing/routes.test.ts     |  72 +++++++
 src/testing/routes.ts          |  42 ++++
 src/testing/sitemap.test.ts    | 151 +++++++++++++++
 src/testing/sitemap.ts         | 118 ++++++++++++
 27 files changed, 1881 insertions(+), 3 deletions(-)
 create mode 100644 e2e/fixtures.spec.ts
 create mode 100644 e2e/fixtures.ts
 create mode 100644 e2e/global-setup.ts
 create mode 100644 e2e/http.spec.ts
 create mode 100644 e2e/pages.spec.ts
 create mode 100644 e2e/playwright.config.ts
 create mode 100644 e2e/require-check.cts
 create mode 100644 e2e/server.ts
 create mode 100644 e2e/tsconfig.json
 create mode 100644 src/testing/http-check.test.ts
 create mode 100644 src/testing/http-check.ts
 create mode 100644 src/testing/ignore.test.ts
 create mode 100644 src/testing/ignore.ts
 create mode 100644 src/testing/index.ts
 create mode 100644 src/testing/patterns.test.ts
 create mode 100644 src/testing/patterns.ts
 create mode 100644 src/testing/playwright.test.ts
 create mode 100644 src/testing/playwright.ts
 create mode 100644 src/testing/routes.test.ts
 create mode 100644 src/testing/routes.ts
 create mode 100644 src/testing/sitemap.test.ts
 create mode 100644 src/testing/sitemap.ts

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index 209e229..cbcb58d 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -27,3 +27,18 @@ jobs:
       - run: npm run typecheck
       - run: npm run test
       - run: npm run build
+
+  e2e:
+    name: Playwright e2e
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7
+        with:
+          node-version: 24
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run test:e2e
diff --git a/.gitignore b/.gitignore
index fa28420..43ca2d1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,8 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
+
+# playwright e2e
+/test-results
+/playwright-report
+/e2e/test-results
diff --git a/README.md b/README.md
index d85234e..2bb6cd2 100644
--- a/README.md
+++ b/README.md
@@ -229,6 +229,171 @@ covers the manual full reset (a missed webhook, or a change to the query-ID form
 | `DRAFT_SECRET_TOKEN`              | Authorizes draft enable/disable and web-previews                   |
 | `CACHE_INVALIDATION_SECRET_TOKEN` | Authorizes the revalidate and cache-tag webhooks (`Webhook-Token`) |
 
+## `@smartive/utils/testing`
+
+Building blocks for sitemap-driven smoke tests. Zero dependencies, no browser.
+
+```typescript
+import { checkUrls, fetchSitemapRoutes, formatUrlCheckFailures } from '@smartive/utils/testing';
+
+const routes = await fetchSitemapRoutes({
+  baseURL: 'http://localhost:3333',
+  limits: [{ pattern: '/arbeiten/', max: 3 }], // sample large collections
+  exclude: ['/ueber-uns/livebilder'],
+});
+
+const results = await checkUrls(routes, { baseURL: 'http://localhost:3333' });
+```
+
+- `fetchSitemapRoutes` follows a sitemap index and includes `xhtml:link` alternates. It replaces the
+  sitemap host with `baseURL`, deduplicates, applies `exclude` then `limits`, and throws when the
+  sitemap is unreachable or empty, so a broken sitemap never turns into a green run that checked
+  nothing.
+- `checkUrls` requests every URL without following redirects (a redirecting sitemap URL fails),
+  retries network errors and 5xx once, and never throws. `formatUrlCheckFailures` turns the
+  failures into an assertion message.
+- `parseSitemap`, `limitRoutes`, `excludeRoutes`, `toPath` and `isIgnored` are exported for custom
+  setups. Patterns are a `string` (substring) or a `RegExp`.
+
+### `@smartive/utils/testing/playwright`
+
+Fixtures that fail a Playwright test on client-side errors: hydration mismatches, React errors,
+exceptions in client components, failed first-party requests. Only types are imported from
+`@playwright/test`, so install the version that matches your CI image:
+
+```bash
+npm install -D @playwright/test@<version of mcr.microsoft.com/playwright in your CI>
+```
+
+The automatic `smoke` fixture:
+
+- blocks every request that is not same-origin with `baseURL` or listed in `allowHosts`, so
+  trackers, consent banners and embeds neither add noise nor send hits from CI
+- collects console errors and warnings (`failOn`), uncaught exceptions and unhandled rejections,
+  first-party responses with status ≥ 400 and failed first-party requests
+- ignores console errors of blocked requests and expected aborts (`<video>` range requests, page
+  close), drops entries matching `ignore`, and deduplicates
+- fails the test afterwards with the full list, attaches it as `smoke-issues.json`, and annotates
+  the blocked hosts
+
+Navigate with `gotoAndSettle`: `waitUntil: 'load'` plus a settle time (default 2 s) for hydration.
+Never `networkidle`, which a playing `<video>` prevents from ever arriving.
+
+#### Recipe
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+const PORT = 3333; // not 3000, so reuseExistingServer never picks up `next dev`
+
+export default defineConfig({
+  testDir: 'test/smoke',
+  globalSetup: './test/smoke/global-setup.ts',
+  fullyParallel: true,
+  workers: process.env.CI ? 2 : undefined,
+  retries: process.env.CI ? 1 : 0,
+  forbidOnly: !!process.env.CI,
+  reporter: [['list'], ['junit', { outputFile: 'test-results/junit.xml' }], ['html', { open: 'never' }]],
+  use: { baseURL: process.env.BASE_URL ?? `http://localhost:${PORT}`, trace: 'retain-on-failure' },
+  projects: [{ name: 'chromium', use: devices['Desktop Chrome'] }],
+  webServer: process.env.BASE_URL
+    ? undefined
+    : {
+        command: `npm run build && npm run start -- -p ${PORT}`,
+        url: `http://localhost:${PORT}/sitemap.xml`,
+        timeout: 15 * 60_000,
+        reuseExistingServer: !process.env.CI,
+      },
+});
+```
+
+```typescript
+// test/smoke/global-setup.ts
+import { smokeGlobalSetup } from '@smartive/utils/testing/playwright';
+
+export default smokeGlobalSetup({ limits: [{ pattern: '/arbeiten/', max: 3 }] });
+```
+
+```typescript
+// test/smoke/fixtures.ts
+import { test as base } from '@playwright/test';
+import { smokeFixtures, type SmokeFixtures } from '@smartive/utils/testing/playwright';
+
+export const test = base.extend<SmokeFixtures>(
+  smokeFixtures({
+    allowHosts: ['*.datocms-assets.com', 'stream.mux.com', 'image.mux.com'],
+    ignore: ['Please ensure that the container has a non-static position'],
+  }),
+);
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// test/smoke/pages.spec.ts
+import { gotoAndSettle, readRoutes } from '@smartive/utils/testing/playwright';
+
+import { expect, test } from './fixtures';
+
+for (const route of readRoutes()) {
+  test(route, async ({ page }) => {
+    const response = await gotoAndSettle(page, route);
+
+    expect(response?.status()).toBe(200);
+  });
+}
+```
+
+```typescript
+// test/smoke/http.spec.ts – plain `test`, so no browser is started
+import { expect, test } from '@playwright/test';
+import { checkUrls, fetchSitemapRoutes, formatUrlCheckFailures } from '@smartive/utils/testing';
+
+test('every sitemap URL returns 200', async ({ baseURL }) => {
+  const results = await checkUrls(await fetchSitemapRoutes({ baseURL: baseURL! }), { baseURL });
+
+  expect(formatUrlCheckFailures(results)).toBe('');
+});
+```
+
+```yaml
+# .gitlab-ci.yml
+tests:
+  image: mcr.microsoft.com/playwright:v<same version as @playwright/test>-noble
+  script:
+    - npm ci
+    - npx playwright test
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+  artifacts:
+    when: always
+    expire_in: 1 week
+    reports:
+      junit: test-results/junit.xml
+    paths: [playwright-report/, test-results/]
+```
+
+#### Notes
+
+- **Why global setup:** Playwright runs `webServer` and `globalSetup` before it loads test files,
+  so the spec can generate one test per route from the file `smokeGlobalSetup` writes (default
+  `node_modules/.cache/smartive-utils/smoke-routes.json`). Every worker reads the same list, even
+  if the sitemap changes mid-run. Setup projects run too late for this. `playwright test --list`
+  skips global setup and lists no routes.
+- **Existing Playwright setup:** `globalSetup` applies to a whole config, so put the smoke suite in
+  its own `playwright.smoke.config.ts` and run it with `playwright test -c playwright.smoke.config.ts`.
+- **Per-file options:** `test.use({ smokeOptions: { failOn: ['error'] } })`.
+- **Expecting issues:** a test can assert on `smoke.issues` and empty it (`smoke.issues.length = 0`)
+  to pass.
+- **CommonJS projects** (most Next.js apps) work: Playwright compiles the specs to `require()`, and
+  both subpaths have a `default` export condition for that.
+- **Keep the version in sync:** group `@playwright/test` and `mcr.microsoft.com/playwright` in one
+  Renovate rule, otherwise the browser in the image and the runner drift apart.
+- **Retries** rerun every failure, so an intermittent console error shows up as flaky and passes.
+  Set `failOnFlakyTests: true` to fail on it instead.
+- **Video** is never really played: Playwright's Chromium has no H.264 decoder. Only the page around
+  it is checked.
+
 ## Migrating from `@smartive/datocms-utils`
 
 This package was previously published as `@smartive/datocms-utils`. With `4.0.0` it was renamed to
diff --git a/e2e/fixtures.spec.ts b/e2e/fixtures.spec.ts
new file mode 100644
index 0000000..b46ffd1
--- /dev/null
+++ b/e2e/fixtures.spec.ts
@@ -0,0 +1,93 @@
+import { gotoAndSettle } from '@smartive/utils/testing/playwright';
+
+import { expect, test } from './fixtures.js';
+
+const SETTLE = { settleMs: 300 };
+
+test.describe('collects issues', () => {
+  test('console errors', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/console-error', SETTLE);
+
+    expect(smoke.issues).toEqual([expect.objectContaining({ type: 'console-error', text: 'client boom' })]);
+    smoke.issues.length = 0;
+  });
+
+  test('console warnings', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/console-warning', SETTLE);
+
+    expect(smoke.issues).toEqual([expect.objectContaining({ type: 'console-warning', text: 'careful' })]);
+    smoke.issues.length = 0;
+  });
+
+  test('uncaught exceptions', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/page-error', SETTLE);
+
+    expect(smoke.issues).toEqual([expect.objectContaining({ type: 'pageerror', text: 'uncaught boom' })]);
+    smoke.issues.length = 0;
+  });
+
+  test('unhandled promise rejections', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/rejection', SETTLE);
+
+    expect(smoke.issues).toEqual([expect.objectContaining({ type: 'pageerror', text: 'unhandled rejection' })]);
+    smoke.issues.length = 0;
+  });
+
+  test('missing first-party assets, without the duplicate console message', async ({ page, smoke, baseURL }) => {
+    await gotoAndSettle(page, '/missing-asset', SETTLE);
+
+    expect(smoke.issues).toEqual([
+      { type: 'response', text: `HTTP 404 ${baseURL}/missing.png`, location: `${baseURL}/missing.png` },
+    ]);
+    smoke.issues.length = 0;
+  });
+
+  test('failed first-party requests', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/broken-request', SETTLE);
+
+    expect(smoke.issues).toEqual([expect.objectContaining({ type: 'requestfailed' })]);
+    smoke.issues.length = 0;
+  });
+});
+
+test.describe('stays quiet', () => {
+  test('blocks third parties and allows allowlisted hosts', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/third-party', SETTLE);
+
+    expect(await page.evaluate(() => (window as { allowedLoaded?: boolean }).allowedLoaded)).toBe(true);
+    expect([...smoke.blockedUrls]).toEqual(['http://tracker.invalid/t.js']);
+    expect(smoke.issues).toEqual([]);
+  });
+
+  test('ignores aborted requests', async ({ page, smoke }) => {
+    await gotoAndSettle(page, '/aborted', SETTLE);
+
+    expect(smoke.issues).toEqual([]);
+  });
+
+  test.describe('with ignore rules', () => {
+    test.use({ smokeOptions: { ignore: ['client boom'] } });
+
+    test('ignored messages', async ({ page, smoke }) => {
+      await gotoAndSettle(page, '/console-error', SETTLE);
+
+      expect(smoke.issues).toEqual([]);
+    });
+  });
+
+  test.describe('failing only on errors', () => {
+    test.use({ smokeOptions: { failOn: ['error'] } });
+
+    test('warnings', async ({ page, smoke }) => {
+      await gotoAndSettle(page, '/console-warning', SETTLE);
+
+      expect(smoke.issues).toEqual([]);
+    });
+  });
+});
+
+test('fails the test when issues remain', async ({ page }) => {
+  test.fail();
+
+  await gotoAndSettle(page, '/console-error', SETTLE);
+});
diff --git a/e2e/fixtures.ts b/e2e/fixtures.ts
new file mode 100644
index 0000000..72d8e1b
--- /dev/null
+++ b/e2e/fixtures.ts
@@ -0,0 +1,5 @@
+import { test as base } from '@playwright/test';
+import { smokeFixtures, type SmokeFixtures } from '@smartive/utils/testing/playwright';
+
+export const test = base.extend<SmokeFixtures>(smokeFixtures({ allowHosts: ['127.0.0.1'] }));
+export { expect } from '@playwright/test';
diff --git a/e2e/global-setup.ts b/e2e/global-setup.ts
new file mode 100644
index 0000000..b3dde4d
--- /dev/null
+++ b/e2e/global-setup.ts
@@ -0,0 +1,3 @@
+import { smokeGlobalSetup } from '@smartive/utils/testing/playwright';
+
+export default smokeGlobalSetup({ limits: [{ pattern: '/blog/', max: 2 }] });
diff --git a/e2e/http.spec.ts b/e2e/http.spec.ts
new file mode 100644
index 0000000..09258a6
--- /dev/null
+++ b/e2e/http.spec.ts
@@ -0,0 +1,12 @@
+import { expect, test } from '@playwright/test';
+import { checkUrls } from '@smartive/utils/testing';
+
+test('reports the status of every URL without following redirects', async ({ baseURL }) => {
+  const results = await checkUrls(['https://prod.example.com/', '/redirect', '/nope'], { baseURL });
+
+  expect(results.map(({ status, ok }) => ({ status, ok }))).toEqual([
+    { status: 200, ok: true },
+    { status: 308, ok: false },
+    { status: 404, ok: false },
+  ]);
+});
diff --git a/e2e/pages.spec.ts b/e2e/pages.spec.ts
new file mode 100644
index 0000000..a85cdcc
--- /dev/null
+++ b/e2e/pages.spec.ts
@@ -0,0 +1,17 @@
+import { gotoAndSettle, readRoutes } from '@smartive/utils/testing/playwright';
+
+import { expect, test } from './fixtures.js';
+
+const routes = readRoutes();
+
+test('global setup wrote the limited sitemap routes', () => {
+  expect(routes).toEqual(['/', '/blog/a', '/blog/b', '/de', '/fr']);
+});
+
+for (const route of routes) {
+  test(`sitemap route ${route}`, async ({ page }) => {
+    const response = await gotoAndSettle(page, route, { settleMs: 200 });
+
+    expect(response?.status()).toBe(200);
+  });
+}
diff --git a/e2e/playwright.config.ts b/e2e/playwright.config.ts
new file mode 100644
index 0000000..155d33e
--- /dev/null
+++ b/e2e/playwright.config.ts
@@ -0,0 +1,20 @@
+import { defineConfig, devices } from '@playwright/test';
+
+const PORT = 4173;
+
+export default defineConfig({
+  testDir: '.',
+  globalSetup: './global-setup.ts',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  reporter: process.env.CI ? [['github'], ['list']] : 'list',
+  use: { baseURL: `http://localhost:${PORT}` },
+  projects: [{ name: 'chromium', use: devices['Desktop Chrome'] }],
+  webServer: {
+    command: 'node e2e/server.ts',
+    cwd: '..',
+    url: `http://localhost:${PORT}/`,
+    env: { PORT: String(PORT) },
+    reuseExistingServer: !process.env.CI,
+  },
+});
diff --git a/e2e/require-check.cts b/e2e/require-check.cts
new file mode 100644
index 0000000..8837250
--- /dev/null
+++ b/e2e/require-check.cts
@@ -0,0 +1,14 @@
+/* eslint-disable @typescript-eslint/no-require-imports, @typescript-eslint/no-var-requires -- this file exists to exercise require() */
+// Next.js projects are CommonJS, so Playwright compiles their specs to `require()`. Packages in
+// node_modules are then loaded by Node itself, which needs a `require` or `default` export
+// condition and require(esm). Run with plain `node`, not Playwright, so nothing transpiles it.
+const testing = require('@smartive/utils/testing') as typeof import('@smartive/utils/testing');
+const playwright = require('@smartive/utils/testing/playwright') as typeof import('@smartive/utils/testing/playwright');
+
+const limited = testing.limitRoutes(['/a/1', '/a/2'], [{ pattern: '/a/', max: 1 }]);
+
+if (limited.join() !== '/a/1' || typeof playwright.smokeFixtures !== 'function') {
+  throw new Error(`require() returned unexpected exports: ${JSON.stringify(limited)}`);
+}
+
+console.info('require() of @smartive/utils/testing and /testing/playwright works');
diff --git a/e2e/server.ts b/e2e/server.ts
new file mode 100644
index 0000000..4e8ac0b
--- /dev/null
+++ b/e2e/server.ts
@@ -0,0 +1,90 @@
+import { createServer } from 'node:http';
+
+/**
+ * Fixture site for the e2e tests. `127.0.0.1` stands in for an allowlisted CMS host
+ * (same server, different origin than `localhost`), and `tracker.invalid` for a tracker
+ * that must be blocked before it is ever resolved.
+ */
+const PORT = Number(process.env.PORT ?? 4173);
+const ORIGIN = `http://localhost:${PORT}`;
+
+const page = (body: string) =>
+  `<!doctype html><html lang="en"><head><title>fixture</title></head><body>${body}</body></html>`;
+
+const urlset = (paths: string[]) =>
+  `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+${paths.map((path) => `<url><loc>https://prod.example.com${path}</loc></url>`).join('\n')}
+<url><loc>https://prod.example.com/de</loc><xhtml:link rel="alternate" hreflang="fr" href="https://prod.example.com/fr"/></url>
+</urlset>`;
+
+const routes: Record<string, () => { status?: number; type?: string; body: string }> = {
+  '/sitemap.xml': () => ({
+    type: 'application/xml',
+    body: `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+<sitemap><loc>https://prod.example.com/sitemap-pages.xml</loc></sitemap>
+</sitemapindex>`,
+  }),
+  '/sitemap-pages.xml': () => ({ type: 'application/xml', body: urlset(['/', '/blog/a', '/blog/b', '/blog/c']) }),
+  '/': () => ({ body: page('<h1>Home</h1>') }),
+  '/blog/a': () => ({ body: page('<h1>A</h1>') }),
+  '/blog/b': () => ({ body: page('<h1>B</h1>') }),
+  '/blog/c': () => ({ body: page('<h1>C</h1>') }),
+  '/de': () => ({ body: page('<h1>DE</h1>') }),
+  '/fr': () => ({ body: page('<h1>FR</h1>') }),
+  '/console-error': () => ({ body: page('<script>console.error("client boom")</script>') }),
+  '/console-warning': () => ({ body: page('<script>console.warn("careful")</script>') }),
+  '/page-error': () => ({ body: page('<script>setTimeout(() => { throw new Error("uncaught boom") }, 0)</script>') }),
+  '/rejection': () => ({ body: page('<script>Promise.reject(new Error("unhandled rejection"))</script>') }),
+  '/missing-asset': () => ({ body: page('<img src="/missing.png" alt="">') }),
+  '/third-party': () => ({
+    body: page(
+      `<script src="http://tracker.invalid/t.js"></script><script src="http://127.0.0.1:${PORT}/allowed.js"></script>`,
+    ),
+  }),
+  '/allowed.js': () => ({ type: 'text/javascript', body: 'window.allowedLoaded = true;' }),
+  '/aborted': () => ({
+    body: page(
+      '<script>const c = new AbortController(); fetch("/slow", { signal: c.signal }).catch(() => {}); c.abort();</script>',
+    ),
+  }),
+  '/slow': () => ({ type: 'text/plain', body: 'slow' }),
+  '/broken-request': () => ({ body: page('<script>fetch("/drop").catch(() => {})</script>') }),
+  '/redirect': () => ({ status: 308, body: '' }),
+};
+
+createServer((request, response) => {
+  const { pathname } = new URL(request.url ?? '/', ORIGIN);
+
+  if (pathname === '/drop') {
+    request.socket.destroy();
+
+    return;
+  }
+
+  const route = routes[pathname];
+
+  if (!route) {
+    response.writeHead(404, { 'Content-Type': 'text/plain' }).end('not found');
+
+    return;
+  }
+
+  const { status = 200, type = 'text/html; charset=utf-8', body } = route();
+  const headers: Record<string, string> = { 'Content-Type': type };
+
+  if (status === 308) {
+    headers.Location = '/';
+  }
+
+  if (pathname === '/slow') {
+    setTimeout(() => response.writeHead(status, headers).end(body), 2000);
+
+    return;
+  }
+
+  response.writeHead(status, headers).end(body);
+}).listen(PORT, () => {
+  console.info(`fixture server on ${ORIGIN}`);
+});
diff --git a/e2e/tsconfig.json b/e2e/tsconfig.json
new file mode 100644
index 0000000..2c98a3e
--- /dev/null
+++ b/e2e/tsconfig.json
@@ -0,0 +1,13 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "..",
+    "noEmit": true,
+    "types": ["node"],
+    "allowImportingTsExtensions": true,
+    // No `paths` override: the package's own subpaths resolve to dist like in a consumer project,
+    // so this config is type-checked and linted after the build (see `pretest:e2e`).
+    "paths": {}
+  },
+  "include": ["./**/*"]
+}
diff --git a/package-lock.json b/package-lock.json
index bb70c9c..14233c3 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -11,6 +11,7 @@
       "devDependencies": {
         "@datocms/cda-client": "0.3.2",
         "@neondatabase/serverless": "1.2.0",
+        "@playwright/test": "1.64.0",
         "@smartive/eslint-config": "10.0.0",
         "@smartive/prettier-config": "3.1.2",
         "@types/node": "24.19.1",
@@ -28,6 +29,7 @@
       "peerDependencies": {
         "@datocms/cda-client": "^0.2.10 || ^0.3.0",
         "@neondatabase/serverless": "^1.0.0",
+        "@playwright/test": "^1.50.0",
         "next": "^15.0.0 || ^16.0.0"
       },
       "peerDependenciesMeta": {
@@ -37,6 +39,9 @@
         "@neondatabase/serverless": {
           "optional": true
         },
+        "@playwright/test": {
+          "optional": true
+        },
         "next": {
           "optional": true
         }
@@ -1340,6 +1345,22 @@
         "url": "https://opencollective.com/pkgr"
       }
     },
+    "node_modules/@playwright/test": {
+      "version": "1.64.0",
+      "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.64.0.tgz",
+      "integrity": "sha512-oTN9FNYuN6bqQMwiho6jJKLCG2/QOYCixGXuCjRmzOq23eODeukuY2XiAVoVpAECbuezMt1MHQjAiQxK8F+Y+g==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright": "1.64.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/@rolldown/binding-android-arm-eabi": {
       "version": "1.2.12",
       "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm-eabi/-/binding-android-arm-eabi-1.2.12.tgz",
@@ -4502,6 +4523,35 @@
         "url": "https://github.com/sponsors/jonschlinkert"
       }
     },
+    "node_modules/playwright": {
+      "version": "1.64.0",
+      "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.64.0.tgz",
+      "integrity": "sha512-kVzTnYFYEyQ9RGzBjNCd2+yEqWmVbxl3AHPynv3qQ6JTjv4a+kwRcnqQwIpuP3NnrnIrE/Q6wWAIAvMfIE2/Yg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "dependencies": {
+        "playwright-core": "1.64.0"
+      },
+      "bin": {
+        "playwright": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/playwright-core": {
+      "version": "1.64.0",
+      "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.64.0.tgz",
+      "integrity": "sha512-T9r+MZkTECl2+oUcZ26YgZzTrYidTsIhYYkJix+6iDOymOb1FB2RLLSOxRGnZGv5DStt+aduIVbt+E8WygXYpg==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "bin": {
+        "playwright-core": "cli.js"
+      },
+      "engines": {
+        "node": ">=20"
+      }
+    },
     "node_modules/postcss": {
       "version": "8.5.28",
       "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.28.tgz",
diff --git a/package.json b/package.json
index 7bdf30a..afef02b 100644
--- a/package.json
+++ b/package.json
@@ -33,6 +33,16 @@
     "./next": {
       "types": "./dist/next/index.d.ts",
       "import": "./dist/next/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js",
+      "default": "./dist/testing/index.js"
+    },
+    "./testing/playwright": {
+      "types": "./dist/testing/playwright.d.ts",
+      "import": "./dist/testing/playwright.js",
+      "default": "./dist/testing/playwright.js"
     }
   },
   "files": [
@@ -45,9 +55,11 @@
     "prebuild": "npm run clean",
     "build": "tsc -p tsconfig.build.json",
     "lint": "eslint src",
-    "prettier": "prettier --check src",
+    "prettier": "prettier --check src e2e",
     "test": "vitest run",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "pretest:e2e": "npm run build && tsc -p e2e/tsconfig.json && eslint e2e",
+    "test:e2e": "node e2e/require-check.cts && playwright test -c e2e/playwright.config.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -58,7 +70,9 @@
     "datocms",
     "nextjs",
     "cache-components",
-    "cache-tags"
+    "cache-tags",
+    "playwright",
+    "smoke-test"
   ],
   "author": "smartive AG",
   "license": "MIT",
@@ -69,6 +83,7 @@
   "peerDependencies": {
     "@datocms/cda-client": "^0.2.10 || ^0.3.0",
     "@neondatabase/serverless": "^1.0.0",
+    "@playwright/test": "^1.50.0",
     "next": "^15.0.0 || ^16.0.0"
   },
   "peerDependenciesMeta": {
@@ -80,6 +95,9 @@
     },
     "next": {
       "optional": true
+    },
+    "@playwright/test": {
+      "optional": true
     }
   },
   "overrides": {
@@ -90,6 +108,7 @@
   "devDependencies": {
     "@datocms/cda-client": "0.3.2",
     "@neondatabase/serverless": "1.2.0",
+    "@playwright/test": "1.64.0",
     "@smartive/eslint-config": "10.0.0",
     "@smartive/prettier-config": "3.1.2",
     "@types/node": "24.19.1",
diff --git a/src/testing/http-check.test.ts b/src/testing/http-check.test.ts
new file mode 100644
index 0000000..cb46dbd
--- /dev/null
+++ b/src/testing/http-check.test.ts
@@ -0,0 +1,118 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { checkUrls, formatUrlCheckFailures } from './http-check.js';
+
+const statusResponse = (status: number) => new Response(status === 204 || status === 304 ? null : 'body', { status });
+
+describe('checkUrls', () => {
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it('reports each URL with its status, in input order', async () => {
+    const statuses: Record<string, number> = { 'https://example.com/a': 200, 'https://example.com/b': 404 };
+    const fetchFn = vi.fn((input: RequestInfo | URL) => Promise.resolve(statusResponse(statuses[input as string])));
+
+    await expect(checkUrls(['https://example.com/a', 'https://example.com/b'], { fetchFn })).resolves.toEqual([
+      { url: 'https://example.com/a', status: 200, ok: true },
+      { url: 'https://example.com/b', status: 404, ok: false },
+    ]);
+  });
+
+  it('does not follow redirects, so a redirect fails the check', async () => {
+    const fetchFn = vi.fn().mockResolvedValue(new Response(null, { status: 308, headers: { Location: '/elsewhere' } }));
+
+    const [result] = await checkUrls(['https://example.com/old'], { fetchFn });
+
+    expect(result).toMatchObject({ status: 308, ok: false });
+    expect(fetchFn.mock.calls[0][1]).toMatchObject({ redirect: 'manual' });
+  });
+
+  it('rewrites hosts to the base URL', async () => {
+    const fetchFn = vi.fn().mockResolvedValue(statusResponse(200));
+
+    const [result] = await checkUrls(['https://prod.example.com/a?x=1'], { baseURL: 'http://localhost:3000', fetchFn });
+
+    expect(result.url).toBe('http://localhost:3000/a?x=1');
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/a?x=1', expect.anything());
+  });
+
+  it('retries 5xx and network errors, but not 4xx', async () => {
+    vi.useFakeTimers();
+
+    const fetchFn = vi.fn((input: RequestInfo | URL) => {
+      const url = input as string;
+
+      if (url.endsWith('/flaky')) {
+        return Promise.resolve(
+          statusResponse(fetchFn.mock.calls.filter(([called]) => called === url).length === 1 ? 502 : 200),
+        );
+      }
+
+      if (url.endsWith('/down')) {
+        return Promise.reject(new TypeError('fetch failed'));
+      }
+
+      return Promise.resolve(statusResponse(404));
+    });
+
+    const promise = checkUrls(['https://example.com/flaky', 'https://example.com/down', 'https://example.com/gone'], {
+      retries: 1,
+      fetchFn,
+    });
+    await vi.runAllTimersAsync();
+
+    await expect(promise).resolves.toEqual([
+      { url: 'https://example.com/flaky', status: 200, ok: true },
+      { url: 'https://example.com/down', status: null, ok: false, error: 'fetch failed' },
+      { url: 'https://example.com/gone', status: 404, ok: false },
+    ]);
+    expect(fetchFn).toHaveBeenCalledTimes(5);
+  });
+
+  it('keeps at most `concurrency` requests in flight', async () => {
+    let inFlight = 0;
+    let maxInFlight = 0;
+    const fetchFn = vi.fn(async () => {
+      inFlight += 1;
+      maxInFlight = Math.max(maxInFlight, inFlight);
+      await new Promise((resolve) => setTimeout(resolve, 1));
+      inFlight -= 1;
+
+      return statusResponse(200);
+    });
+
+    const results = await checkUrls(
+      Array.from({ length: 10 }, (_, index) => `https://example.com/${index}`),
+      { concurrency: 3, fetchFn },
+    );
+
+    expect(results).toHaveLength(10);
+    expect(results.every(({ ok }) => ok)).toBe(true);
+    expect(maxInFlight).toBe(3);
+  });
+
+  it('accepts a different expected status', async () => {
+    const fetchFn = vi.fn().mockResolvedValue(statusResponse(204));
+
+    await expect(checkUrls(['https://example.com/'], { expectedStatus: 204, fetchFn })).resolves.toEqual([
+      { url: 'https://example.com/', status: 204, ok: true },
+    ]);
+  });
+
+  it('returns no results for no URLs', async () => {
+    await expect(checkUrls([], { fetchFn: vi.fn() })).resolves.toEqual([]);
+  });
+});
+
+describe('formatUrlCheckFailures', () => {
+  it('lists only failures, one per line', () => {
+    expect(
+      formatUrlCheckFailures([
+        { url: 'https://example.com/a', status: 200, ok: true },
+        { url: 'https://example.com/b', status: 404, ok: false },
+        { url: 'https://example.com/c', status: null, ok: false, error: 'fetch failed' },
+      ]),
+    ).toBe('404 https://example.com/b\nno response https://example.com/c (fetch failed)');
+  });
+});
diff --git a/src/testing/http-check.ts b/src/testing/http-check.ts
new file mode 100644
index 0000000..0102fc4
--- /dev/null
+++ b/src/testing/http-check.ts
@@ -0,0 +1,96 @@
+import { toPath } from './routes.js';
+
+export type CheckUrlsOptions = {
+  /** When set, each URL's host is replaced by it, so production sitemap URLs can be checked locally. */
+  baseURL?: string;
+  /** Requests in flight at once. Default 8. */
+  concurrency?: number;
+  /** Default 200. Redirects are not followed, so a redirecting URL fails the check. */
+  expectedStatus?: number;
+  /** Extra attempts after a network error or a 5xx. Default 1. Other statuses are final. */
+  retries?: number;
+  /** Per request. Default 30 seconds. */
+  timeoutMs?: number;
+  fetchFn?: typeof fetch;
+};
+
+export type UrlCheckResult = {
+  url: string;
+  /** `null` when no response arrived. */
+  status: number | null;
+  ok: boolean;
+  error?: string;
+};
+
+const DEFAULT_CONCURRENCY = 8;
+const DEFAULT_RETRIES = 1;
+const DEFAULT_TIMEOUT_MS = 30_000;
+const RETRY_DELAY_MS = 500;
+
+const wait = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Requests every URL without a browser and reports its status. Cheap enough to cover the
+ * full sitemap where the browser test only samples it.
+ *
+ * Never throws: every URL yields a result, so the caller can report all failures at once.
+ */
+export const checkUrls = async (
+  urls: readonly string[],
+  {
+    baseURL,
+    concurrency = DEFAULT_CONCURRENCY,
+    expectedStatus = 200,
+    retries = DEFAULT_RETRIES,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchFn = fetch,
+  }: CheckUrlsOptions = {},
+): Promise<UrlCheckResult[]> => {
+  const check = async (url: string): Promise<UrlCheckResult> => {
+    for (let attempt = 0; ; attempt++) {
+      const isLastAttempt = attempt >= retries;
+
+      try {
+        const response = await fetchFn(url, { redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+        // Only the status matters; release the connection instead of buffering the page.
+        await response.body?.cancel();
+
+        if (response.status >= 500 && !isLastAttempt) {
+          await wait(RETRY_DELAY_MS);
+          continue;
+        }
+
+        return { url, status: response.status, ok: response.status === expectedStatus };
+      } catch (error) {
+        if (!isLastAttempt) {
+          await wait(RETRY_DELAY_MS);
+          continue;
+        }
+
+        return { url, status: null, ok: false, error: error instanceof Error ? error.message : String(error) };
+      }
+    }
+  };
+
+  const targets = urls.map((url) => (baseURL ? new URL(toPath(url), baseURL).toString() : url));
+  const results = new Array<UrlCheckResult>(targets.length);
+  let next = 0;
+
+  const worker = async () => {
+    while (next < targets.length) {
+      const index = next++;
+      results[index] = await check(targets[index]);
+    }
+  };
+
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(concurrency, targets.length)) }, worker));
+
+  return results;
+};
+
+/** One line per failed URL, for an assertion message that lists every problem at once. */
+export const formatUrlCheckFailures = (results: readonly UrlCheckResult[]): string =>
+  results
+    .filter(({ ok }) => !ok)
+    .map(({ url, status, error }) => `${status ?? 'no response'} ${url}${error ? ` (${error})` : ''}`)
+    .join('\n');
diff --git a/src/testing/ignore.test.ts b/src/testing/ignore.test.ts
new file mode 100644
index 0000000..6ca4731
--- /dev/null
+++ b/src/testing/ignore.test.ts
@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+
+import { isIgnored } from './ignore.js';
+
+describe('isIgnored', () => {
+  const entry = { text: 'Error: no level with compatible codecs found', location: 'https://cdn.example.com/player.js' };
+
+  it('matches a string rule against the text', () => {
+    expect(isIgnored(entry, ['compatible codecs'])).toBe(true);
+  });
+
+  it('matches a plain rule against the location', () => {
+    expect(isIgnored(entry, ['cdn.example.com'])).toBe(true);
+    expect(isIgnored(entry, [/player\.js$/])).toBe(true);
+  });
+
+  it('does not ignore unmatched entries', () => {
+    expect(isIgnored(entry, ['hydration', /usercentrics/])).toBe(false);
+    expect(isIgnored(entry, [])).toBe(false);
+  });
+
+  it('requires every field of an object rule to match', () => {
+    expect(isIgnored(entry, [{ message: 'codecs', location: 'cdn.example.com' }])).toBe(true);
+    expect(isIgnored(entry, [{ message: 'codecs', location: 'other.example.com' }])).toBe(false);
+    expect(isIgnored(entry, [{ location: /cdn\./ }])).toBe(true);
+  });
+
+  it('never ignores with an empty object rule', () => {
+    expect(isIgnored(entry, [{}])).toBe(false);
+  });
+
+  it('handles entries without a location', () => {
+    expect(isIgnored({ text: 'boom' }, ['example.com'])).toBe(false);
+    expect(isIgnored({ text: 'boom' }, [{ location: 'x' }])).toBe(false);
+  });
+});
diff --git a/src/testing/ignore.ts b/src/testing/ignore.ts
new file mode 100644
index 0000000..e697f2d
--- /dev/null
+++ b/src/testing/ignore.ts
@@ -0,0 +1,32 @@
+import { matchesPattern, type Pattern } from './patterns.js';
+
+/**
+ * A plain pattern ignores an entry when it matches the message text **or** the location.
+ * An object ignores an entry only when every given field matches, e.g. one message from
+ * one script.
+ */
+export type IgnoreRule = Pattern | { message?: Pattern; location?: Pattern };
+
+export type IgnoreCandidate = {
+  text: string;
+  location?: string;
+};
+
+const matchesRule = ({ text, location = '' }: IgnoreCandidate, rule: IgnoreRule): boolean => {
+  if (typeof rule === 'string' || rule instanceof RegExp) {
+    return matchesPattern(text, rule) || (location !== '' && matchesPattern(location, rule));
+  }
+
+  // An empty object would otherwise match everything and silently disable the check.
+  if (rule.message === undefined && rule.location === undefined) {
+    return false;
+  }
+
+  return (
+    (rule.message === undefined || matchesPattern(text, rule.message)) &&
+    (rule.location === undefined || matchesPattern(location, rule.location))
+  );
+};
+
+export const isIgnored = (candidate: IgnoreCandidate, rules: readonly IgnoreRule[]): boolean =>
+  rules.some((rule) => matchesRule(candidate, rule));
diff --git a/src/testing/index.ts b/src/testing/index.ts
new file mode 100644
index 0000000..1022eb5
--- /dev/null
+++ b/src/testing/index.ts
@@ -0,0 +1,5 @@
+export { checkUrls, formatUrlCheckFailures, type CheckUrlsOptions, type UrlCheckResult } from './http-check.js';
+export { isIgnored, type IgnoreCandidate, type IgnoreRule } from './ignore.js';
+export { matchesPattern, type Pattern } from './patterns.js';
+export { excludeRoutes, limitRoutes, toPath, type RouteLimit } from './routes.js';
+export { fetchSitemapRoutes, parseSitemap, type FetchSitemapRoutesOptions, type ParsedSitemap } from './sitemap.js';
diff --git a/src/testing/patterns.test.ts b/src/testing/patterns.test.ts
new file mode 100644
index 0000000..4eb7023
--- /dev/null
+++ b/src/testing/patterns.test.ts
@@ -0,0 +1,29 @@
+import { describe, expect, it } from 'vitest';
+
+import { matchesAnyPattern, matchesPattern } from './patterns.js';
+
+describe('matchesPattern', () => {
+  it('matches strings as substrings', () => {
+    expect(matchesPattern('/arbeiten/foo', '/arbeiten/')).toBe(true);
+    expect(matchesPattern('/kompetenzen/foo', '/arbeiten/')).toBe(false);
+  });
+
+  it('tests regular expressions', () => {
+    expect(matchesPattern('/de/produkte/x', /^\/de\//)).toBe(true);
+    expect(matchesPattern('/fr/produits/x', /^\/de\//)).toBe(false);
+  });
+
+  it('gives the same answer every time for global regular expressions', () => {
+    const pattern = /foo/g;
+
+    expect([1, 2, 3].map(() => matchesPattern('foo', pattern))).toEqual([true, true, true]);
+  });
+});
+
+describe('matchesAnyPattern', () => {
+  it('matches when any pattern does', () => {
+    expect(matchesAnyPattern('/news/a', ['/event/', /^\/news\//])).toBe(true);
+    expect(matchesAnyPattern('/about', ['/event/', /^\/news\//])).toBe(false);
+    expect(matchesAnyPattern('/about', [])).toBe(false);
+  });
+});
diff --git a/src/testing/patterns.ts b/src/testing/patterns.ts
new file mode 100644
index 0000000..25a1561
--- /dev/null
+++ b/src/testing/patterns.ts
@@ -0,0 +1,19 @@
+/** A `string` matches as a substring, a `RegExp` via `test()`. */
+export type Pattern = string | RegExp;
+
+/**
+ * `RegExp.prototype.test` is stateful for `g` and `y` flags (it advances `lastIndex`), so
+ * the same rule would alternate between matching and not matching across calls.
+ */
+export const matchesPattern = (value: string, pattern: Pattern): boolean => {
+  if (typeof pattern === 'string') {
+    return value.includes(pattern);
+  }
+
+  pattern.lastIndex = 0;
+
+  return pattern.test(value);
+};
+
+export const matchesAnyPattern = (value: string, patterns: readonly Pattern[]): boolean =>
+  patterns.some((pattern) => matchesPattern(value, pattern));
diff --git a/src/testing/playwright.test.ts b/src/testing/playwright.test.ts
new file mode 100644
index 0000000..68e41e9
--- /dev/null
+++ b/src/testing/playwright.test.ts
@@ -0,0 +1,339 @@
+import { EventEmitter } from 'node:events';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { FullConfig, Page, TestInfo } from '@playwright/test';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import {
+  readRoutes,
+  smokeFixtures,
+  smokeGlobalSetup,
+  writeRoutes,
+  type SmokeOptions,
+  type SmokeState,
+} from './playwright.js';
+
+type RouteHandler = (route: ReturnType<typeof createRoute>) => Promise<void>;
+
+const createRoute = (url: string, { navigation = false } = {}) => ({
+  request: () => ({ url: () => url, isNavigationRequest: () => navigation, frame: () => mainFrame }),
+  fallback: vi.fn(() => Promise.resolve()),
+  abort: vi.fn(() => Promise.resolve()),
+});
+
+const mainFrame = {};
+
+const createPage = () => {
+  const emitter = new EventEmitter();
+  let handler: RouteHandler | undefined;
+
+  const page = Object.assign(emitter, {
+    url: () => 'http://localhost:3000/page',
+    mainFrame: () => mainFrame,
+    route: vi.fn((_pattern: string, routeHandler: RouteHandler) => {
+      handler = routeHandler;
+
+      return Promise.resolve();
+    }),
+  });
+
+  return {
+    page,
+    request: async (url: string, options?: { navigation?: boolean }) => {
+      const route = createRoute(url, options);
+      await handler?.(route);
+
+      return route;
+    },
+    console: (type: string, text: string, url = '') =>
+      emitter.emit('console', { type: () => type, text: () => text, location: () => ({ url }) }),
+  };
+};
+
+const createTestInfo = () => ({ annotations: [] as TestInfo['annotations'], attach: vi.fn(() => Promise.resolve()) });
+
+/** Runs the `smoke` fixture with `body` as the test, returning the outcome of its teardown. */
+const runSmoke = (
+  body: (fake: ReturnType<typeof createPage>, state: SmokeState) => Promise<void> | void,
+  { options = {}, baseURL = 'http://localhost:3000' }: { options?: SmokeOptions; baseURL?: string | null } = {},
+) => {
+  const fake = createPage();
+  const testInfo = createTestInfo();
+  const [fixture] = smokeFixtures(options).smoke as unknown as [
+    (args: object, use: (state: SmokeState) => Promise<void>, testInfo: object) => Promise<void>,
+  ];
+  let state: SmokeState | undefined;
+
+  const result = fixture(
+    { page: fake.page as unknown as Page, baseURL: baseURL ?? undefined, smokeOptions: options },
+    async (smokeState) => {
+      state = smokeState;
+      await body(fake, smokeState);
+    },
+    testInfo,
+  );
+
+  return { result, testInfo, getState: () => state! };
+};
+
+describe('smokeFixtures', () => {
+  it('exposes the options as an overridable option fixture', () => {
+    const options = { ignore: ['noise'] };
+
+    expect(smokeFixtures(options).smokeOptions).toEqual([options, { option: true }]);
+  });
+
+  it('allows first-party, allowlisted and non-http requests and blocks the rest', async () => {
+    const { result, testInfo, getState } = runSmoke(
+      async ({ request }) => {
+        expect((await request('http://localhost:3000/_next/app.js')).fallback).toHaveBeenCalled();
+        expect((await request('https://www.datocms-assets.com/1/a.jpg')).fallback).toHaveBeenCalled();
+        expect((await request('https://stream.mux.com/x/high.mp4')).fallback).toHaveBeenCalled();
+        expect((await request('data:image/png;base64,AAAA')).fallback).toHaveBeenCalled();
+
+        const tracker = await request('https://www.googletagmanager.com/gtm.js?id=GTM-1');
+        expect(tracker.abort).toHaveBeenCalledWith('blockedbyclient');
+        expect(tracker.fallback).not.toHaveBeenCalled();
+
+        await request('http://localhost:4000/other-port.js');
+        await request('https://datocms-assets.com.evil.example/x.js');
+      },
+      { options: { allowHosts: ['*.datocms-assets.com', /^stream\.mux\.com$/] } },
+    );
+
+    await expect(result).resolves.toBeUndefined();
+    expect([...getState().blockedUrls]).toHaveLength(3);
+    expect(testInfo.annotations).toEqual([
+      {
+        type: 'blocked hosts',
+        description: 'datocms-assets.com.evil.example, localhost:4000, www.googletagmanager.com',
+      },
+    ]);
+  });
+
+  it('passes without issues and attaches nothing', async () => {
+    const { result, testInfo } = runSmoke(({ console }) => {
+      console('log', 'hello');
+      console('info', 'hello');
+    });
+
+    await expect(result).resolves.toBeUndefined();
+    expect(testInfo.attach).not.toHaveBeenCalled();
+  });
+
+  it('fails on console errors and warnings by default', async () => {
+    const { result, testInfo } = runSmoke(({ console }) => {
+      console('error', 'Hydration failed', 'http://localhost:3000/_next/app.js');
+      console('warning', 'Deprecated thing');
+    });
+
+    await expect(result).rejects.toThrow(
+      /2 issue\(s\) on http:\/\/localhost:3000\/page:\n {2}\[console-error\] Hydration failed \(http:\/\/localhost:3000\/_next\/app\.js\)\n {2}\[console-warning\] Deprecated thing/,
+    );
+    expect(testInfo.attach).toHaveBeenCalledWith(
+      'smoke-issues.json',
+      expect.objectContaining({ contentType: 'application/json' }),
+    );
+  });
+
+  it('only fails on the configured console types', async () => {
+    const { result, getState } = runSmoke(
+      ({ console }) => {
+        console('warning', 'Deprecated thing');
+      },
+      { options: { failOn: ['error'] } },
+    );
+
+    await expect(result).resolves.toBeUndefined();
+    expect(getState().issues).toEqual([]);
+  });
+
+  it('skips ignored and duplicate messages', async () => {
+    const { result, getState } = runSmoke(
+      ({ console }) => {
+        console('warning', "Please ensure that the container has a non-static position, like 'relative'");
+        console('error', 'from a script', 'https://plausible.io/js/script.js');
+        console('error', 'boom');
+        console('error', 'boom');
+      },
+      { options: { ignore: ['non-static position', { location: 'plausible.io' }] } },
+    );
+
+    await expect(result).rejects.toThrow('1 issue(s)');
+    expect(getState().issues).toEqual([{ type: 'console-error', text: 'boom', location: undefined }]);
+  });
+
+  it('skips console errors caused by blocked requests', async () => {
+    const { result } = runSmoke(async ({ request, console }) => {
+      await request('https://connect.facebook.net/en_US/fbevents.js');
+      console(
+        'error',
+        'Failed to load resource: net::ERR_BLOCKED_BY_CLIENT',
+        'https://connect.facebook.net/en_US/fbevents.js',
+      );
+    });
+
+    await expect(result).resolves.toBeUndefined();
+  });
+
+  it('reports failed first-party responses once, with their status', async () => {
+    const { result, getState } = runSmoke(({ page, console }) => {
+      page.emit('response', { url: () => 'http://localhost:3000/missing.png', status: () => 404 });
+      page.emit('response', { url: () => 'http://localhost:3000/ok.png', status: () => 200 });
+      page.emit('response', { url: () => 'https://www.datocms-assets.com/gone.png', status: () => 404 });
+      console(
+        'error',
+        'Failed to load resource: the server responded with a status of 404 (Not Found)',
+        'http://localhost:3000/missing.png',
+      );
+    });
+
+    await expect(result).rejects.toThrow('1 issue(s)');
+    expect(getState().issues).toEqual([
+      {
+        type: 'response',
+        text: 'HTTP 404 http://localhost:3000/missing.png',
+        location: 'http://localhost:3000/missing.png',
+      },
+    ]);
+  });
+
+  it('reports failed first-party requests except expected aborts', async () => {
+    const failed = (url: string, errorText: string) => ({ url: () => url, failure: () => ({ errorText }) });
+
+    const { result, getState } = runSmoke(({ page }) => {
+      page.emit('requestfailed', failed('http://localhost:3000/video.mp4', 'net::ERR_ABORTED'));
+      page.emit('requestfailed', failed('https://www.googletagmanager.com/gtm.js', 'net::ERR_BLOCKED_BY_CLIENT'));
+      page.emit('requestfailed', failed('https://third.example/x.js', 'net::ERR_NAME_NOT_RESOLVED'));
+      page.emit('requestfailed', failed('http://localhost:3000/api/data', 'net::ERR_EMPTY_RESPONSE'));
+    });
+
+    await expect(result).rejects.toThrow('1 issue(s)');
+    expect(getState().issues).toEqual([
+      {
+        type: 'requestfailed',
+        text: 'net::ERR_EMPTY_RESPONSE http://localhost:3000/api/data',
+        location: 'http://localhost:3000/api/data',
+      },
+    ]);
+  });
+
+  it('does not check first-party requests when disabled', async () => {
+    const { result } = runSmoke(
+      ({ page }) => {
+        page.emit('response', { url: () => 'http://localhost:3000/missing.png', status: () => 404 });
+      },
+      { options: { checkFirstPartyRequests: false } },
+    );
+
+    await expect(result).resolves.toBeUndefined();
+  });
+
+  it('reports uncaught exceptions with the script location', async () => {
+    const error = new Error('Minified React error #418');
+    error.stack = 'Error: Minified React error #418\n    at x (http://localhost:3000/_next/static/chunks/app.js:1:2345)';
+
+    const { result, getState } = runSmoke(({ page }) => {
+      page.emit('pageerror', error);
+    });
+
+    await expect(result).rejects.toThrow('[pageerror] Minified React error #418');
+    expect(getState().issues[0].location).toBe('http://localhost:3000/_next/static/chunks/app.js');
+  });
+
+  it('passes when the test consumed the issues it expected', async () => {
+    const { result } = runSmoke(({ console }, state) => {
+      console('error', 'expected');
+      expect(state.issues).toHaveLength(1);
+      state.issues.length = 0;
+    });
+
+    await expect(result).resolves.toBeUndefined();
+  });
+
+  it('takes the first party from the first navigation without a baseURL', async () => {
+    const { result, getState } = runSmoke(
+      async ({ request }) => {
+        expect((await request('https://example.com/', { navigation: true })).fallback).toHaveBeenCalled();
+        expect((await request('https://example.com/app.js')).fallback).toHaveBeenCalled();
+        expect((await request('https://other.example/app.js')).abort).toHaveBeenCalled();
+      },
+      { baseURL: null },
+    );
+
+    await expect(result).resolves.toBeUndefined();
+    expect([...getState().blockedUrls]).toEqual(['https://other.example/app.js']);
+  });
+});
+
+describe('writeRoutes / readRoutes', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'smoke-routes-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('round-trips routes, creating missing directories', () => {
+    const file = join(dir, 'nested', 'routes.json');
+    writeRoutes(['/', '/a'], file);
+
+    expect(readRoutes(file)).toEqual(['/', '/a']);
+  });
+
+  it('returns no routes when the file is missing', () => {
+    expect(readRoutes(join(dir, 'missing.json'))).toEqual([]);
+  });
+
+  it('ignores anything that is not a list of strings', () => {
+    const file = join(dir, 'routes.json');
+    writeFileSync(file, JSON.stringify(['/', 1, null]));
+
+    expect(readRoutes(file)).toEqual(['/']);
+  });
+});
+
+describe('smokeGlobalSetup', () => {
+  let dir: string;
+
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), 'smoke-setup-'));
+  });
+
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  const config = (baseURL?: string) => ({ projects: [{ use: {} }, { use: { baseURL } }] }) as unknown as FullConfig;
+  const sitemap = () =>
+    new Response(
+      '<urlset><url><loc>https://prod.example.com/</loc></url><url><loc>https://prod.example.com/a</loc></url></urlset>',
+    );
+
+  it('writes the sitemap routes of the configured baseURL', async () => {
+    const file = join(dir, 'routes.json');
+    const fetchFn = vi.fn(() => Promise.resolve(sitemap()));
+
+    await smokeGlobalSetup({ file, fetchFn })(config('http://localhost:3333'));
+
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3333/sitemap.xml');
+    expect(readRoutes(file)).toEqual(['/', '/a']);
+  });
+
+  it('prefers an explicit baseURL', async () => {
+    const fetchFn = vi.fn(() => Promise.resolve(sitemap()));
+
+    await smokeGlobalSetup({ baseURL: 'https://prod.example.com', file: join(dir, 'r.json'), fetchFn })(config());
+
+    expect(fetchFn).toHaveBeenCalledWith('https://prod.example.com/sitemap.xml');
+  });
+
+  it('throws without a baseURL', async () => {
+    await expect(smokeGlobalSetup({ file: join(dir, 'r.json') })(config())).rejects.toThrow('needs a baseURL');
+  });
+});
diff --git a/src/testing/playwright.ts b/src/testing/playwright.ts
new file mode 100644
index 0000000..bd152d1
--- /dev/null
+++ b/src/testing/playwright.ts
@@ -0,0 +1,300 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+import type {
+  Fixtures,
+  FullConfig,
+  Page,
+  PlaywrightTestArgs,
+  PlaywrightTestOptions,
+  PlaywrightWorkerArgs,
+  PlaywrightWorkerOptions,
+  Response,
+} from '@playwright/test';
+
+import { isIgnored, type IgnoreRule } from './ignore.js';
+import { fetchSitemapRoutes, type FetchSitemapRoutesOptions } from './sitemap.js';
+
+/** `'example.com'` matches exactly, `'*.example.com'` matches subdomains, a `RegExp` tests the hostname. */
+export type HostPattern = string | RegExp;
+
+export type SmokeOptions = {
+  /** Known noise. Checked against the message text and its location. */
+  ignore?: IgnoreRule[];
+  /** Console message types that fail the test. Default `['error', 'warning']`. Uncaught exceptions always do. */
+  failOn?: ('error' | 'warning')[];
+  /**
+   * Hosts allowed besides the `baseURL` origin, typically CMS asset hosts. Every other
+   * request is aborted, so trackers, consent banners and embeds neither add console noise
+   * nor send hits from CI.
+   */
+  allowHosts?: HostPattern[];
+  /** Fail on first-party responses with status >= 400 and failed first-party requests. Default `true`. */
+  checkFirstPartyRequests?: boolean;
+};
+
+export type SmokeIssue = {
+  type: 'console-error' | 'console-warning' | 'pageerror' | 'response' | 'requestfailed';
+  text: string;
+  location?: string;
+};
+
+export type SmokeState = {
+  /** Issues collected so far. A test may assert and then empty it to expect specific issues. */
+  issues: SmokeIssue[];
+  blockedUrls: Set<string>;
+};
+
+export type SmokeFixtures = {
+  /** Override per file or describe block with `test.use({ smokeOptions: { … } })`. */
+  smokeOptions: SmokeOptions;
+  smoke: SmokeState;
+};
+
+type TestArgs = PlaywrightTestArgs & PlaywrightTestOptions;
+type WorkerArgs = PlaywrightWorkerArgs & PlaywrightWorkerOptions;
+
+const DEFAULT_FAIL_ON: SmokeOptions['failOn'] = ['error', 'warning'];
+const DEFAULT_SETTLE_MS = 2000;
+const DEFAULT_ROUTES_FILE = 'node_modules/.cache/smartive-utils/smoke-routes.json';
+
+/**
+ * `ERR_BLOCKED_BY_CLIENT` is our own blocking. `ERR_ABORTED` is the browser cancelling a
+ * request it no longer needs: `<video>` drops range requests when it switches renditions,
+ * and closing the page aborts whatever is still in flight.
+ */
+const EXPECTED_FAILURES = new Set(['net::ERR_BLOCKED_BY_CLIENT', 'net::ERR_ABORTED']);
+
+const matchesHost = (hostname: string, pattern: HostPattern): boolean => {
+  if (typeof pattern !== 'string') {
+    pattern.lastIndex = 0;
+
+    return pattern.test(hostname);
+  }
+
+  return pattern.startsWith('*.') ? hostname.endsWith(pattern.slice(1)) : hostname === pattern;
+};
+
+const parseUrl = (url: string): URL | undefined => {
+  try {
+    return new URL(url);
+  } catch {
+    return undefined;
+  }
+};
+
+/** First script URL in a stack trace, without `:line:column`, so location ignore rules work for exceptions too. */
+const stackLocation = (stack: string | undefined): string | undefined =>
+  stack?.match(/https?:\/\/[^\s)]+/)?.[0].replace(/(:\d+){1,2}$/, '');
+
+const formatIssue = ({ type, text, location }: SmokeIssue): string =>
+  `  [${type}] ${text}${location && !text.includes(location) ? ` (${location})` : ''}`;
+
+/**
+ * Fixtures for `test.extend()` that fail a test on client-side errors.
+ *
+ * The `smoke` fixture is automatic: it blocks third-party requests, collects console
+ * messages, uncaught exceptions and failed first-party requests while the test runs, and
+ * fails the test afterwards with every issue that is not ignored.
+ *
+ * Only imports types from `@playwright/test`, so the project's own pinned version is the
+ * one that runs. Request interception disables the browser HTTP cache, which is what a
+ * smoke test wants anyway.
+ */
+export const smokeFixtures = (
+  options: SmokeOptions = {},
+): Fixtures<SmokeFixtures, Record<never, never>, TestArgs, WorkerArgs> => ({
+  smokeOptions: [options, { option: true }],
+  smoke: [
+    async ({ page, baseURL, smokeOptions }, use, testInfo) => {
+      const { ignore = [], failOn = DEFAULT_FAIL_ON, allowHosts = [], checkFirstPartyRequests = true } = smokeOptions;
+      const state: SmokeState = { issues: [], blockedUrls: new Set() };
+      const seen = new Set<string>();
+      let firstPartyOrigin = baseURL ? new URL(baseURL).origin : undefined;
+
+      const isFirstParty = (url: string) => firstPartyOrigin !== undefined && parseUrl(url)?.origin === firstPartyOrigin;
+
+      const isAllowed = (url: string) => {
+        const parsed = parseUrl(url);
+
+        if (!parsed || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+          return true;
+        }
+
+        return parsed.origin === firstPartyOrigin || allowHosts.some((pattern) => matchesHost(parsed.hostname, pattern));
+      };
+
+      const record = (issue: SmokeIssue) => {
+        const key = `${issue.type}\n${issue.text}\n${issue.location ?? ''}`;
+
+        if (seen.has(key) || isIgnored(issue, ignore)) {
+          return;
+        }
+
+        seen.add(key);
+        state.issues.push(issue);
+      };
+
+      await page.route('**/*', async (route) => {
+        const request = route.request();
+        const url = request.url();
+
+        // Without a baseURL, the first top-level document defines what counts as first party.
+        if (firstPartyOrigin === undefined && request.isNavigationRequest() && request.frame() === page.mainFrame()) {
+          firstPartyOrigin = parseUrl(url)?.origin;
+        }
+
+        if (isAllowed(url)) {
+          await route.fallback();
+
+          return;
+        }
+
+        state.blockedUrls.add(url);
+        await route.abort('blockedbyclient');
+      });
+
+      page.on('console', (message) => {
+        const type = message.type();
+
+        if ((type !== 'error' && type !== 'warning') || !failOn?.includes(type)) {
+          return;
+        }
+
+        const text = message.text();
+        const location = message.location().url || undefined;
+
+        if (location && state.blockedUrls.has(location)) {
+          return;
+        }
+
+        // Chromium logs failed loads too; the response and requestfailed handlers report them with the status.
+        if (checkFirstPartyRequests && text.startsWith('Failed to load resource') && location && isFirstParty(location)) {
+          return;
+        }
+
+        record({ type: type === 'error' ? 'console-error' : 'console-warning', text, location });
+      });
+
+      page.on('pageerror', (error) => {
+        record({ type: 'pageerror', text: error.message, location: stackLocation(error.stack) });
+      });
+
+      page.on('response', (response) => {
+        const url = response.url();
+
+        if (checkFirstPartyRequests && response.status() >= 400 && isFirstParty(url)) {
+          record({ type: 'response', text: `HTTP ${response.status()} ${url}`, location: url });
+        }
+      });
+
+      page.on('requestfailed', (request) => {
+        const url = request.url();
+        const errorText = request.failure()?.errorText ?? 'unknown error';
+
+        if (checkFirstPartyRequests && !EXPECTED_FAILURES.has(errorText) && isFirstParty(url)) {
+          record({ type: 'requestfailed', text: `${errorText} ${url}`, location: url });
+        }
+      });
+
+      await use(state);
+
+      const blockedHosts = [...new Set([...state.blockedUrls].map((url) => parseUrl(url)?.host ?? url))].sort();
+
+      if (blockedHosts.length > 0) {
+        testInfo.annotations.push({ type: 'blocked hosts', description: blockedHosts.join(', ') });
+      }
+
+      if (state.issues.length > 0) {
+        await testInfo.attach('smoke-issues.json', {
+          body: JSON.stringify(state.issues, null, 2),
+          contentType: 'application/json',
+        });
+
+        throw new Error(
+          `[testing] ${state.issues.length} issue(s) on ${page.url()}:\n${state.issues.map(formatIssue).join('\n')}`,
+        );
+      }
+    },
+    { auto: true },
+  ],
+});
+
+export type GotoAndSettleOptions = {
+  /** Time after `load` for hydration and client components to log errors. Default 2000 ms. */
+  settleMs?: number;
+  /** Navigation timeout. Defaults to the config's `navigationTimeout`. */
+  timeout?: number;
+};
+
+/**
+ * Navigates and waits a fixed settle time. Deliberately not `networkidle`: a playing
+ * `<video>` keeps a range request open indefinitely, so that state never arrives.
+ */
+export const gotoAndSettle = async (
+  page: Page,
+  path: string,
+  { settleMs = DEFAULT_SETTLE_MS, timeout }: GotoAndSettleOptions = {},
+): Promise<Response | null> => {
+  const response = await page.goto(path, { waitUntil: 'load', timeout });
+  await page.waitForTimeout(settleMs);
+
+  return response;
+};
+
+/**
+ * Persists the routes for {@link readRoutes}. Playwright loads test files after global
+ * setup, so a spec can generate one test per route from this file, and every worker sees
+ * the same list even if the sitemap changes mid-run.
+ */
+export const writeRoutes = (routes: readonly string[], file: string = DEFAULT_ROUTES_FILE): void => {
+  const path = resolve(file);
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(routes));
+};
+
+/**
+ * Reads the routes written by {@link writeRoutes}. Returns `[]` when the file is missing
+ * (e.g. `playwright test --list`, which skips global setup), which makes a real run fail
+ * with "No tests found" rather than pass silently.
+ */
+export const readRoutes = (file: string = DEFAULT_ROUTES_FILE): string[] => {
+  let content: string;
+
+  try {
+    content = readFileSync(resolve(file), 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+      return [];
+    }
+
+    throw error;
+  }
+
+  const routes: unknown = JSON.parse(content);
+
+  return Array.isArray(routes) ? routes.filter((route): route is string => typeof route === 'string') : [];
+};
+
+export type SmokeGlobalSetupOptions = Omit<FetchSitemapRoutesOptions, 'baseURL'> & {
+  /** Defaults to the first project's `use.baseURL`. */
+  baseURL?: string;
+  /** Where to write the routes. Must match {@link readRoutes}. */
+  file?: string;
+};
+
+/**
+ * Builds a `globalSetup` function that fetches the sitemap routes and writes them for
+ * {@link readRoutes}. Runs after `webServer` is up, so it can read the local sitemap.
+ */
+export const smokeGlobalSetup =
+  ({ baseURL, file, ...options }: SmokeGlobalSetupOptions = {}) =>
+  async (config: FullConfig): Promise<void> => {
+    const resolvedBaseURL = baseURL ?? config.projects.find((project) => project.use.baseURL)?.use.baseURL;
+
+    if (!resolvedBaseURL) {
+      throw new Error('[testing] smokeGlobalSetup needs a baseURL: set use.baseURL in the Playwright config or pass it');
+    }
+
+    writeRoutes(await fetchSitemapRoutes({ ...options, baseURL: resolvedBaseURL }), file);
+  };
diff --git a/src/testing/routes.test.ts b/src/testing/routes.test.ts
new file mode 100644
index 0000000..64c485a
--- /dev/null
+++ b/src/testing/routes.test.ts
@@ -0,0 +1,72 @@
+import { describe, expect, it } from 'vitest';
+
+import { excludeRoutes, limitRoutes, toPath } from './routes.js';
+
+describe('toPath', () => {
+  it('strips the origin and keeps the query', () => {
+    expect(toPath('https://robnicolas.ch/arbeiten/foo?x=1#top')).toBe('/arbeiten/foo?x=1');
+  });
+
+  it('keeps the root and trailing slashes', () => {
+    expect(toPath('https://robnicolas.ch')).toBe('/');
+    expect(toPath('https://robnicolas.ch/news/')).toBe('/news/');
+  });
+
+  it('accepts paths and host-less values', () => {
+    expect(toPath('/kontakt')).toBe('/kontakt');
+    expect(toPath('kontakt')).toBe('/kontakt');
+  });
+});
+
+describe('limitRoutes', () => {
+  const routes = ['/', '/arbeiten/a', '/kontakt', '/arbeiten/b', '/arbeiten/c', '/arbeiten/d', '/news/a', '/news/b'];
+
+  it('keeps the first matches of each limit in their original order', () => {
+    expect(limitRoutes(routes, [{ pattern: '/arbeiten/', max: 2 }])).toEqual([
+      '/',
+      '/arbeiten/a',
+      '/kontakt',
+      '/arbeiten/b',
+      '/news/a',
+      '/news/b',
+    ]);
+  });
+
+  it('applies several limits independently', () => {
+    expect(
+      limitRoutes(routes, [
+        { pattern: '/arbeiten/', max: 1 },
+        { pattern: /^\/news\//, max: 1 },
+      ]),
+    ).toEqual(['/', '/arbeiten/a', '/kontakt', '/news/a']);
+  });
+
+  it('counts a route only against the first matching limit', () => {
+    expect(
+      limitRoutes(
+        ['/a/x', '/a/y', '/b/z'],
+        [
+          { pattern: '/a/', max: 1 },
+          { pattern: '/', max: 1 },
+        ],
+      ),
+    ).toEqual(['/a/x', '/b/z']);
+  });
+
+  it('drops every match with max 0', () => {
+    expect(limitRoutes(routes, [{ pattern: '/arbeiten/', max: 0 }])).not.toContain('/arbeiten/a');
+  });
+
+  it('returns all routes without limits', () => {
+    expect(limitRoutes(routes, [])).toEqual(routes);
+  });
+});
+
+describe('excludeRoutes', () => {
+  it('drops matching routes', () => {
+    expect(excludeRoutes(['/', '/ueber-uns/livebilder', '/fr/x', '/fr'], ['/livebilder', /^\/fr\/.+/])).toEqual([
+      '/',
+      '/fr',
+    ]);
+  });
+});
diff --git a/src/testing/routes.ts b/src/testing/routes.ts
new file mode 100644
index 0000000..2aa1136
--- /dev/null
+++ b/src/testing/routes.ts
@@ -0,0 +1,42 @@
+import { matchesAnyPattern, matchesPattern, type Pattern } from './patterns.js';
+
+/** Caps how many routes matching `pattern` are kept, e.g. three of hundreds of case studies. */
+export type RouteLimit = {
+  pattern: Pattern;
+  max: number;
+};
+
+/**
+ * Reduces an absolute or relative URL to its path and query, so routes taken from a
+ * sitemap (which lists the production host) can be visited against any base URL.
+ */
+export const toPath = (url: string): string => {
+  const { pathname, search } = new URL(url, 'http://localhost');
+
+  return `${pathname}${search}`;
+};
+
+/**
+ * Keeps the first `max` routes matching each limit, in their original order. A route that
+ * matches several limits counts only against the first one, so overlapping patterns never
+ * drop a route twice.
+ */
+export const limitRoutes = (routes: readonly string[], limits: readonly RouteLimit[]): string[] => {
+  const counts = limits.map(() => 0);
+
+  return routes.filter((route) => {
+    const index = limits.findIndex(({ pattern }) => matchesPattern(route, pattern));
+
+    if (index === -1) {
+      return true;
+    }
+
+    counts[index] += 1;
+
+    return counts[index] <= limits[index].max;
+  });
+};
+
+/** Drops routes matching any of `exclude`. */
+export const excludeRoutes = (routes: readonly string[], exclude: readonly Pattern[]): string[] =>
+  routes.filter((route) => !matchesAnyPattern(route, exclude));
diff --git a/src/testing/sitemap.test.ts b/src/testing/sitemap.test.ts
new file mode 100644
index 0000000..def9b73
--- /dev/null
+++ b/src/testing/sitemap.test.ts
@@ -0,0 +1,151 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { fetchSitemapRoutes, parseSitemap } from './sitemap.js';
+
+const urlset = (body: string) =>
+  `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+${body}
+</urlset>`;
+
+const sitemapIndex = (locs: string[]) =>
+  `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${locs.map((loc) => `<sitemap><loc>${loc}</loc></sitemap>`).join('\n')}
+</sitemapindex>`;
+
+const xmlResponse = (body: string, status = 200) =>
+  new Response(body, { status, headers: { 'Content-Type': 'application/xml' } });
+
+describe('parseSitemap', () => {
+  it('reads <loc> values of a urlset', () => {
+    expect(
+      parseSitemap(
+        urlset(`
+<url><loc>https://example.com/</loc><lastmod>2026-01-01</lastmod></url>
+<url><loc>
+  https://example.com/kontakt
+</loc></url>`),
+      ),
+    ).toEqual({ urls: ['https://example.com/', 'https://example.com/kontakt'], sitemaps: [] });
+  });
+
+  it('includes xhtml:link alternates', () => {
+    const { urls } = parseSitemap(
+      urlset(`<url>
+  <loc>https://example.com/de</loc>
+  <xhtml:link rel="alternate" hreflang="fr" href="https://example.com/fr"/>
+  <xhtml:link rel='alternate' hreflang='it' href='https://example.com/it' />
+</url>`),
+    );
+
+    expect(urls).toEqual(['https://example.com/de', 'https://example.com/fr', 'https://example.com/it']);
+  });
+
+  it('decodes entities and CDATA', () => {
+    const { urls } = parseSitemap(
+      urlset(`
+<url><loc>https://example.com/?a=1&amp;b=2</loc></url>
+<url><loc><![CDATA[https://example.com/caf&eacute;]]></loc></url>
+<url><loc>https://example.com/caf&#xE9;&#33;</loc></url>`),
+    );
+
+    expect(urls).toEqual(['https://example.com/?a=1&b=2', 'https://example.com/caf&eacute;', 'https://example.com/café!']);
+  });
+
+  it('returns child sitemaps of an index', () => {
+    expect(parseSitemap(sitemapIndex(['https://example.com/a.xml', 'https://example.com/b.xml']))).toEqual({
+      urls: [],
+      sitemaps: ['https://example.com/a.xml', 'https://example.com/b.xml'],
+    });
+  });
+
+  it('returns no URLs for an empty urlset', () => {
+    expect(parseSitemap(urlset(''))).toEqual({ urls: [], sitemaps: [] });
+  });
+
+  it('throws for documents that are not sitemaps', () => {
+    expect(() => parseSitemap('<!doctype html><html><body>Not found</body></html>')).toThrow('Not a sitemap');
+  });
+});
+
+describe('fetchSitemapRoutes', () => {
+  it('fetches /sitemap.xml from the base URL and returns paths', async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue(
+        xmlResponse(
+          urlset('<url><loc>https://prod.example.com/</loc></url><url><loc>https://prod.example.com/a</loc></url>'),
+        ),
+      );
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).resolves.toEqual(['/', '/a']);
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/sitemap.xml');
+  });
+
+  it('follows a sitemap index against the base URL host', async () => {
+    const responses: Record<string, string> = {
+      'http://localhost:3000/sitemap.xml': sitemapIndex([
+        'https://prod.example.com/pages.xml',
+        'https://prod.example.com/news.xml',
+      ]),
+      'http://localhost:3000/pages.xml': urlset('<url><loc>https://prod.example.com/</loc></url>'),
+      'http://localhost:3000/news.xml': urlset('<url><loc>https://prod.example.com/news/a</loc></url>'),
+    };
+    const fetchFn = vi.fn((input: RequestInfo | URL) => {
+      const body = responses[input as string];
+
+      return Promise.resolve(xmlResponse(body ?? '', body ? 200 : 404));
+    });
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).resolves.toEqual(['/', '/news/a']);
+  });
+
+  it('does not loop on a self-referencing index', async () => {
+    const fetchFn = vi.fn(() =>
+      Promise.resolve(
+        xmlResponse(sitemapIndex(['https://prod.example.com/sitemap.xml', 'https://prod.example.com/pages.xml'])),
+      ),
+    );
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).rejects.toThrow('No URLs found');
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+  });
+
+  it('deduplicates, excludes and limits routes', async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValue(
+        xmlResponse(
+          urlset(
+            ['/', '/arbeiten/a', '/arbeiten/b', '/arbeiten/c', '/arbeiten/d', '/livebilder', '/']
+              .map((path) => `<url><loc>https://prod.example.com${path}</loc></url>`)
+              .join(''),
+          ),
+        ),
+      );
+
+    await expect(
+      fetchSitemapRoutes({
+        baseURL: 'http://localhost:3000',
+        sitemapPath: '/custom-sitemap.xml',
+        exclude: ['/livebilder'],
+        limits: [{ pattern: '/arbeiten/', max: 3 }],
+        fetchFn,
+      }),
+    ).resolves.toEqual(['/', '/arbeiten/a', '/arbeiten/b', '/arbeiten/c']);
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/custom-sitemap.xml');
+  });
+
+  it('throws on a non-200 sitemap', async () => {
+    const fetchFn = vi.fn().mockResolvedValue(xmlResponse('nope', 503));
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).rejects.toThrow('HTTP 503');
+  });
+
+  it('throws when the sitemap lists no pages', async () => {
+    const fetchFn = vi.fn().mockResolvedValue(xmlResponse(urlset('')));
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).rejects.toThrow('No URLs found');
+  });
+});
diff --git a/src/testing/sitemap.ts b/src/testing/sitemap.ts
new file mode 100644
index 0000000..6d4c1b0
--- /dev/null
+++ b/src/testing/sitemap.ts
@@ -0,0 +1,118 @@
+import type { Pattern } from './patterns.js';
+import { excludeRoutes, limitRoutes, toPath, type RouteLimit } from './routes.js';
+
+export type ParsedSitemap = {
+  /** Page URLs: every `<loc>` of a `<urlset>`, plus `xhtml:link` alternates. */
+  urls: string[];
+  /** Child sitemap URLs of a `<sitemapindex>`. */
+  sitemaps: string[];
+};
+
+export type FetchSitemapRoutesOptions = {
+  /** Origin the sitemap is fetched from. Sitemap hosts are replaced by it. */
+  baseURL: string;
+  /** Default `'/sitemap.xml'`. */
+  sitemapPath?: string;
+  /** Applied after {@link FetchSitemapRoutesOptions.exclude}. */
+  limits?: readonly RouteLimit[];
+  /** Routes to drop entirely, e.g. pages behind auth or with live webcams. */
+  exclude?: readonly Pattern[];
+  fetchFn?: typeof fetch;
+};
+
+const DEFAULT_SITEMAP_PATH = '/sitemap.xml';
+/** A sitemap index may only reference sitemaps, so one level is all the spec allows. */
+const MAX_INDEX_DEPTH = 2;
+
+const ENTITIES: Record<string, string> = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" };
+
+const decodeEntities = (value: string): string =>
+  value.replace(/&(#x[\da-f]+|#\d+|[a-z]+);/gi, (entity, name: string) => {
+    if (name.startsWith('#x') || name.startsWith('#X')) {
+      return String.fromCodePoint(Number.parseInt(name.slice(2), 16));
+    }
+
+    if (name.startsWith('#')) {
+      return String.fromCodePoint(Number.parseInt(name.slice(1), 10));
+    }
+
+    return ENTITIES[name.toLowerCase()] ?? entity;
+  });
+
+const unwrap = (value: string): string =>
+  decodeEntities(
+    value
+      .trim()
+      .replace(/^<!\[CDATA\[([\s\S]*)\]\]>$/, '$1')
+      .trim(),
+  );
+
+const LOC = /<loc>([\s\S]*?)<\/loc>/g;
+const ALTERNATE = /<xhtml:link\b[^>]*?\bhref=(["'])(.*?)\1/g;
+
+/**
+ * Extracts URLs from a sitemap or sitemap index. Regex-based on purpose: sitemaps are a
+ * flat, machine-written format, and a real XML parser would be this package's first
+ * runtime dependency.
+ */
+export const parseSitemap = (xml: string): ParsedSitemap => {
+  const locs = [...xml.matchAll(LOC)].map(([, value]) => unwrap(value)).filter(Boolean);
+
+  if (/<sitemapindex[\s>]/.test(xml)) {
+    return { urls: [], sitemaps: locs };
+  }
+
+  if (!/<urlset[\s>]/.test(xml)) {
+    throw new Error('[testing] Not a sitemap: expected a <urlset> or <sitemapindex> root element');
+  }
+
+  const alternates = [...xml.matchAll(ALTERNATE)].map(([, , value]) => unwrap(value)).filter(Boolean);
+
+  return { urls: [...locs, ...alternates], sitemaps: [] };
+};
+
+/**
+ * Fetches the sitemap (following a sitemap index) and returns deduplicated paths, so the
+ * same routes can be visited against localhost, a preview, or production.
+ *
+ * Throws when the sitemap is unreachable or lists no pages: an empty route list would
+ * otherwise turn into a green test run that checked nothing.
+ */
+export const fetchSitemapRoutes = async ({
+  baseURL,
+  sitemapPath = DEFAULT_SITEMAP_PATH,
+  limits = [],
+  exclude = [],
+  fetchFn = fetch,
+}: FetchSitemapRoutesOptions): Promise<string[]> => {
+  const visited = new Set<string>();
+
+  const collect = async (path: string, depth: number): Promise<string[]> => {
+    const url = new URL(path, baseURL).toString();
+
+    if (visited.has(url) || depth > MAX_INDEX_DEPTH) {
+      return [];
+    }
+
+    visited.add(url);
+
+    const response = await fetchFn(url);
+
+    if (!response.ok) {
+      throw new Error(`[testing] Failed to fetch sitemap ${url}: HTTP ${response.status}`);
+    }
+
+    const { urls, sitemaps } = parseSitemap(await response.text());
+    const nested = await Promise.all(sitemaps.map((sitemap) => collect(toPath(sitemap), depth + 1)));
+
+    return [...urls.map(toPath), ...nested.flat()];
+  };
+
+  const routes = [...new Set(await collect(sitemapPath, 1))];
+
+  if (routes.length === 0) {
+    throw new Error(`[testing] No URLs found in sitemap ${new URL(sitemapPath, baseURL).toString()}`);
+  }
+
+  return limitRoutes(excludeRoutes(routes, exclude), limits);
+};

From d9d23e548130f41f417e38050e3e125311f76b73 Mon Sep 17 00:00:00 2001
From: Kevin Walker <kevin@smartive.ch>
Date: Thu, 8 Oct 2026 10:13:05 +0200
Subject: [PATCH 2/4] refactor(testing): reuse matchesPattern for hosts and
 simplify e2e fixture server

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .gitignore                |  1 -
 e2e/server.ts             | 64 +++++++++++++++++----------------------
 src/testing/playwright.ts |  9 +++---
 3 files changed, 32 insertions(+), 42 deletions(-)

diff --git a/.gitignore b/.gitignore
index 43ca2d1..8fe45a5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,7 +15,6 @@ npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
 
-
 # playwright e2e
 /test-results
 /playwright-report
diff --git a/e2e/server.ts b/e2e/server.ts
index 4e8ac0b..25e9477 100644
--- a/e2e/server.ts
+++ b/e2e/server.ts
@@ -18,40 +18,42 @@ ${paths.map((path) => `<url><loc>https://prod.example.com${path}</loc></url>`).j
 <url><loc>https://prod.example.com/de</loc><xhtml:link rel="alternate" hreflang="fr" href="https://prod.example.com/fr"/></url>
 </urlset>`;
 
-const routes: Record<string, () => { status?: number; type?: string; body: string }> = {
-  '/sitemap.xml': () => ({
+type Route = { status?: number; type?: string; location?: string; delayMs?: number; body: string };
+
+const routes: Record<string, Route> = {
+  '/sitemap.xml': {
     type: 'application/xml',
     body: `<?xml version="1.0" encoding="UTF-8"?>
 <sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
 <sitemap><loc>https://prod.example.com/sitemap-pages.xml</loc></sitemap>
 </sitemapindex>`,
-  }),
-  '/sitemap-pages.xml': () => ({ type: 'application/xml', body: urlset(['/', '/blog/a', '/blog/b', '/blog/c']) }),
-  '/': () => ({ body: page('<h1>Home</h1>') }),
-  '/blog/a': () => ({ body: page('<h1>A</h1>') }),
-  '/blog/b': () => ({ body: page('<h1>B</h1>') }),
-  '/blog/c': () => ({ body: page('<h1>C</h1>') }),
-  '/de': () => ({ body: page('<h1>DE</h1>') }),
-  '/fr': () => ({ body: page('<h1>FR</h1>') }),
-  '/console-error': () => ({ body: page('<script>console.error("client boom")</script>') }),
-  '/console-warning': () => ({ body: page('<script>console.warn("careful")</script>') }),
-  '/page-error': () => ({ body: page('<script>setTimeout(() => { throw new Error("uncaught boom") }, 0)</script>') }),
-  '/rejection': () => ({ body: page('<script>Promise.reject(new Error("unhandled rejection"))</script>') }),
-  '/missing-asset': () => ({ body: page('<img src="/missing.png" alt="">') }),
-  '/third-party': () => ({
+  },
+  '/sitemap-pages.xml': { type: 'application/xml', body: urlset(['/', '/blog/a', '/blog/b', '/blog/c']) },
+  '/': { body: page('<h1>Home</h1>') },
+  '/blog/a': { body: page('<h1>A</h1>') },
+  '/blog/b': { body: page('<h1>B</h1>') },
+  '/blog/c': { body: page('<h1>C</h1>') },
+  '/de': { body: page('<h1>DE</h1>') },
+  '/fr': { body: page('<h1>FR</h1>') },
+  '/console-error': { body: page('<script>console.error("client boom")</script>') },
+  '/console-warning': { body: page('<script>console.warn("careful")</script>') },
+  '/page-error': { body: page('<script>setTimeout(() => { throw new Error("uncaught boom") }, 0)</script>') },
+  '/rejection': { body: page('<script>Promise.reject(new Error("unhandled rejection"))</script>') },
+  '/missing-asset': { body: page('<img src="/missing.png" alt="">') },
+  '/third-party': {
     body: page(
       `<script src="http://tracker.invalid/t.js"></script><script src="http://127.0.0.1:${PORT}/allowed.js"></script>`,
     ),
-  }),
-  '/allowed.js': () => ({ type: 'text/javascript', body: 'window.allowedLoaded = true;' }),
-  '/aborted': () => ({
+  },
+  '/allowed.js': { type: 'text/javascript', body: 'window.allowedLoaded = true;' },
+  '/aborted': {
     body: page(
       '<script>const c = new AbortController(); fetch("/slow", { signal: c.signal }).catch(() => {}); c.abort();</script>',
     ),
-  }),
-  '/slow': () => ({ type: 'text/plain', body: 'slow' }),
-  '/broken-request': () => ({ body: page('<script>fetch("/drop").catch(() => {})</script>') }),
-  '/redirect': () => ({ status: 308, body: '' }),
+  },
+  '/slow': { type: 'text/plain', delayMs: 2000, body: 'slow' },
+  '/broken-request': { body: page('<script>fetch("/drop").catch(() => {})</script>') },
+  '/redirect': { status: 308, location: '/', body: '' },
 };
 
 createServer((request, response) => {
@@ -71,20 +73,10 @@ createServer((request, response) => {
     return;
   }
 
-  const { status = 200, type = 'text/html; charset=utf-8', body } = route();
-  const headers: Record<string, string> = { 'Content-Type': type };
-
-  if (status === 308) {
-    headers.Location = '/';
-  }
-
-  if (pathname === '/slow') {
-    setTimeout(() => response.writeHead(status, headers).end(body), 2000);
-
-    return;
-  }
+  const { status = 200, type = 'text/html; charset=utf-8', location, delayMs = 0, body } = route;
+  const headers = { 'Content-Type': type, ...(location && { Location: location }) };
 
-  response.writeHead(status, headers).end(body);
+  setTimeout(() => response.writeHead(status, headers).end(body), delayMs);
 }).listen(PORT, () => {
   console.info(`fixture server on ${ORIGIN}`);
 });
diff --git a/src/testing/playwright.ts b/src/testing/playwright.ts
index bd152d1..018abf7 100644
--- a/src/testing/playwright.ts
+++ b/src/testing/playwright.ts
@@ -13,6 +13,7 @@ import type {
 } from '@playwright/test';
 
 import { isIgnored, type IgnoreRule } from './ignore.js';
+import { matchesPattern } from './patterns.js';
 import { fetchSitemapRoutes, type FetchSitemapRoutesOptions } from './sitemap.js';
 
 /** `'example.com'` matches exactly, `'*.example.com'` matches subdomains, a `RegExp` tests the hostname. */
@@ -54,7 +55,7 @@ export type SmokeFixtures = {
 type TestArgs = PlaywrightTestArgs & PlaywrightTestOptions;
 type WorkerArgs = PlaywrightWorkerArgs & PlaywrightWorkerOptions;
 
-const DEFAULT_FAIL_ON: SmokeOptions['failOn'] = ['error', 'warning'];
+const DEFAULT_FAIL_ON: NonNullable<SmokeOptions['failOn']> = ['error', 'warning'];
 const DEFAULT_SETTLE_MS = 2000;
 const DEFAULT_ROUTES_FILE = 'node_modules/.cache/smartive-utils/smoke-routes.json';
 
@@ -67,9 +68,7 @@ const EXPECTED_FAILURES = new Set(['net::ERR_BLOCKED_BY_CLIENT', 'net::ERR_ABORT
 
 const matchesHost = (hostname: string, pattern: HostPattern): boolean => {
   if (typeof pattern !== 'string') {
-    pattern.lastIndex = 0;
-
-    return pattern.test(hostname);
+    return matchesPattern(hostname, pattern);
   }
 
   return pattern.startsWith('*.') ? hostname.endsWith(pattern.slice(1)) : hostname === pattern;
@@ -157,7 +156,7 @@ export const smokeFixtures = (
       page.on('console', (message) => {
         const type = message.type();
 
-        if ((type !== 'error' && type !== 'warning') || !failOn?.includes(type)) {
+        if ((type !== 'error' && type !== 'warning') || !failOn.includes(type)) {
           return;
         }
 

From 695599ac5f435f19390f22532f425a26af01f342 Mon Sep 17 00:00:00 2001
From: Kevin Walker <kevin@smartive.ch>
Date: Thu, 8 Oct 2026 10:28:29 +0200
Subject: [PATCH 3/4] fix(testing): merge per-file smoke options and fully
 silence disabled first-party checks

`test.use({ smokeOptions })` replaced the options passed to `smokeFixtures()`, silently
dropping the project-wide `allowHosts` and `ignore` rules. Overrides are now merged:
`ignore` and `allowHosts` add to the base options, the other fields replace them.

`checkFirstPartyRequests: false` still failed on first-party 404s through Chromium's
"Failed to load resource" console error. That message is now always skipped for
first-party URLs, since the response and requestfailed handlers own those failures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 README.md                      |  3 +-
 e2e/fixtures.spec.ts           | 17 +++++++++++
 src/testing/playwright.test.ts | 53 +++++++++++++++++++++++++++++-----
 src/testing/playwright.ts      | 24 +++++++++++----
 4 files changed, 83 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 2bb6cd2..b259522 100644
--- a/README.md
+++ b/README.md
@@ -382,7 +382,8 @@ tests:
   skips global setup and lists no routes.
 - **Existing Playwright setup:** `globalSetup` applies to a whole config, so put the smoke suite in
   its own `playwright.smoke.config.ts` and run it with `playwright test -c playwright.smoke.config.ts`.
-- **Per-file options:** `test.use({ smokeOptions: { failOn: ['error'] } })`.
+- **Per-file options:** `test.use({ smokeOptions: { failOn: ['error'] } })`. They are merged over the
+  options passed to `smokeFixtures`: `ignore` and `allowHosts` add to them, the other fields replace them.
 - **Expecting issues:** a test can assert on `smoke.issues` and empty it (`smoke.issues.length = 0`)
   to pass.
 - **CommonJS projects** (most Next.js apps) work: Playwright compiles the specs to `require()`, and
diff --git a/e2e/fixtures.spec.ts b/e2e/fixtures.spec.ts
index b46ffd1..c438fb1 100644
--- a/e2e/fixtures.spec.ts
+++ b/e2e/fixtures.spec.ts
@@ -83,6 +83,23 @@ test.describe('stays quiet', () => {
 
       expect(smoke.issues).toEqual([]);
     });
+
+    test('keeps the allowed hosts of the base options', async ({ page, smoke }) => {
+      await gotoAndSettle(page, '/third-party', SETTLE);
+
+      expect(await page.evaluate(() => (window as { allowedLoaded?: boolean }).allowedLoaded)).toBe(true);
+      expect([...smoke.blockedUrls]).toEqual(['http://tracker.invalid/t.js']);
+    });
+  });
+
+  test.describe('without first-party request checks', () => {
+    test.use({ smokeOptions: { checkFirstPartyRequests: false } });
+
+    test('missing first-party assets', async ({ page, smoke }) => {
+      await gotoAndSettle(page, '/missing-asset', SETTLE);
+
+      expect(smoke.issues).toEqual([]);
+    });
   });
 });
 
diff --git a/src/testing/playwright.test.ts b/src/testing/playwright.test.ts
index 68e41e9..05042b7 100644
--- a/src/testing/playwright.test.ts
+++ b/src/testing/playwright.test.ts
@@ -57,7 +57,11 @@ const createTestInfo = () => ({ annotations: [] as TestInfo['annotations'], atta
 /** Runs the `smoke` fixture with `body` as the test, returning the outcome of its teardown. */
 const runSmoke = (
   body: (fake: ReturnType<typeof createPage>, state: SmokeState) => Promise<void> | void,
-  { options = {}, baseURL = 'http://localhost:3000' }: { options?: SmokeOptions; baseURL?: string | null } = {},
+  {
+    options = {},
+    overrides = {},
+    baseURL = 'http://localhost:3000',
+  }: { options?: SmokeOptions; overrides?: SmokeOptions; baseURL?: string | null } = {},
 ) => {
   const fake = createPage();
   const testInfo = createTestInfo();
@@ -67,7 +71,7 @@ const runSmoke = (
   let state: SmokeState | undefined;
 
   const result = fixture(
-    { page: fake.page as unknown as Page, baseURL: baseURL ?? undefined, smokeOptions: options },
+    { page: fake.page as unknown as Page, baseURL: baseURL ?? undefined, smokeOptions: overrides },
     async (smokeState) => {
       state = smokeState;
       await body(fake, smokeState);
@@ -79,10 +83,40 @@ const runSmoke = (
 };
 
 describe('smokeFixtures', () => {
-  it('exposes the options as an overridable option fixture', () => {
-    const options = { ignore: ['noise'] };
+  it('exposes an overridable option fixture that starts empty', () => {
+    expect(smokeFixtures({ ignore: ['noise'] }).smokeOptions).toEqual([{}, { option: true }]);
+  });
 
-    expect(smokeFixtures(options).smokeOptions).toEqual([options, { option: true }]);
+  it('adds overridden ignore rules and allowed hosts to the base options', async () => {
+    const { result, getState } = runSmoke(
+      async ({ request, console }) => {
+        expect((await request('https://www.datocms-assets.com/1/a.jpg')).fallback).toHaveBeenCalled();
+        expect((await request('https://stream.mux.com/x/high.mp4')).fallback).toHaveBeenCalled();
+        console('error', 'base noise');
+        console('error', 'file noise');
+        console('error', 'boom');
+      },
+      {
+        options: { allowHosts: ['*.datocms-assets.com'], ignore: ['base noise'] },
+        overrides: { allowHosts: ['stream.mux.com'], ignore: ['file noise'] },
+      },
+    );
+
+    await expect(result).rejects.toThrow('1 issue(s)');
+    expect(getState().issues).toEqual([{ type: 'console-error', text: 'boom', location: undefined }]);
+    expect([...getState().blockedUrls]).toEqual([]);
+  });
+
+  it('lets overrides replace failOn and checkFirstPartyRequests', async () => {
+    const { result } = runSmoke(
+      ({ page, console }) => {
+        console('warning', 'Deprecated thing');
+        page.emit('response', { url: () => 'http://localhost:3000/missing.png', status: () => 404 });
+      },
+      { options: { failOn: ['warning'] }, overrides: { failOn: ['error'], checkFirstPartyRequests: false } },
+    );
+
+    await expect(result).resolves.toBeUndefined();
   });
 
   it('allows first-party, allowlisted and non-http requests and blocks the rest', async () => {
@@ -220,10 +254,15 @@ describe('smokeFixtures', () => {
     ]);
   });
 
-  it('does not check first-party requests when disabled', async () => {
+  it('does not check first-party requests when disabled, including their console errors', async () => {
     const { result } = runSmoke(
-      ({ page }) => {
+      ({ page, console }) => {
         page.emit('response', { url: () => 'http://localhost:3000/missing.png', status: () => 404 });
+        console(
+          'error',
+          'Failed to load resource: the server responded with a status of 404 (Not Found)',
+          'http://localhost:3000/missing.png',
+        );
       },
       { options: { checkFirstPartyRequests: false } },
     );
diff --git a/src/testing/playwright.ts b/src/testing/playwright.ts
index 018abf7..9b1d155 100644
--- a/src/testing/playwright.ts
+++ b/src/testing/playwright.ts
@@ -30,7 +30,10 @@ export type SmokeOptions = {
    * nor send hits from CI.
    */
   allowHosts?: HostPattern[];
-  /** Fail on first-party responses with status >= 400 and failed first-party requests. Default `true`. */
+  /**
+   * Fail on first-party responses with status >= 400 and failed first-party requests. Default `true`.
+   * When `false`, Chromium's matching "Failed to load resource" console errors are skipped too.
+   */
   checkFirstPartyRequests?: boolean;
 };
 
@@ -47,7 +50,11 @@ export type SmokeState = {
 };
 
 export type SmokeFixtures = {
-  /** Override per file or describe block with `test.use({ smokeOptions: { … } })`. */
+  /**
+   * Per file or describe block overrides, e.g. `test.use({ smokeOptions: { failOn: ['error'] } })`.
+   * Merged over the options passed to {@link smokeFixtures}: `ignore` and `allowHosts` add to
+   * them, the other fields replace them.
+   */
   smokeOptions: SmokeOptions;
   smoke: SmokeState;
 };
@@ -103,10 +110,14 @@ const formatIssue = ({ type, text, location }: SmokeIssue): string =>
 export const smokeFixtures = (
   options: SmokeOptions = {},
 ): Fixtures<SmokeFixtures, Record<never, never>, TestArgs, WorkerArgs> => ({
-  smokeOptions: [options, { option: true }],
+  smokeOptions: [{}, { option: true }],
   smoke: [
     async ({ page, baseURL, smokeOptions }, use, testInfo) => {
-      const { ignore = [], failOn = DEFAULT_FAIL_ON, allowHosts = [], checkFirstPartyRequests = true } = smokeOptions;
+      const { failOn = DEFAULT_FAIL_ON, checkFirstPartyRequests = true } = { ...options, ...smokeOptions };
+      // Playwright replaces an option on `test.use()` instead of merging it, which would silently
+      // drop the project-wide allowlist and ignore rules.
+      const ignore = [...(options.ignore ?? []), ...(smokeOptions.ignore ?? [])];
+      const allowHosts = [...(options.allowHosts ?? []), ...(smokeOptions.allowHosts ?? [])];
       const state: SmokeState = { issues: [], blockedUrls: new Set() };
       const seen = new Set<string>();
       let firstPartyOrigin = baseURL ? new URL(baseURL).origin : undefined;
@@ -167,8 +178,9 @@ export const smokeFixtures = (
           return;
         }
 
-        // Chromium logs failed loads too; the response and requestfailed handlers report them with the status.
-        if (checkFirstPartyRequests && text.startsWith('Failed to load resource') && location && isFirstParty(location)) {
+        // Chromium logs failed loads too. The response and requestfailed handlers own first-party
+        // failures (with the status), so `checkFirstPartyRequests: false` silences them entirely.
+        if (text.startsWith('Failed to load resource') && location && isFirstParty(location)) {
           return;
         }
 

From f0f04488c859a419d2edf4f5abdb4f190cac9c65 Mon Sep 17 00:00:00 2001
From: Kevin Walker <kevin@smartive.ch>
Date: Thu, 8 Oct 2026 11:21:50 +0200
Subject: [PATCH 4/4] fix(testing): handle Firefox and WebKit aborts and time
 out sitemap fetches

The smoke fixture only knew Chromium's abort error, so cancelled first-party
requests (video range requests, navigating away) failed tests in Firefox
(`NS_BINDING_ABORTED`) and WebKit (`cancelled`, `Load request cancelled` on
Linux). The never-matching `ERR_BLOCKED_BY_CLIENT` entry is gone.

Firefox reports a blocked script as a console warning that names the URL in
its text but gives the page as location, which failed every page with a
blocked tracker. Console messages naming a blocked URL are now skipped.

`fetchSitemapRoutes` takes a `timeoutMs` (default 30 s) per request and adds
the sitemap URL to network and timeout errors, so a hanging sitemap fails the
global setup instead of stalling it.

The fixture e2e spec now also runs in Firefox and WebKit on CI (opt-in locally
via `E2E_ALL_BROWSERS`).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .github/workflows/test.yml     |  2 +-
 README.md                      |  2 +-
 e2e/fixtures.spec.ts           |  5 ++++-
 e2e/playwright.config.ts       | 12 +++++++++++-
 src/testing/playwright.test.ts | 22 +++++++++++++++++++---
 src/testing/playwright.ts      | 17 +++++++++++------
 src/testing/sitemap.test.ts    | 29 ++++++++++++++++++++++++++---
 src/testing/sitemap.ts         | 33 ++++++++++++++++++++++++++-------
 8 files changed, 99 insertions(+), 23 deletions(-)

diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
index cbcb58d..e80f9ae 100644
--- a/.github/workflows/test.yml
+++ b/.github/workflows/test.yml
@@ -40,5 +40,5 @@ jobs:
         with:
           node-version: 24
       - run: npm ci
-      - run: npx playwright install --with-deps chromium
+      - run: npx playwright install --with-deps chromium firefox webkit
       - run: npm run test:e2e
diff --git a/README.md b/README.md
index b259522..1e6f31a 100644
--- a/README.md
+++ b/README.md
@@ -247,7 +247,7 @@ const results = await checkUrls(routes, { baseURL: 'http://localhost:3333' });
 
 - `fetchSitemapRoutes` follows a sitemap index and includes `xhtml:link` alternates. It replaces the
   sitemap host with `baseURL`, deduplicates, applies `exclude` then `limits`, and throws when the
-  sitemap is unreachable or empty, so a broken sitemap never turns into a green run that checked
+  sitemap is unreachable, slower than `timeoutMs` (default 30 s) or empty, so a broken sitemap never turns into a green run that checked
   nothing.
 - `checkUrls` requests every URL without following redirects (a redirecting sitemap URL fails),
   retries network errors and 5xx once, and never throws. `formatUrlCheckFailures` turns the
diff --git a/e2e/fixtures.spec.ts b/e2e/fixtures.spec.ts
index c438fb1..456c370 100644
--- a/e2e/fixtures.spec.ts
+++ b/e2e/fixtures.spec.ts
@@ -29,7 +29,10 @@ test.describe('collects issues', () => {
   test('unhandled promise rejections', async ({ page, smoke }) => {
     await gotoAndSettle(page, '/rejection', SETTLE);
 
-    expect(smoke.issues).toEqual([expect.objectContaining({ type: 'pageerror', text: 'unhandled rejection' })]);
+    // WebKit prefixes the message with `Error: `.
+    expect(smoke.issues).toEqual([
+      expect.objectContaining({ type: 'pageerror', text: expect.stringContaining('unhandled rejection') }),
+    ]);
     smoke.issues.length = 0;
   });
 
diff --git a/e2e/playwright.config.ts b/e2e/playwright.config.ts
index 155d33e..3821173 100644
--- a/e2e/playwright.config.ts
+++ b/e2e/playwright.config.ts
@@ -9,7 +9,17 @@ export default defineConfig({
   forbidOnly: !!process.env.CI,
   reporter: process.env.CI ? [['github'], ['list']] : 'list',
   use: { baseURL: `http://localhost:${PORT}` },
-  projects: [{ name: 'chromium', use: devices['Desktop Chrome'] }],
+  projects: [
+    { name: 'chromium', use: devices['Desktop Chrome'] },
+    // Every engine words aborts and blocked requests differently, so the fixture runs in all three.
+    // Opt-in locally: Playwright's Firefox does not start on every macOS version.
+    ...(process.env.CI || process.env.E2E_ALL_BROWSERS
+      ? [
+          { name: 'firefox', use: devices['Desktop Firefox'], testMatch: 'fixtures.spec.ts' },
+          { name: 'webkit', use: devices['Desktop Safari'], testMatch: 'fixtures.spec.ts' },
+        ]
+      : []),
+  ],
   webServer: {
     command: 'node e2e/server.ts',
     cwd: '..',
diff --git a/src/testing/playwright.test.ts b/src/testing/playwright.test.ts
index 05042b7..30ead73 100644
--- a/src/testing/playwright.test.ts
+++ b/src/testing/playwright.test.ts
@@ -212,6 +212,19 @@ describe('smokeFixtures', () => {
     await expect(result).resolves.toBeUndefined();
   });
 
+  it('skips Firefox console warnings that name a blocked request', async () => {
+    const { result } = runSmoke(async ({ request, console }) => {
+      await request('https://connect.facebook.net/en_US/fbevents.js');
+      console(
+        'warning',
+        'Loading failed for the <script> with source “https://connect.facebook.net/en_US/fbevents.js”.',
+        'http://localhost:3000/page',
+      );
+    });
+
+    await expect(result).resolves.toBeUndefined();
+  });
+
   it('reports failed first-party responses once, with their status', async () => {
     const { result, getState } = runSmoke(({ page, console }) => {
       page.emit('response', { url: () => 'http://localhost:3000/missing.png', status: () => 404 });
@@ -239,7 +252,10 @@ describe('smokeFixtures', () => {
 
     const { result, getState } = runSmoke(({ page }) => {
       page.emit('requestfailed', failed('http://localhost:3000/video.mp4', 'net::ERR_ABORTED'));
-      page.emit('requestfailed', failed('https://www.googletagmanager.com/gtm.js', 'net::ERR_BLOCKED_BY_CLIENT'));
+      page.emit('requestfailed', failed('http://localhost:3000/firefox.mp4', 'NS_BINDING_ABORTED'));
+      page.emit('requestfailed', failed('http://localhost:3000/webkit-mac.mp4', 'cancelled'));
+      page.emit('requestfailed', failed('http://localhost:3000/webkit-linux.mp4', 'Load request cancelled'));
+      page.emit('requestfailed', failed('https://www.googletagmanager.com/gtm.js', 'net::ERR_BLOCKED_BY_CLIENT.Inspector'));
       page.emit('requestfailed', failed('https://third.example/x.js', 'net::ERR_NAME_NOT_RESOLVED'));
       page.emit('requestfailed', failed('http://localhost:3000/api/data', 'net::ERR_EMPTY_RESPONSE'));
     });
@@ -360,7 +376,7 @@ describe('smokeGlobalSetup', () => {
 
     await smokeGlobalSetup({ file, fetchFn })(config('http://localhost:3333'));
 
-    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3333/sitemap.xml');
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3333/sitemap.xml', expect.anything());
     expect(readRoutes(file)).toEqual(['/', '/a']);
   });
 
@@ -369,7 +385,7 @@ describe('smokeGlobalSetup', () => {
 
     await smokeGlobalSetup({ baseURL: 'https://prod.example.com', file: join(dir, 'r.json'), fetchFn })(config());
 
-    expect(fetchFn).toHaveBeenCalledWith('https://prod.example.com/sitemap.xml');
+    expect(fetchFn).toHaveBeenCalledWith('https://prod.example.com/sitemap.xml', expect.anything());
   });
 
   it('throws without a baseURL', async () => {
diff --git a/src/testing/playwright.ts b/src/testing/playwright.ts
index 9b1d155..e58de33 100644
--- a/src/testing/playwright.ts
+++ b/src/testing/playwright.ts
@@ -67,11 +67,12 @@ const DEFAULT_SETTLE_MS = 2000;
 const DEFAULT_ROUTES_FILE = 'node_modules/.cache/smartive-utils/smoke-routes.json';
 
 /**
- * `ERR_BLOCKED_BY_CLIENT` is our own blocking. `ERR_ABORTED` is the browser cancelling a
- * request it no longer needs: `<video>` drops range requests when it switches renditions,
- * and closing the page aborts whatever is still in flight.
+ * The browser cancelling a first-party request it no longer needs: `<video>` drops range
+ * requests when it switches renditions, and navigating or closing the page aborts whatever is
+ * still in flight. Chromium, Firefox, WebKit on macOS and WebKit on Linux each word it differently.
+ * Our own blocking never shows up here, because blocked requests are never first party.
  */
-const EXPECTED_FAILURES = new Set(['net::ERR_BLOCKED_BY_CLIENT', 'net::ERR_ABORTED']);
+const EXPECTED_FAILURES = new Set(['net::ERR_ABORTED', 'NS_BINDING_ABORTED', 'cancelled', 'Load request cancelled']);
 
 const matchesHost = (hostname: string, pattern: HostPattern): boolean => {
   if (typeof pattern !== 'string') {
@@ -174,11 +175,15 @@ export const smokeFixtures = (
         const text = message.text();
         const location = message.location().url || undefined;
 
-        if (location && state.blockedUrls.has(location)) {
+        // Chromium gives the blocked URL as the location, Firefox names it in the text and gives the page.
+        if (
+          (location && state.blockedUrls.has(location)) ||
+          [...state.blockedUrls].some((blockedUrl) => text.includes(blockedUrl))
+        ) {
           return;
         }
 
-        // Chromium logs failed loads too. The response and requestfailed handlers own first-party
+        // Chromium and WebKit log failed loads too. The response and requestfailed handlers own first-party
         // failures (with the status), so `checkFirstPartyRequests: false` silences them entirely.
         if (text.startsWith('Failed to load resource') && location && isFirstParty(location)) {
           return;
diff --git a/src/testing/sitemap.test.ts b/src/testing/sitemap.test.ts
index def9b73..b09f1e6 100644
--- a/src/testing/sitemap.test.ts
+++ b/src/testing/sitemap.test.ts
@@ -80,7 +80,7 @@ describe('fetchSitemapRoutes', () => {
       );
 
     await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).resolves.toEqual(['/', '/a']);
-    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/sitemap.xml');
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/sitemap.xml', expect.anything());
   });
 
   it('follows a sitemap index against the base URL host', async () => {
@@ -134,13 +134,36 @@ describe('fetchSitemapRoutes', () => {
         fetchFn,
       }),
     ).resolves.toEqual(['/', '/arbeiten/a', '/arbeiten/b', '/arbeiten/c']);
-    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/custom-sitemap.xml');
+    expect(fetchFn).toHaveBeenCalledWith('http://localhost:3000/custom-sitemap.xml', expect.anything());
   });
 
   it('throws on a non-200 sitemap', async () => {
     const fetchFn = vi.fn().mockResolvedValue(xmlResponse('nope', 503));
 
-    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).rejects.toThrow('HTTP 503');
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).rejects.toThrow(
+      'Failed to fetch sitemap http://localhost:3000/sitemap.xml: HTTP 503',
+    );
+  });
+
+  it('times out a hanging sitemap request', async () => {
+    const fetchFn = vi.fn(
+      (_input: RequestInfo | URL, init?: RequestInit) =>
+        new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener('abort', () => reject(init.signal?.reason as Error));
+        }),
+    );
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', timeoutMs: 10, fetchFn })).rejects.toThrow(
+      /^\[testing\] Failed to fetch sitemap http:\/\/localhost:3000\/sitemap\.xml: .*timeout/,
+    );
+  });
+
+  it('adds the sitemap URL to network errors', async () => {
+    const fetchFn = vi.fn().mockRejectedValue(new TypeError('fetch failed'));
+
+    await expect(fetchSitemapRoutes({ baseURL: 'http://localhost:3000', fetchFn })).rejects.toThrow(
+      'Failed to fetch sitemap http://localhost:3000/sitemap.xml: fetch failed',
+    );
   });
 
   it('throws when the sitemap lists no pages', async () => {
diff --git a/src/testing/sitemap.ts b/src/testing/sitemap.ts
index 6d4c1b0..552b9f7 100644
--- a/src/testing/sitemap.ts
+++ b/src/testing/sitemap.ts
@@ -17,10 +17,13 @@ export type FetchSitemapRoutesOptions = {
   limits?: readonly RouteLimit[];
   /** Routes to drop entirely, e.g. pages behind auth or with live webcams. */
   exclude?: readonly Pattern[];
+  /** Per sitemap request. Default 30 seconds, so a hanging sitemap fails the setup instead of stalling it. */
+  timeoutMs?: number;
   fetchFn?: typeof fetch;
 };
 
 const DEFAULT_SITEMAP_PATH = '/sitemap.xml';
+const DEFAULT_TIMEOUT_MS = 30_000;
 /** A sitemap index may only reference sitemaps, so one level is all the spec allows. */
 const MAX_INDEX_DEPTH = 2;
 
@@ -83,10 +86,32 @@ export const fetchSitemapRoutes = async ({
   sitemapPath = DEFAULT_SITEMAP_PATH,
   limits = [],
   exclude = [],
+  timeoutMs = DEFAULT_TIMEOUT_MS,
   fetchFn = fetch,
 }: FetchSitemapRoutesOptions): Promise<string[]> => {
   const visited = new Set<string>();
 
+  const fetchXml = async (url: string): Promise<string> => {
+    try {
+      // The signal also covers reading the body, which is where a slow sitemap spends its time.
+      const response = await fetchFn(url, { signal: AbortSignal.timeout(timeoutMs) });
+
+      if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`HTTP ${response.status}`);
+      }
+
+      return await response.text();
+    } catch (error) {
+      throw new Error(
+        `[testing] Failed to fetch sitemap ${url}: ${error instanceof Error ? error.message : String(error)}`,
+        {
+          cause: error,
+        },
+      );
+    }
+  };
+
   const collect = async (path: string, depth: number): Promise<string[]> => {
     const url = new URL(path, baseURL).toString();
 
@@ -96,13 +121,7 @@ export const fetchSitemapRoutes = async ({
 
     visited.add(url);
 
-    const response = await fetchFn(url);
-
-    if (!response.ok) {
-      throw new Error(`[testing] Failed to fetch sitemap ${url}: HTTP ${response.status}`);
-    }
-
-    const { urls, sitemaps } = parseSitemap(await response.text());
+    const { urls, sitemaps } = parseSitemap(await fetchXml(url));
     const nested = await Promise.all(sitemaps.map((sitemap) => collect(toPath(sitemap), depth + 1)));
 
     return [...urls.map(toPath), ...nested.flat()];