community-rule/docs/SNAPSHOT_WORKFLOW.md

Visual Regression Snapshot Workflow

Quick reference for managing visual regression snapshots.

🚀 First-Time Setup

# 1. Generate baseline snapshots (choose one)
npm run seed-snapshots        # Docker (recommended for CI consistency)
npm run seed-snapshots:local  # Local environment

# 2. Commit the snapshots
git add tests/e2e/visual-regression.spec.ts-snapshots/
git commit -m "Add baseline visual regression snapshots"

# 3. Verify setup
npm run visual:test

🔄 Daily Workflow

# Run visual regression tests
npm run visual:test

# Run with UI for debugging
npm run visual:ui

# Update snapshots after UI changes
npm run visual:update

📝 When UI Changes

1. Make your UI changes (design updates, component modifications, etc.)

2. Update snapshots to reflect new design:

   npm run visual:update
   

3. Review changes:

   git diff tests/e2e/visual-regression.spec.ts-snapshots/
   

4. Commit updated snapshots:

   git add tests/e2e/visual-regression.spec.ts-snapshots/
   git commit -m "Update snapshots for [describe changes]"
   

🐛 Troubleshooting

"Snapshot doesn't exist" errors

• Cause: Baseline snapshots haven't been generated
• Fix: Run npm run seed-snapshots:local

Platform differences (macOS vs Linux)

• Cause: Different font rendering between platforms
• Fix: Use npm run seed-snapshots (Docker container)

Minor pixel differences

• Cause: Font rendering, anti-aliasing differences
• Fix: Check tolerance settings in playwright.config.ts

Animation-related failures

• Cause: Animations not fully disabled
• Fix: Ensure animations: "disabled" is set (already configured)

📁 File Structure

tests/e2e/
├── visual-regression.spec.ts                    # Test definitions
└── visual-regression.spec.ts-snapshots/         # Baseline images
    ├── homepage-full-chromium.png
    ├── homepage-viewport-chromium.png
    ├── hero-banner-chromium.png
    └── ...

⚡ Quick Commands Reference

Command	Purpose
npm run visual:test	Run visual regression tests
npm run visual:update	Update snapshots after UI changes
npm run visual:ui	Run tests with UI for debugging
npm run seed-snapshots	Generate baselines with Docker (CI consistency)
npm run seed-snapshots:local	Generate baselines locally

💡 Best Practices

1. Always review changes before committing updated snapshots
2. Use descriptive commit messages when updating snapshots
3. Test locally first before pushing to CI
4. Use Docker for consistency when generating baselines
5. Update snapshots promptly after UI changes to avoid drift

🔗 Related Documentation

• Visual Regression Setup - Detailed setup guide
• Testing Strategy - Overall testing approach