Playwright Visual Implementation

Playwright Visual Implementation

Implement against rendered evidence, not memory. Iterate through controlled screenshots until the requested state matches the reference without regressing adjacent states.

1. Establish The Comparison Contract

Identify before editing:

• Which image is current and which is expected.
• Exact route, viewport, device scale factor, and whether either image is cropped.
• Required UI state: selected tab, view mode, filters, expanded panels, scroll position, and responsive breakpoint.
• Persistent inputs such as local storage, cookies, feature flags, and server preferences.
• Data assumptions that affect layout: item count, title lengths, missing images, progress values, and loading/error states.

Do not compare screenshots from different states. Reproduce the reference state first. If the state is persisted, set or preserve the real persistence mechanism rather than hard-coding a component default.

2. Inspect Before Editing

Read the page component, styles, shared components, route, fixtures, tests, and relevant generated types. Check the dirty worktree and preserve unrelated changes.

Determine whether the difference comes from:

1. Wrong structure or view variant.
2. Wrong content source or state.
3. Wrong asset or aspect ratio.
4. Wrong dimensions, spacing, typography, color, or borders.

Fix in that order. CSS cannot repair the wrong component structure or data state.

3. Capture A Controlled Baseline

Use the repository's Playwright installation. Capture to /tmp unless the project has an established visual-test artifact directory.

Build the website first, then use the screenshot CLI. The CLI starts a temporary Vite preview server for the built dist assets, applies the configured /p1 API proxy, selects an unused local port, and closes the server after capture. Do not ask the user to start or keep a Vite dev server running for visual work.

Prefer the repository's screenshot CLI, pnpm website screenshot (packages/website/scripts/screenshot.mjs):

pnpm run build
pnpm website screenshot <route> <output> [options]

Useful options:

• --width / --height: viewport size (default 1440×900)
• --device-scale-factor <n>: device scale factor (default 1)
• --quality <0-100>: JPEG quality (default 60); output must end in .jpg/.jpeg, PNG is not supported
• --full-page: capture the full scrollable page
• --element <selector>: capture only the element matching a CSS selector (e.g. #user-avatar) at its natural size instead of the whole page; mutually exclusive with --full-page. Use it to screenshot a single UI component in isolation
• --wait-until <state>: commit, domcontentloaded, load, or networkidle (default domcontentloaded)
• --wait-for <selector>: wait for a selector to become visible
• --wait-ms <ms>: additional delay after loading (default 1000)
• --local-storage key=value: set local storage before navigation (repeatable)
• --storage-state <path>: Playwright storage-state JSON for authentication

Examples:

pnpm run build
pnpm website screenshot /user/sai /tmp/user.jpg --full-page
pnpm website screenshot /user/sai /tmp/avatar.jpg --element '#user-avatar'
pnpm website screenshot --wait-for main --local-storage view=grid

Pass a route such as /anime, rather than the address of a manually started server. The CLI accepts a legacy loopback URL by extracting its route, but new commands should use a route. Use the same --mode for the build and screenshot command when a non-default Vite mode is required.

Extend packages/website/scripts/screenshot.mjs when the CLI options cannot express the needed state — for example clicks, form input, or waiting for an element to appear or disappear. It is the repository's capture tool and is meant to be modified as needed: add the extra steps (such as a repeatable --click <selector> option) to the capture flow, then run it with pnpm website screenshot as usual. It starts a temporary Vite preview server for the built assets; do not point it at a dev server, and build the website first (pnpm run build).

Write a separate temporary Playwright script only if extending the CLI is impractical. Place it inside packages/website/ (e.g. packages/website/scripts/) and run it with pnpm website run <script>; do not run it from the repo root, where @playwright/test is not resolvable in this pnpm workspace (ERR_MODULE_NOT_FOUND). Follow screenshot.mjs: derive the website directory from import.meta.dirname instead of a cwd-relative path, because the runner sets cwd to the package directory:

import path from 'node:path';
import { preview } from 'vite';
import { chromium } from '@playwright/test';

const websiteDirectory = path.resolve(import.meta.dirname, '..');
const previewServer = await preview({
  root: websiteDirectory,
  mode: 'production',
  preview: { host: '127.0.0.1', port: 0, strictPort: true },
});
const { port } = previewServer.httpServer.address();
const browser = await chromium.launch();
const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
const page = await context.newPage();

try {
  await page.route('**/api/page-data', (route) =>
    route.fulfill({ status: 200, contentType: 'application/json', body: fixture }),
  );

  await page.goto(`http://127.0.0.1:${port}/target-route`, { waitUntil: 'networkidle' });
  await page.getByRole('button', { name: 'Show details' }).click();
  await page.locator('[data-ready]').waitFor();
  await page.screenshot({ path: output, fullPage: true });
} finally {
  await context.close();
  await browser.close();
  await previewServer.close();
}

Use authentication storage supplied by the project or intercept APIs with existing fixtures. Never place credentials or bearer tokens in screenshot scripts. Keep fixture data representative: include long text, odd item counts, future/disabled items, and enough rows to expose the target layout.

Capture at minimum:

• The exact desktop reference state.
• Every alternate view mode touched by shared markup or CSS.
• A mobile viewport when the page is responsive.