ci(e2e): wait for stable doc screenshots, strip exclude-from-example-doc lines (#4429)

Doc screenshots are now taken once two consecutive screenshots match (status bar
left out), with a 10 s cap. UserLocationUpdates is excluded from Percy as it shows
a wall-clock timestamp. example-docs.ts drops lines ending with
// exclude-from-example-doc and blocks between exclude-from-example-doc:start/end.

Author: mfazekas

AGENTS.md

@@ -128,6 +128,7 @@ The project uses Mapbox Maps SDK v11 and React Native's New Architecture (Fabric
 - Component docs are auto-generated from JSDoc comments
 - Don't edit `.md` files in `docs/` directly - edit source files and run `yarn generate`
 - Examples in `example/src/examples/` are used for documentation
+- Example doc pages show the source up to `/* end-example-doc */` (keep metadata after it), without lines ending in `// exclude-from-example-doc` or between `/* exclude-from-example-doc:start */` and `/* exclude-from-example-doc:end */`
 
 ### Fixing Bugs
 

CONTRIBUTING.md

@@ -123,6 +123,8 @@ The full documentation generation process looks like this:
   bun scripts/example-docs.ts
   ```
 
+  The doc page shows the example source up to `/* end-example-doc */`, so metadata and test-only code go after it. Lines ending with `// exclude-from-example-doc`, and lines between `/* exclude-from-example-doc:start */` and `/* exclude-from-example-doc:end */`, are left out too.
+
   Runs when `main` is changed by `update-docs` gh action workflow
 
 6.) publish doc site

docs/examples.json

@@ -273,7 +273,8 @@
             "UserLocation#onUpdate"
           ],
           "docs": "\nRetrieves and shows location updates from UserLocation component via the `onUpdate` callback\n",
-          "waitForMapIdle": false
+          "waitForMapIdle": false,
+          "excludeFromPercy": true
         },
         "fullPath": "example/src/examples/UserLocation/UserLocationUpdates.tsx",
         "relPath": "UserLocation/UserLocationUpdates.tsx",

example/e2e/changedPixels.js

@@ -0,0 +1,34 @@
+/**
+ * @file node changedPixels.js <a.png> <b.png> <top> <screenWidth>
+ * Prints the number of pixels that differ between two screenshots, leaving out their top <top> points, <screenWidth> being the screen width in points.
+ */
+
+const fs = require('fs');
+const { PNG } = require('pngjs');
+
+const [aPath, bPath, top, screenWidth] = process.argv.slice(2);
+
+const a = PNG.sync.read(fs.readFileSync(aPath));
+const b = PNG.sync.read(fs.readFileSync(bPath));
+if (a.width !== b.width || a.height !== b.height) {
+  process.stdout.write(String(a.width * a.height));
+  process.exit(0);
+}
+const topPx = Math.round((Number(top) * a.width) / Number(screenWidth));
+const a32 = new Uint32Array(
+  a.data.buffer,
+  a.data.byteOffset,
+  a.data.length / 4,
+);
+const b32 = new Uint32Array(
+  b.data.buffer,
+  b.data.byteOffset,
+  b.data.length / 4,
+);
+let changed = 0;
+for (let i = topPx * a.width; i < a32.length; i++) {
+  if (a32[i] !== b32[i]) {
+    changed++;
+  }
+}
+process.stdout.write(String(changed));

example/e2e/docScreenshots.e2e.js

@@ -7,7 +7,8 @@
 const { mkdir, copyFile } = require('fs/promises');
 const fs = require('fs');
 const path = require('path');
-const { execSync, execFileSync } = require('child_process');
+const { promisify } = require('util');
+const { execSync, execFileSync, execFile } = require('child_process');
 
 const { device } = require('detox');
 
@@ -83,8 +84,7 @@ async function setSampleLocation() {
   execSync(`xcrun simctl location ${device.id} set ${latitude},${longitude}`);
 }
 
-async function saveImage(basePath, suffix = null) {
-  const imagePath = await device.takeScreenshot(`example-${suffix || ''}`);
+async function saveImage(imagePath, basePath, suffix = null) {
   const destDir = path.dirname(basePath);
   await mkdir(destDir, { recursive: true });
   var fullDestPath = basePath;
@@ -124,6 +124,44 @@ async function savePercyImage(imagePath, groupName, name) {
   ]);
 }
 
