skills.rest
payloadcms
payloadcmsOFFICIAL
Explore all skills by this author →
Website𝕏@payloadcmsGitHub

e2e-write-visual-test

Writes and runs Playwright visual regression tests with Docker-generated screenshot baselines.

44.5k|4.1k|Updated Jan 5, 2021
Search Tags:#docker#playwright#visual regression#ci#E2E Testing#screenshot testing#baseline snapshots
One-click install
npx skills add https://github.com/payloadcms/payload --skill e2e-write-visual-test
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: e2e-write-visual-test
Source: https://github.com/payloadcms/payload/tree/main/.claude/skills/e2e-write-visual-test
Command: npx skills add https://github.com/payloadcms/payload --skill e2e-write-visual-test

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Visual UI changes can slip through normal e2e tests, and screenshot comparisons fail inconsistently when baselines are generated on the wrong platform. This Skill guides writing Playwright visual regression tests that compare screenshots against committed baselines, with baselines generated inside the pinned Playwright Docker image so CI comparisons stay deterministic.

Core Features & Use Cases

  • Visual Test Authoring: Use the visual() helper to declare @visual-tagged tests and expectScreenshot to capture and diff screenshots, with optional target locators and mask regions for non-deterministic content.
  • Baseline Generation: Run pnpm test:visual:update inside the pinned Playwright Docker image to create or update baseline PNGs that match CI's exact renderer and font stack.
  • CI Integration: Understand how the visual-regression job discovers suites via find-visual-suites.mjs, gates on UI-affecting file changes, and excludes @visual tests from the regular e2e matrix.
  • Use Case: You changed a CSS file affecting the admin list view. Write a visual() test asserting the row is visible, generate the baseline with pnpm test:visual:update, commit the PNG, and let CI catch any future unintended pixel changes.

Quick Start

Write a Playwright visual regression test for the posts list view using the visual helper and generate its baseline screenshot with the Docker update command.

Frequently Asked Questions about e2e-write-visual-test

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a Playwright visual regression test?▼

Use the visual() helper instead of test() and call expectScreenshot with a baseline name after navigating to the page. Always assert a meaningful element is visible before screenshotting so a loading spinner or error page does not get baselined.

How do I update Playwright screenshot baselines?▼

Run pnpm test:visual:update, which executes every @visual suite inside the pinned Playwright Docker image and overwrites the baseline PNGs. To scope one suite, run pnpm test:visual <suite> -- --update-snapshots, then commit the resulting PNGs.

Why does my screenshot comparison fail on CI but pass locally?▼

The baseline was likely generated on a bare host instead of the pinned Docker image. Font hinting and anti-aliasing differ across operating systems, so baselines must be created with pnpm test:visual:update inside the same image CI uses.

Why doesn't pnpm test:e2e run my @visual tests?▼

The e2e runner excludes @visual tests by default via --grep-invert=@visual, and expectScreenshot refuses to run without PAYLOAD_TEST_PROD=true. Visual tests only run through the Docker-based pnpm test:visual script, matching CI behavior.

How do I handle timestamps and avatars in screenshot tests?▼

Pass a mask array of locators to expectScreenshot to blank out non-deterministic content before comparison. For masked cells inside auto-layout tables, also force table-layout: fixed via page.addStyleTag so column widths stop depending on masked content.

Related Skills

Explore More Software Engineering Skills→
kirillshilinkirillshilin

write-e2e-test

Generate Playwright E2E page objects and specs from clarified scenarios.

Community
Intermediate
alinaqialinaqi
705

Visual Validation — Autonomous Screenshot Verification

Compares Peekaboo screenshots with AI to detect visual regressions.

Community
Intermediate
aboudou-cto-blokoaboudou-cto-bloko
2

testing-patterns

Guide Vitest, Playwright, and Convex testing workflows for Pixel-Mart projects.

Community
Advanced
zenbuappszenbuapps

aibdd.auto.ts.it.handlers.readmodel-then

Verify rendered UI content in React IT Gherkin tests using Testing Library screen queries.

Official
Intermediate