setupRecast

What it does

setupRecast(test) connects the playwright-recast step helpers to your Playwright test context. Helpers that write annotations (narrate, zoom, highlight) require this setup to access test.info(). Marker-only helpers degrade safely without it: waitForNarration() and markClick() no-op, and click() falls back to locator.click(options) without adding settle/marker work.

Call it once in your fixtures file before relying on recorded narration, zoom, highlight, click, or narration-boundary markers.

Usage

import { test } from 'playwright-bdd'
import { setupRecast } from 'playwright-recast'

setupRecast(test)

Or with standard Playwright:

import { test } from '@playwright/test'
import { setupRecast } from 'playwright-recast'

setupRecast(test)

Options

narrateAutoWait — a global autoWait default

Instead of repeating { autoWait: true } on every narrate() call, set it once for the whole suite. Each narrate() that omits its own autoWait falls back to this default:

import { test } from 'playwright-bdd'
import { setupRecast } from 'playwright-recast'

// Every narrate() pads the test with the estimated speak time…
setupRecast(test, { narrateAutoWait: true })

// …or tune the estimate globally, same shapes as narrate's per-call autoWait:
setupRecast(test, {
  narrateAutoWait: { charactersPerSecond: 16, minMs: 1500, maxMs: 6000 },
})

A per-call autoWait always wins — including an explicit false, which disables the wait for that one call regardless of the global default:

await narrate('This line uses the global default.')
await narrate('This line waits 2s.', { autoWait: 2000 })   // overrides the default
await narrate('This line never waits.', { autoWait: false }) // opts out

The default is off, so suites that never set narrateAutoWait behave exactly as before. Calling setupRecast(test) again without the option resets the default back to off.

clickSettleMs — the click settle

The click() helper waits a short, fixed settle before marking the click, so the screencast captures a painted frame of the target (rather than a still-loading screen) for the rendered cursor approach. The default is 150 ms. Tune or disable it for the whole suite:

setupRecast(test, { clickSettleMs: 250 }) // slower targets need more settle
setupRecast(test, { clickSettleMs: 0 })   // disable the settle entirely

This is the only real-time cost click() adds to the test run. markClick() does not settle — standalone callers own their own timing.

How it works

setupRecast receives the test object and uses test.info() internally to access the current test's annotations. The annotation helpers (narrate, zoom, highlight) write structured data there, while marker helpers (click, markClick, waitForNarration) write marker-prefixed test.step() entries into the trace zip for the pipeline to read during video generation.

Example with playwright-bdd

// steps/fixtures.ts
import { test } from 'playwright-bdd'
import { setupRecast, narrate, pace } from 'playwright-recast'

setupRecast(test)
export { narrate, pace }

// steps/dashboard.ts
import { Given } from './fixtures'
import { narrate, pace } from 'playwright-recast'

Given('the user opens the dashboard', async ({ page }, docString?: string) => {
  narrate(docString)
  await page.goto('/dashboard')
  await pace(page, 4000)
})