@hootlens/playwright

A Playwright fixture that records a test run as a Hoot Lens test visit and hands the recording back, so a coding agent (or any test) can read what the run did and fail on snags: pile-ups, no-shows and misfires.

Test visits are marked with a controlled-validation variant. Hoot Lens keeps them but never counts them in traffic, findings, heatmaps or plan usage.

// playwright.config.ts
import { defineConfig } from '@playwright/test';
import type { HootlensTestOptions } from '@hootlens/playwright';

export default defineConfig<HootlensTestOptions>({
  reporter: [['list'], ['html'], ['@hootlens/playwright/reporter']],
  use: {
    hootlensOptions: { projectId: process.env.HOOTLENS_PROJECT_ID, token: process.env.HOOTLENS_PAT, controlled: true },
  },
});

// checkout.spec.ts
import { test, expect } from '@hootlens/playwright';

test('paying with a card', async ({ page, hootlens }) => {
  await hootlens.start();                  // before page.goto()
  await page.goto('/checkout');
  await page.getByRole('button', { name: 'Pay' }).click();
  await expect(page.getByText('Thank you')).toBeVisible();
  await hootlens.expectNoSnags();          // fails with the narrative and the replay link
});

| Call | Returns | | --- | --- | | hootlens.start({ projectId?, label? }) | The handle. Marks the visit controlled; adds the tracker to a page without the Hoot Lens tag. | | hootlens.flush() | Waits until the collector has the recording. Throws a HootlensError that names the fix on a refusal. | | hootlens.recording() | { projectId, sessionId, recordingId?, recordingIds, variant, dashboardUrl } | | hootlens.narrative() | { available: true, text, steps, snags: { pileUps, noShows, misfires, total } ... }, or { available: false, note, recording } without a token | | hootlens.expectNoSnags({ allow? }) | The narrative, or throws with it |

A local dev server must be allowed first: the project owner chooses Allow localhost for testing in Installation. Reading narratives needs a personal access token with the read scope in HOOTLENS_PAT.

Full guide for agents, CI usage, errors and privacy: hootlens.com/docs/TESTING-WITH-HOOT-LENS.md.

License

MIT