Agent skill · payloadcms
e2e-write-visual-test
Use when writing a Playwright visual regression (screenshot comparison) test, tagging a test `@visual`, generating or updating baseline screenshots, running visual tests locally, or debugging a failing screenshot comparison in CI.
What it needs
About 5k tokens when loaded.
What this skill does
Writing and Running Visual Regression Tests Overview Visual regression tests are normal Playwright e2e tests tagged @visual that compare a screenshot against a committed baseline PNG instead of (or in addition to) asserting on the DOM. They live alongside normal e2e tests — there is no separate test type or directory to register a test in. Key pieces: test/helpers/e2e/visual.ts — the visual() helper. Declares a test tagged @visual without the tag needing to be typed (and possibly forgotten) at each call site. Prefer this over test() with a manual tag for any normal visual regression test. test/helpers/e2e/expectScreenshot.ts — the helper that takes the screenshot and diffs it against the baseline. test/playwright.config.ts — toHaveScreenshot.maxDiffPixelRatio (anti-aliasing tolerance) and snapshotPathTemplate (where baselines are stored). .github/scripts/visual/find-visual-suites.mjs — discovers every suite that has an @visual-tagged test by scanning test//e2e.spec.ts for either the string @visual or a visual() helper import. Nothing needs to be registered anywhere else — add a visual() test and it's picked up automatically next time visual tests run. .github/scripts/visual/run-visual-suites.sh — loops pnpm test:e2e:prod:server:run:noturbo <suite> --grep @visual over either an explicit suite or every discovered suite. Shared by CI and the local Docker script. Writing a new visual test Use the visual() helper instead of test() and call expectScreenshot instead of (or alongside) normal assertions: visual() applies the @visual tag for you, so there's nothing to remember. A test written with plain test() that forgets the tag is intentionally excluded from the visual-regression flow rather than caught after the fact — use visual() from the start instead of tagging manually. name — the baseline filename. Baselines are stored at test/<suite>/snapshots/e2e.spec.ts/<name>. target (optional) — a Locator to screenshot instead of the full page. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills payloadcms/e2e-write-visual-test