Snapshot management

2025-08-29 16:25:45 -06:00
parent f7f76a2396
commit 6f7baa6f2f
7 changed files with 341 additions and 5 deletions
@@ -0,0 +1,110 @@
+# Visual Regression Snapshot Workflow
+
+Quick reference for managing visual regression snapshots.
+
+## 🚀 **First-Time Setup**
+
+```bash
+# 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**
+
+```bash
+# 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:**
+
+   ```bash
+   npm run visual:update
+   ```
+
+3. **Review changes:**
+
+   ```bash
+   git diff tests/e2e/visual-regression.spec.ts-snapshots/
+   ```
+
+4. **Commit updated snapshots:**
+   ```bash
+   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](./VISUAL_REGRESSION_SETUP.md) - Detailed setup guide
+- [Testing Strategy](../TESTING_STRATEGY.md) - Overall testing approach