add update-int-snapshots claude skill

2026-08-07 10:14:44 +00:00 · 2026-05-23 10:50:38 -07:00
parent 4bf94b0486
commit 65b515e533
1 changed files with 62 additions and 0 deletions
@@ -0,0 +1,62 @@
+---
+name: update-int-snapshots
+description: Use when Playwright visual snapshots in e2e/visual.spec.ts-snapshots/ need to be regenerated after a UI change (logo, theme, layout, anything that affects rendered pixels) and the integration suite needs to be rerun via make int
+---
+
+# Update Integration Snapshots
+
+## When to Use
+
+- A visual change landed (logo, color, spacing, fonts) and `make int` will fail on `visual.spec.ts` until snapshots are regenerated.
+- A snapshot test reports diffs you've confirmed are intentional.
+
+Do NOT use when diffs are unintentional regressions — investigate first.
+
+## Procedure
+
+1. **Delete the stale snapshots** so Playwright writes fresh ones (don't try to update in place, the old PNGs can confuse the diff):
+
+   ```bash
+   rm e2e/visual.spec.ts-snapshots/*.png
+   ```
+
+2. **Check for port 8080 conflicts.** The `custom_base` test container binds host port 8080. If another container is already on it (common: `doligence-api-1`), the run fails with `Bind for 0.0.0.0:8080 failed: port is already allocated`.
+
+   ```bash
+   docker ps --format '{{.Names}}\t{{.Ports}}' | grep ':8080->'
+   ```
+
+   If anything other than test containers is bound, stop it first (ask the user before stopping containers from other projects).
+
+3. **Run Playwright with `--update-snapshots`.** Bypass the Makefile so we can pass the flag:
+
+   ```bash
+   docker compose run --rm --build playwright npx playwright test --update-snapshots
+   ```
+
+   Snapshots must be generated in Linux/Chromium (the compose image), not macOS, because filenames include the platform suffix (e.g. `-chromium-linux.png`).
+
+4. **Verify** by rerunning the normal suite:
+
+   ```bash
+   make int
+   ```
+
+   Should now pass cleanly.
+
+5. **Commit the regenerated PNGs** alongside the UI change so CI stays green.
+
+## Common Mistakes
+
+- **Running `npx playwright test --update-snapshots` locally on macOS.** Generates `-darwin` filenames CI doesn't use. Always go through the docker compose image.
+- **Forgetting to delete first.** `--update-snapshots` does overwrite, but if the test layout changed (new test, renamed snapshot), stale PNGs are left behind. Wipe-and-regenerate is safest.
+- **Stopping unrelated containers without asking.** The port conflict is annoying but the user's other dev containers may be holding important state.
+
+## Quick Reference
+
+| Step            | Command                                                                             |
+| --------------- | ----------------------------------------------------------------------------------- |
+| Wipe snapshots  | `rm e2e/visual.spec.ts-snapshots/*.png`                                             |
+| Check port 8080 | `docker ps \| grep ':8080->'`                                                       |
+| Regenerate      | `docker compose run --rm --build playwright npx playwright test --update-snapshots` |
+| Verify          | `make int`                                                                          |