fix(visual-diff): reduce false positives and cache prod screenshots (#1397)

- Freeze CSS animations/transitions via injected stylesheet before
  capturing to eliminate mid-animation pixel differences
- Replace details expansion click+timeout with direct open attribute
  set and waitForFunction poll to avoid framework re-render races
- Switch waitUntil from networkidle to load for faster, deterministic
  page readiness
- Add --disable-font-subpixel-positioning and --disable-lcd-text
  Chromium flags for consistent text rasterization across captures
- Skip prod screenshot when file already exists on disk; pair with
  a workflow cache keyed on the production sitemap SHA-256 hash so
  prod pages are only re-screenshotted when the live site changes

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: sserrata

.github/workflows/deploy-preview.yml

@@ -208,6 +208,20 @@ jobs:
       - name: Install Playwright
         run: npx playwright install --with-deps chromium
 
+      - name: Get production sitemap hash
+        id: sitemap-hash
+        run: |
+          hash=$(curl -fsSL https://docusaurus-openapi.tryingpan.dev/sitemap.xml | sha256sum | cut -d' ' -f1)
+          echo "hash=$hash" >> "$GITHUB_OUTPUT"
+
+      - name: Restore cached production screenshots
+        uses: actions/cache@v4
+        with:
+          path: visual_diffs/prod
+          key: prod-screenshots-${{ steps.sitemap-hash.outputs.hash }}
+          restore-keys: |
+            prod-screenshots-
+
       - name: Run visual diff
         run: yarn ts-node scripts/sitemap-visual-diff.ts --preview-url ${{ needs.deploy.outputs.preview_url }} --summary-file visual_diffs/results.json --concurrency 4 --paths "/tests/"
 

scripts/sitemap-visual-diff.ts

@@ -98,17 +98,31 @@ function parseUrlsFromSitemap(xml: string): string[] {
 }
 
 async function screenshotFullPage(page: any, url: string, outputPath: string) {
-  await page.goto(url, { waitUntil: "networkidle" });
+  await page.goto(url, { waitUntil: "load" });
+  // Freeze all CSS animations and transitions before screenshotting so that
+  // mid-animation frames don't produce spurious pixel differences.
+  await page.addStyleTag({
+    content: `*, *::before, *::after {
+      animation-duration: 0s !important;
+      animation-delay: 0s !important;
+      transition-duration: 0s !important;
+      transition-delay: 0s !important;
+    }`,
+  });
+  // Expand details elements by setting the attribute directly; avoid
+  // simulating clicks, which can fire framework event handlers and cause
+  // re-renders that race with the subsequent screenshot.
   await page.evaluate(() => {
     document.querySelectorAll("div.container details").forEach((el) => {
-      const detail = el as HTMLDetailsElement;
-      const summary = detail.querySelector("summary");
-      if (!detail.open && summary) (summary as HTMLElement).click();
-      detail.open = true;
-      detail.setAttribute("data-collapsed", "false");
+      (el as HTMLDetailsElement).open = true;
     });
   });
-  await page.waitForTimeout(500);
+  // Wait until every details element is confirmed open before capturing.
+  await page.waitForFunction(
+    () =>
+      document.querySelectorAll("div.container details:not([open])").length ===
+      0
+  );
   await fs.promises.mkdir(path.dirname(outputPath), { recursive: true });
   const container = await page.$("div.container");
   if (container) {
@@ -201,7 +215,9 @@ async function run() {
   }
   console.log(`Found ${paths.length} paths.`);
 
-  const browser = await chromium.launch();
+  const browser = await chromium.launch({
+    args: ["--disable-font-subpixel-positioning", "--disable-lcd-text"],
+  });
   const context = await browser.newContext({
     viewport: { width: opts.width, height: opts.viewHeight },
   });
@@ -220,7 +236,11 @@ async function run() {
     const diffImg = path.join(opts.outputDir, "diff", `${cleanPath}.png`);
     const page = await context.newPage();
     try {
-      await screenshotFullPage(page, url, prodSnap);
+      if (fs.existsSync(prodSnap)) {
+        console.log(`CACHED prod: /${cleanPath}`);
+      } else {
+        await screenshotFullPage(page, url, prodSnap);
+      }
       await screenshotFullPage(
         page,
         new URL(cleanPath, opts.previewUrl).toString(),