Skill: screenshot-baseline

Skill: screenshot-baseline

Manage the full lifecycle of visual regression baselines: initial capture, intentional updates, platform-specific naming conventions, Git LFS storage, and PR review gates.

---

Responsibilities

• Guide the initial baseline generation workflow on CI (Linux) for cross-platform consistency.
• Provide the correct --update-snapshots command and explain when it is safe to use.
• Enforce platform-specific baseline naming so CI (Linux) and local (macOS/Windows) baselines do not collide.
• Configure .gitattributes for Git LFS on .png snapshot files.
• Document the PR review checklist for baseline updates.

---

Baseline Naming Convention

Playwright auto-generates snapshot names using the pattern:

<test-name>-<project>-<platform>.png

Examples:

Environment	Generated filename
CI (Linux, chromium project)	hero-desktop-chromium-linux.png
Local macOS (chromium project)	hero-desktop-chromium-darwin.png
Local Windows (chromium project)	hero-desktop-chromium-win32.png

Platform suffixes ensure that Linux CI baselines are never overwritten by local captures.

---

Initial Capture Workflow

# 1. Run the visual suite — tests will FAIL on first run (no baselines yet).
npx playwright test --project=visual

# 2. Accept the generated screenshots as baselines.
npx playwright test --project=visual --update-snapshots

# 3. Verify the generated PNGs look correct, then commit.
git add tests/visual/__screenshots__/
git commit -m "chore(visual): add initial baselines"

---

Intentional Baseline Update Workflow

# After a deliberate UI change, regenerate only the affected baselines.
npx playwright test --project=visual --update-snapshots --grep "hero section"

# Review the diff in the Playwright HTML report before committing.
npx playwright show-report

# Commit with a clear message explaining the visual change.
git add tests/visual/__screenshots__/
git commit -m "chore(visual): update hero baselines — new brand colour"

---

Git LFS Configuration

Add to .gitattributes at the repository root:

tests/visual/__screenshots__/**/*.png filter=lfs diff=lfs merge=lfs -text

Initialize LFS if not already configured:

git lfs install
git lfs track "tests/visual/__screenshots__/**/*.png"

---

CI Safety Rules

• Never pass --update-snapshots in CI pipeline scripts.
• Set CI=true in the environment; Playwright will fail tests rather than regenerate missing baselines.
• Store the playwright-report/ artifact in CI so pixel diffs are visible on failure.

# GitHub Actions example
- name: Run visual tests
  run: npx playwright test --project=visual
  env:
    CI: true

- name: Upload visual report
  uses: actions/upload-artifact@v4
  if: failure()
  with:
    name: playwright-visual-report
    path: playwright-report/

---

PR Review Checklist

When a PR modifies baseline PNGs, reviewers must:

1. Open the Playwright HTML report artifact from CI.
2. Confirm that every changed baseline reflects an intentional UI change described in the PR.
3. Reject any baseline update that hides a regression rather than recording an approved change.
4. Check that new baselines were generated on CI (Linux), not on a local macOS or Windows machine.

---

Guidelines

• Baselines committed to main must always originate from CI (Linux) to prevent cross-platform drift.
• Use --update-snapshots locally only to preview what a change looks like; regenerate on CI before merging.
• Tag baseline-update commits with chore(visual): so they are easy to filter in the log.