How to use Verisual with Playwright

You need:

• Node.js 24 and a repository with Playwright installed;
• a web application that can be started locally or reached at a stable URL;
• a Verisual project connected to the repository; and
• permission to install a development dependency and commit workflow files.

Verisual uses a pinned Chromium environment for visual checkpoints. Your existing Playwright suite can continue to use its own projects, fixtures, assertions, and reporters.

Install Verisual in the project, initialize its directories and workflow, then link the repository to the project slug shown in the Verisual dashboard.

npm install --save-dev verisual
npx verisual init
npx verisual login
npx verisual link <project-slug>

verisual login stores a mode-0600 credential on your workstation. GitHub Actions does not use that credential; CI obtains a short-lived project token through GitHub OIDC.

Create .verisual/journeys/checkout.yml. This example uses an environment-backed target, accessible locators, a secret supplied at runtime, a masked dynamic value, and a strict visual checkpoint.

version: 1
id: checkout
name: Checkout summary
startUrlFromEnv: VERISUAL_TARGET_URL
steps:
  - action: goto
    url: /checkout
    waitUntil: domcontentloaded
  - action: fill
    locator:
      label: Email
    valueFromEnv: TEST_CUSTOMER_EMAIL
  - action: click
    locator:
      role: button
      name: Continue to review
  - action: assertVisible
    locator:
      role: heading
      name: Review your order
  - action: screenshot
    name: checkout-summary
    locator:
      testId: checkout-summary
    masks:
      - testId: order-number
    threshold: 0.2
    maxDiffPixels: 0

Prefer roles, labels, and test IDs over layout-dependent CSS. Each journey ID and checkpoint name becomes part of its stable baseline identity, so rename them only when you intend to create a new baseline.

Validate journey files without opening a browser, start the target, wait until it is ready, and then run Verisual.

npx verisual journey validate

npm run dev -- --hostname 127.0.0.1 > /tmp/verisual-app.log 2>&1 &
until curl --fail --silent http://127.0.0.1:3000 > /dev/null; do sleep 1; done

VERISUAL_TARGET_URL=http://127.0.0.1:3000 TEST_CUSTOMER_EMAIL=tester@example.com npx verisual test

verisual test validates and runs the YAML journeys, sends review data when linked, and then invokes your normal Playwright suite. A functional Playwright failure still fails the command.

On the trusted default branch, create the first candidate and approve it in Verisual:

VERISUAL_TARGET_URL=http://127.0.0.1:3000 TEST_CUSTOMER_EMAIL=tester@example.com npx verisual baseline seed

Later pull requests compare against the active baseline. Matching screenshot bytes remain in the runner; when a checkpoint changes, Verisual retains the current image and diff for private review. An approved CI candidate remains tied to the exact commit and becomes active only after the trusted deployment path verifies what shipped.

Capture browser state locally when a journey needs an authenticated session:

npx verisual auth capture customer   --url http://127.0.0.1:3000/login

Add authProfile: customer to the journey. The storage state lives under playwright/.auth, is ignored by the initialized project, and is never uploaded by the CLI. Use valueFromEnv for passwords, tokens, and other sensitive fields; never place those values in journey YAML.

Open any saved journey version and choose Export Playwright. The ZIP contains a TypeScript spec, minimal Playwright config and package manifest, a README, .env.example, an export manifest, and every retained approved baseline that matches a checkpoint in that version.

unzip checkout-playwright-v3.zip
cd checkout-playwright-v3
npm install
npx playwright install chromium
cp .env.example .env
npm test

The generated assertions use Playwright's native screenshot masks, threshold, and maxDiffPixels options. Baselines live under tests/baselines with deterministic snapshot paths. If a draft checkpoint has no retained baseline, the export manifest lists it and npm run update-snapshots creates it locally for review.

• Target unavailable: start the app and wait for a successful health request before running Verisual.
• Missing variable: provide every startUrlFromEnv and valueFromEnv value in the same process environment.
• New baseline after a rename: restore the previous journey/checkpoint identity or intentionally seed and approve the new one.
• Visual noise: stabilize data and animation first, then review Suggest Ignore Zones or mask only genuinely dynamic regions. Suggestions do not change the run that created them. A confirmed mask becomes an immutable version. Its first visual run still needs baseline approval because masked and unmasked screenshots are intentionally isolated.
• Local export differs: use the pinned container named in export-manifest.json; operating-system rendering can differ even when viewport and Playwright settings match.