@codepress/interactions-playwright 1.0.0 → 1.1.0

package/README.md

@@ -41,6 +41,7 @@ Options (all optional):
 | `routeSegments` | `[]` | literal path segments kept in the default route template (others become `:id`) |
 | `maxElements` | 50000 | element limit |
 | `theme` | the page's `prefers-color-scheme` | `"light"`, `"dark"` or `"unknown"` to record, for apps with their own theme toggle (Playwright's `colorScheme` / `page.emulateMedia` set the default) |
+| `testId` | `defaultTestIdFilter` | `(value, element) => string \| null`: which `data-interaction-id` / `data-testid` values to record, as the browser SDK's [`testId` option](https://github.com/quantfive/codepress-interactions/blob/main/packages/browser/README.md#test-ids-and-privacy). It runs in the page, so it must be self-contained, like a `page.evaluate` callback; a name the page does not have fails the capture. A name the page does have, such as a test variable called `status`, or any other runtime error in the hook, drops the ID with no error, so check the snapshot's IDs when you write a hook. Write out the rule your app uses so fingerprints match production, calling `globalThis.__codepressInteractions.defaultTestIdFilter(value)` where it calls the default. `(value) => value` keeps every ID |
 | `ignoreFingerprints` | `[]` | fingerprints to leave out (known findings accepted for now) |
 | `events` | none | protocol v2 events to run the click and stability checks over too |
 | `checks` and thresholds | see [detect options](https://github.com/quantfive/codepress-interactions/blob/main/packages/browser/README.md#ui-checks) | |

package/dist/index.cjs

@@ -42,12 +42,40 @@ async function captureSnapshot(page, options = {}) {
       routeSegments: options.routeSegments,
       maxElements: options.maxElements,
       theme: options.theme
-    }
+    },
+    testId: typeof options.testId === "function" ? String(options.testId) : null
   };
-  const body = await page.evaluate(async ({ script, options: options2 }) => {
+  const body = await page.evaluate(async ({ script, options: options2, testId }) => {
     const scope = globalThis;
     if (!scope.__codepressInteractions) (0, eval)(script);
-    return scope.__codepressInteractions.walk(options2);
+    if (testId === null) return scope.__codepressInteractions.walk(options2);
+    let filter;
+    try {
+      filter = (0, eval)(`(${testId})`);
+    } catch {
+      try {
+        filter = Object.values((0, eval)(`({${testId}})`))[0];
+      } catch {
+      }
+    }
+    if (typeof filter !== "function")
+      throw new Error("testId must be a self-contained function: bound and native functions cannot run in the page");
+    const hook = filter;
+    let missing = null;
+    const body2 = await scope.__codepressInteractions.walk({
+      ...options2,
+      testId: (value, element) => {
+        try {
+          return hook(value, element);
+        } catch (error) {
+          if (error instanceof ReferenceError) missing ??= error.message;
+          throw error;
+        }
+      }
+    });
+    if (missing !== null)
+      throw new Error(`testId runs in the page and must be self-contained: ${missing}`);
+    return body2;
   }, args);
   const sha256 = (0, import_node_crypto.createHash)("sha256").update(JSON.stringify(body)).digest("hex");
   return { body, sha256 };

package/dist/index.d.cts

@@ -15,6 +15,15 @@ interface CaptureOptions {
     maxElements?: number;
     /** Theme to record when the app has its own toggle. Default: the page's prefers-color-scheme (`colorScheme` in the Playwright config, or `page.emulateMedia`). */
     theme?: "light" | "dark" | "unknown";
+    /**
+     * Test ID filter, as the browser SDK's `testId` option: return the value to
+     * keep it, `null` to drop it. Replaces the default (`defaultTestIdFilter`).
+     * It runs in the page, so like a `page.evaluate` callback it must be
+     * self-contained: no variables from the test file, no imports. Using one
+     * fails the capture. To extend the default, call
+     * `globalThis.__codepressInteractions.defaultTestIdFilter(value)`.
+     */
+    testId?: (value: string, element: Element) => string | null;
 }
 interface Snapshot {
     body: SnapshotBody;

package/dist/index.d.ts

@@ -15,6 +15,15 @@ interface CaptureOptions {
     maxElements?: number;
     /** Theme to record when the app has its own toggle. Default: the page's prefers-color-scheme (`colorScheme` in the Playwright config, or `page.emulateMedia`). */
     theme?: "light" | "dark" | "unknown";
+    /**
+     * Test ID filter, as the browser SDK's `testId` option: return the value to
+     * keep it, `null` to drop it. Replaces the default (`defaultTestIdFilter`).
+     * It runs in the page, so like a `page.evaluate` callback it must be
+     * self-contained: no variables from the test file, no imports. Using one
+     * fails the capture. To extend the default, call
+     * `globalThis.__codepressInteractions.defaultTestIdFilter(value)`.
+     */
+    testId?: (value: string, element: Element) => string | null;
 }
 interface Snapshot {
     body: SnapshotBody;

package/dist/index.js

@@ -19,12 +19,40 @@ async function captureSnapshot(page, options = {}) {
       routeSegments: options.routeSegments,
       maxElements: options.maxElements,
       theme: options.theme
-    }
+    },
+    testId: typeof options.testId === "function" ? String(options.testId) : null
   };
-  const body = await page.evaluate(async ({ script, options: options2 }) => {
+  const body = await page.evaluate(async ({ script, options: options2, testId }) => {
     const scope = globalThis;
     if (!scope.__codepressInteractions) (0, eval)(script);
-    return scope.__codepressInteractions.walk(options2);
+    if (testId === null) return scope.__codepressInteractions.walk(options2);
+    let filter;
+    try {
+      filter = (0, eval)(`(${testId})`);
+    } catch {
+      try {
+        filter = Object.values((0, eval)(`({${testId}})`))[0];
+      } catch {
+      }
+    }
+    if (typeof filter !== "function")
+      throw new Error("testId must be a self-contained function: bound and native functions cannot run in the page");
+    const hook = filter;
+    let missing = null;
+    const body2 = await scope.__codepressInteractions.walk({
+      ...options2,
+      testId: (value, element) => {
+        try {
+          return hook(value, element);
+        } catch (error) {
+          if (error instanceof ReferenceError) missing ??= error.message;
+          throw error;
+        }
+      }
+    });
+    if (missing !== null)
+      throw new Error(`testId runs in the page and must be self-contained: ${missing}`);
+    return body2;
   }, args);
   const sha256 = createHash("sha256").update(JSON.stringify(body)).digest("hex");
   return { body, sha256 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codepress/interactions-playwright",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Playwright helpers that run the CodePress Interactions UI checks in tests: capture a snapshot, list findings, assert none",
   "license": "Apache-2.0",
   "type": "module",
@@ -24,7 +24,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@codepress/interactions-browser": "^1.0.0"
+    "@codepress/interactions-browser": "^1.1.0"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40"