+const STABLE_INTERVAL_MS = 500;
+const STABLE_TIMEOUT_MS = 10000;
+const STABLE_MAX_CHANGED_PIXELS = 10;
+
+// Compared in a separate process for the same reason as savePercyImage.
+async function changedPixels(aPath, bPath) {
+  const { frame, safeAreaInsets } = rootViewAttributes;
+  const { stdout } = await promisify(execFile)(process.execPath, [
+    path.join(__dirname, 'changedPixels.js'),
+    aPath,
+    bPath,
+    String(safeAreaInsets.top),
+    String(frame.width),
+  ]);
+  return Number(stdout);
+}
+
+// Labels and tiles can still change after the maps report idle, so wait until two
+// consecutive screenshots match.
+async function takeStableScreenshot(name) {
+  const start = Date.now();
+  let previous = await device.takeScreenshot(`${name}-0`);
+  for (let i = 1; ; i++) {
+    await new Promise((resolve) => setTimeout(resolve, STABLE_INTERVAL_MS));
+    const current = await device.takeScreenshot(`${name}-${i}`);
+    if ((await changedPixels(previous, current)) <= STABLE_MAX_CHANGED_PIXELS) {
+      return current;
+    }
+    if (Date.now() - start >= STABLE_TIMEOUT_MS) {
+      console.warn(
+        `${name}: screenshot still changing after ${STABLE_TIMEOUT_MS} ms, keeping the last one.`,
+      );
+      return current;
+    }
+    previous = current;
+  }
+}
+
 async function wait(ms) {
   try {
     await waitFor(element(by.id('no-such-view')))
@@ -207,7 +245,11 @@ class ExampleScreenshots {
       screenshotsDict[basename] = { images: [] };
     }
 
-    const imgPath = await saveImage(path.join(groupDir, basename), suffix);
+    const imgPath = await saveImage(
+      await takeStableScreenshot(basename),
+      path.join(groupDir, basename),
+      suffix,
+    );
     screenshotsDict[basename].images.push(
       path.relative(docSiteRootPath, path.resolve(imgPath)),
     );
@@ -255,9 +297,7 @@ describe('Example screenshots', () => {
                 cellularBars: '4',
               });
               await setSampleLocation();
-              if (percyScreenshotsPath) {
-                await readRootViewAttributes();
-              }
+              await readRootViewAttributes();
 
               await waitFor(element(by.text(groupMetadata.title)))
                 .toBeVisible()

example/src/examples/UserLocation/UserLocationUpdates.tsx

@@ -48,5 +48,6 @@ const metadata: ExampleWithMetadata['metadata'] = {
 Retrieves and shows location updates from UserLocation component via the \`onUpdate\` callback
 `,
   waitForMapIdle: false,
+  excludeFromPercy: true,
 };
 UserLocationUpdates.metadata = metadata;

scripts/example-docs.ts

@@ -14,11 +14,34 @@ import {
   mapsRootPath,
 } from './autogenHelpers/docconfig.js';
 
-const endOfExampleMarker = '/* end-example-doc */';
-
 import type { Examples } from './autogenHelpers/examplesJsonSchema';
 import type { Screenshots } from './autogenHelpers/screenshotsJsonSchema';
 
+const endOfExampleMarker = '/* end-example-doc */';
+const excludeLineMarker = '// exclude-from-example-doc';
+const excludeStartMarker = '/* exclude-from-example-doc:start */';
+const excludeEndMarker = '/* exclude-from-example-doc:end */';
+
+function stripExcludedLines(code: string): string {
+  let excluding = false;
+  return code
+    .split('\n')
+    .filter((line) => {
+      const trimmed = line.trim();
+      if (trimmed === excludeStartMarker) {
+        excluding = true;
+        return false;
+      }
+      if (trimmed === excludeEndMarker) {
+        excluding = false;
+        return false;
+      }
+      return !excluding && !trimmed.endsWith(excludeLineMarker);
+    })
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n');
+}
+
 // Published by .github/workflows/update-docs.yml, see the linking config in example/src/App.js
 const webExampleAppURL = 'https://rnmapbox.github.io/example-app/';
 
@@ -49,6 +72,7 @@ examples.forEach(({ groupName, examples: _examples, metadata: _metadata }) => {
     if (endOfMarkerIndex > 0) {
       jscode = jscode.slice(0, endOfMarkerIndex);
     }
+    jscode = stripExcludedLines(jscode);
 
     const mdPath = path.join(destGroupDir, `${name}.md`);