Skill: visual-project-structure

Skill: visual-project-structure

Scaffold the visual regression test directory layout, configure .gitattributes for Git LFS on PNG baselines, and generate snapshot update helper scripts.

---

Responsibilities

• Emit the canonical directory tree for visual tests.
• Create tests/visual/__screenshots__/ with a .gitkeep so the empty directory is tracked.
• Write .gitattributes entries for PNG LFS tracking.
• Provide snapshot update helper scripts for common workflows.

---

Directory Tree

tests/
└── visual/
    ├── specs/                          # Visual spec files (*.visual.spec.ts)
    │   ├── landing.visual.spec.ts
    │   ├── dashboard.visual.spec.ts
    │   └── components/
    │       ├── button.visual.spec.ts
    │       └── card.visual.spec.ts
    ├── __screenshots__/                # Baseline PNG storage (Git LFS)
    │   ├── .gitkeep
    │   ├── landing-desktop-chromium-linux.png
    │   ├── landing-mobile-chromium-linux.png
    │   └── ...
    └── helpers/
        ├── disable-animations.ts       # Shared animation-disabling utility
        └── update-snapshots.sh         # Baseline update helper script

---

Scaffolding Commands

# Create the directory structure
mkdir -p tests/visual/specs/components
mkdir -p tests/visual/__screenshots__
mkdir -p tests/visual/helpers

# Ensure the empty screenshots directory is tracked by git
touch tests/visual/__screenshots__/.gitkeep
git add tests/visual/__screenshots__/.gitkeep

---

.gitattributes Configuration

Add to .gitattributes at the repository root:

# Visual regression baselines — track with Git LFS
tests/visual/__screenshots__/**/*.png filter=lfs diff=lfs merge=lfs -text

Initialize LFS and apply tracking:

git lfs install
git lfs track "tests/visual/__screenshots__/**/*.png"
# Verify tracking
git lfs ls-files

---

tests/visual/helpers/disable-animations.ts

import { Page } from '@playwright/test';

/**
 * Injects a style tag that sets all CSS animation and transition durations to 0.
 * Call this after navigation and before every toHaveScreenshot() assertion.
 */
export async function disableAnimations(page: Page): Promise<void> {
  await page.addStyleTag({
    content: `
      *, *::before, *::after {
        animation-duration: 0s !important;
        animation-delay: 0s !important;
        transition-duration: 0s !important;
        transition-delay: 0s !important;
      }
    `,
  });
}

---

tests/visual/helpers/update-snapshots.sh

#!/usr/bin/env bash
# Usage:
#   ./tests/visual/helpers/update-snapshots.sh            # update all baselines
#   ./tests/visual/helpers/update-snapshots.sh "hero"     # update matching pattern
set -euo pipefail

PATTERN="${1:-}"

if [[ -n "$PATTERN" ]]; then
  echo "Updating baselines matching: $PATTERN"
  npx playwright test --project=visual --update-snapshots --grep "$PATTERN"
else
  echo "Updating ALL visual baselines"
  npx playwright test --project=visual --update-snapshots
fi

echo ""
echo "Review the diff in the HTML report before committing:"
echo "  npx playwright show-report"
echo ""
echo "Stage changed baselines:"
echo "  git diff --stat tests/visual/__screenshots__/"

Make executable:

chmod +x tests/visual/helpers/update-snapshots.sh

---

Spec File Naming Convention

Surface	File name
Full page	<page-name>.visual.spec.ts
Component	components/<component-name>.visual.spec.ts
Responsive sweep	<page-name>-responsive.visual.spec.ts

---

playwright.config.ts Pointer

export default defineConfig({
  snapshotDir: 'tests/visual/__screenshots__',
  projects: [
    {
      name: 'visual',
      testMatch: 'tests/visual/**/*.visual.spec.ts',
      use: { ...devices['Desktop Chrome'], viewport: { width: 1280, height: 800 } },
    },
  ],
});

---

Guidelines

• Keep specs in tests/visual/specs/; never mix visual specs with functional E2E specs.
• The __screenshots__/ directory must be tracked by Git (or Git LFS for large repos); do not gitignore it.
• Import disableAnimations from the shared helper rather than inlining the style tag in every spec.
• Run the update script locally and review with npx playwright show-report before staging baseline changes.