@ralphralphai/playwright 2.7.0 → 2.8.0

package/README.md

@@ -254,6 +254,24 @@ Pass an `edgeLabel` to describe the step in your own words, e.g.
 `ralph.recordNode(page, { name: 'Done', edgeLabel: 'Sign in' })`. A later call
 without one keeps it.
 
+### Excluding elements from snapshots
+
+For parts of the page that change on their own, such as ads, chat widgets or
+live counters, list CSS selectors in `ignoreInDiff`:
+
+```ts
+ralphOptions: {
+  ignoreInDiff: ['.ad-slot', '#intercom-container', 'live-clock'],
+},
+```
+
+Matched elements and their descendants, including content in open shadow roots
+and slots, are left out of the ARIA snapshot used for diffing. They still appear
+in the screenshot, and the space they take up still moves the elements around
+them. Text that sits inline in a larger element, like a bare `<span>` in a
+paragraph, belongs to that element's text and is not removed. Wrap it in an
+element with a role, or match the whole paragraph.
+
 ### When recording fails
 
 - A failed `recordNode` call rejects.
@@ -414,6 +432,7 @@ export default defineConfig<RalphFixtures>({
 | `ready`               |                          | `(page, signal) => Promise<void>`. Waits for your app before an automatic recording. Honor `signal`. |
 | `reduceMotion`        | `false`                  | Emulates `prefers-reduced-motion: reduce` and waits for finite animations before recording.          |
 | `freezeDuringCapture` | `false`                  | Finishes finite browser animations, allows JS-driven DOM changes to settle within a bounded wait, then freezes timers and animations across capture. |
+| `ignoreInDiff`        |                          | CSS selectors for subtrees to omit from the ARIA snapshot. See [Excluding elements from snapshots](#excluding-elements-from-snapshots). |
 | `strictNodeTags`      | `false`                  | Fails the test when the app reports a tag outside what `ralph.setNodeConditions` declared.           |
 | `ignoreUntaggedCalls` | `false`                  | Makes `recordNode`, `setNodeConditions`, and `observe` no-ops in untagged tests instead of throwing. |
 

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_upload = require("./upload-_UWss__c.cjs");
+const require_upload = require("./upload-KEwXpYxG.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let _playwright_test = require("@playwright/test");

package/dist/index.d.mts

@@ -18,6 +18,11 @@ type RalphOptions = {
    */
   freezeDuringCapture?: boolean;
   recordTimeoutMs?: number;
+  /**
+   * CSS selectors for subtrees the diff ignores, such as an ad slot or a chat
+   * widget. They are left out of the aria snapshot but stay in the screenshot.
+   */
+  ignoreInDiff?: string[];
   ready?: (page: Page, signal: AbortSignal) => Promise<void>;
   /**
    * Fail the test when the app reports a tag outside the set the test

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as resolveMode, a as prepareArtifactUpload, f as Recorder, g as loadConfigSync, h as loadConfig, i as createRawGraphBundle, l as uploadRawGraph, p as visitAllLinks, u as MANIFEST_ATTACHMENT } from "./upload-BsCzkoup.mjs";
+import { _ as resolveMode, a as prepareArtifactUpload, f as Recorder, g as loadConfigSync, h as loadConfig, i as createRawGraphBundle, l as uploadRawGraph, p as visitAllLinks, u as MANIFEST_ATTACHMENT } from "./upload-CcdDM33Z.mjs";
 import path from "node:path";
 import { expect, mergeTests, test as test$1 } from "@playwright/test";
 //#region src/screens.ts

package/dist/reporter.cjs

@@ -1,4 +1,4 @@
-const require_upload = require("./upload-_UWss__c.cjs");
+const require_upload = require("./upload-KEwXpYxG.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let node_fs_promises = require("node:fs/promises");

package/dist/reporter.mjs

@@ -1,4 +1,4 @@
-import { _ as resolveMode, a as prepareArtifactUpload, c as resultLink, d as REPORTER_ENV, l as uploadRawGraph, m as version, n as bundleImagePath, o as registerDeployment, r as bundleSnapshotPath, s as resolveUploadOptions, t as RAW_GRAPH_BUNDLE_INDEX, u as MANIFEST_ATTACHMENT } from "./upload-BsCzkoup.mjs";
+import { _ as resolveMode, a as prepareArtifactUpload, c as resultLink, d as REPORTER_ENV, l as uploadRawGraph, m as version, n as bundleImagePath, o as registerDeployment, r as bundleSnapshotPath, s as resolveUploadOptions, t as RAW_GRAPH_BUNDLE_INDEX, u as MANIFEST_ATTACHMENT } from "./upload-CcdDM33Z.mjs";
 import path from "node:path";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";

package/dist/{upload-BsCzkoup.mjs → upload-CcdDM33Z.mjs}

@@ -45,7 +45,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "2.7.0";
+var version = "2.8.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -650,7 +650,7 @@ const MIN_IFRAME_SIZE = 5;
 * screenshot just showed: sticky headers, lazy loading, scroll-triggered
 * animation.
 */
-async function captureAriaSnapshot(page, { viewport, scroll }) {
+async function captureAriaSnapshot(page, { viewport, scroll }, ignore = []) {
 	const snapshot = await page.locator("body").ariaSnapshotJSON({
 		mode: "ai",
 		boxes: true,
@@ -662,7 +662,10 @@ async function captureAriaSnapshot(page, { viewport, scroll }) {
 		const kept = keepShown(node, viewport.width, clips, void 0);
 		return kept === void 0 ? [] : [kept];
 	});
-	const described = await Promise.all(visible.map((node) => describe(page, node, {}, false)));
+	const ignoreSelector = ignore.length === 0 ? void 0 : ignore.join(", ");
+	const facts = /* @__PURE__ */ new Map();
+	const normalized = (await Promise.all(visible.map((node) => readTree(page, node, ignoreSelector, facts)))).filter((node) => node !== void 0);
+	const described = await Promise.all(normalized.map((node) => describe(page, node, {}, false, facts)));
 	const json = Buffer.from(JSON.stringify(fillMissingRefs(described)));
 	return json.byteLength > 4194304 ? void 0 : json;
 }
@@ -849,12 +852,14 @@ function keepShown(node, viewportWidth, clips, inherited) {
 		return kept === void 0 ? [] : [kept];
 	});
 	if (!shown && children.length === 0) return;
-	const [only] = children;
-	if (node.role === "generic" && !node.name && (node.children?.length ?? 0) > 1 && children.length === 1 && typeof only !== "string" && only?.ref !== void 0) return only;
-	return node.children === void 0 ? node : {
+	return loneChild(node, children) ?? (node.children === void 0 ? node : {
 		...node,
 		children
-	};
+	});
+}
+function loneChild(node, children) {
+	const [only] = children;
+	if (node.role === "generic" && !node.name && (node.children?.length ?? 0) > 1 && children.length === 1 && typeof only !== "string" && only?.ref !== void 0) return only;
 }
 function fillMissingRefs(nodes) {
 	let generated = 0;
@@ -873,34 +878,40 @@ function fillMissingRefs(nodes) {
 	};
 	return nodes.map(fill);
 }
-async function readElement(page, ref, isImage) {
+async function readElement(page, ref, isImage, ignoreSelector) {
 	try {
-		return await page.locator(`aria-ref=${ref}`).evaluate((element, { properties, isImage, dynamicAttribute }) => {
+		return await page.locator(`aria-ref=${ref}`).evaluate((element, { properties, isImage, dynamicAttribute, ignoreSelector }) => {
 			const computed = getComputedStyle(element);
 			const typed = "computedStyleMap" in element ? element.computedStyleMap() : void 0;
 			const style = Object.fromEntries(properties.map((property) => [property, property.startsWith("margin-") && typed?.get(property)?.toString() === "auto" ? "auto" : computed.getPropertyValue(property)]));
 			const dynamic = element.closest(`[${dynamicAttribute}]`) !== null;
-			if (!isImage) return {
+			let ignored = false;
+			for (let at = element; ignoreSelector !== void 0 && at !== null && !ignored;) {
+				try {
+					ignored = at.matches(ignoreSelector);
+				} catch {
+					break;
+				}
+				const root = at.getRootNode();
+				at = at.assignedSlot ?? at.parentElement ?? (root instanceof ShadowRoot ? root.host : null);
+			}
+			const facts = {
 				style,
-				dynamic
+				dynamic,
+				ignored
 			};
+			if (!isImage) return facts;
 			if (element instanceof HTMLImageElement) return {
-				style,
-				dynamic,
+				...facts,
 				image: { src: element.currentSrc || element.src }
 			};
 			if (element instanceof SVGElement) return {
-				style,
-				dynamic,
+				...facts,
 				image: { markup: element.outerHTML }
 			};
 			const backgroundUrl = /url\("(.+)"\)/.exec(computed.backgroundImage)?.[1];
-			return backgroundUrl === void 0 ? {
-				style,
-				dynamic
-			} : {
-				style,
-				dynamic,
+			return backgroundUrl === void 0 ? facts : {
+				...facts,
 				image: { src: new URL(backgroundUrl, document.baseURI).href }
 			};
 		}, {
@@ -910,7 +921,8 @@ async function readElement(page, ref, isImage) {
 				...isImage ? Object.keys(IMAGE_PROPERTIES) : []
 			],
 			isImage,
-			dynamicAttribute: DYNAMIC_ATTRIBUTE
+			dynamicAttribute: DYNAMIC_ATTRIBUTE,
+			ignoreSelector
 		}, { timeout: ELEMENT_LOOKUP_TIMEOUT_MS });
 	} catch {
 		return;
@@ -932,13 +944,29 @@ function distinctStyle(style, inherited) {
 	});
 	return distinct.length === 0 ? void 0 : Object.fromEntries(distinct);
 }
-async function describe(page, child, inherited, insideDynamic) {
+async function readTree(page, child, ignoreSelector, factsByRef) {
+	if (typeof child === "string") return child;
+	const facts = child.ref === void 0 ? void 0 : await readElement(page, child.ref, child.role === "img", ignoreSelector);
+	if (facts?.ignored) return;
+	if (child.ref !== void 0 && facts !== void 0) factsByRef.set(child.ref, facts);
+	const children = child.children === void 0 ? void 0 : (await Promise.all(child.children.map((grandchild) => readTree(page, grandchild, ignoreSelector, factsByRef)))).filter((grandchild) => grandchild !== void 0);
+	if (children !== void 0) {
+		if (children.length === 0 && (child.ref === void 0 || child.role === "generic" && !child.name && (child.children?.length ?? 0) > 0)) return;
+		const only = loneChild(child, children);
+		if (only !== void 0) return only;
+	}
+	return children === void 0 ? child : {
+		...child,
+		children
+	};
+}
+async function describe(page, child, inherited, insideDynamic, factsByRef) {
 	if (typeof child === "string") return child;
-	const facts = child.ref === void 0 ? void 0 : await readElement(page, child.ref, child.role === "img");
+	const facts = child.ref === void 0 ? void 0 : factsByRef.get(child.ref);
 	const style = facts === void 0 ? void 0 : distinctStyle(facts.style, inherited);
 	const imageHash = facts?.image === void 0 ? void 0 : await hashImage(page, facts.image);
 	const dynamic = facts?.dynamic === true && !insideDynamic;
-	const children = child.children === void 0 ? void 0 : await Promise.all(child.children.map((grandchild) => describe(page, grandchild, facts?.style ?? inherited, insideDynamic || dynamic)));
+	const children = child.children === void 0 ? void 0 : await Promise.all(child.children.map((grandchild) => describe(page, grandchild, facts?.style ?? inherited, insideDynamic || dynamic, factsByRef)));
 	return {
 		...child,
 		...style && { style },
@@ -1619,7 +1647,7 @@ var Recorder = class {
 					before,
 					image,
 					after,
-					snapshot: await Promise.race([captureAriaSnapshot(page, after).catch(() => void 0), setTimeout$1(Math.max(0, deadline.endsAt - Date.now()), void 0, { ref: false })])
+					snapshot: await Promise.race([captureAriaSnapshot(page, after, this.options.ignoreInDiff).catch(() => void 0), setTimeout$1(Math.max(0, deadline.endsAt - Date.now()), void 0, { ref: false })])
 				};
 			};
 			const { before, image, after, snapshot } = freezer ? await freezer.capture(page, deadline.signal, capture, deadline.endsAt) : await capture();
@@ -2053,4 +2081,4 @@ async function responseDetail(response) {
 //#endregion
 export { resolveMode as _, prepareArtifactUpload as a, resultLink as c, REPORTER_ENV as d, Recorder as f, loadConfigSync as g, loadConfig as h, createRawGraphBundle as i, uploadRawGraph as l, version as m, bundleImagePath as n, registerDeployment as o, visitAllLinks as p, bundleSnapshotPath as r, resolveUploadOptions as s, RAW_GRAPH_BUNDLE_INDEX as t, MANIFEST_ATTACHMENT as u };
 
-//# sourceMappingURL=upload-BsCzkoup.mjs.map
+//# sourceMappingURL=upload-CcdDM33Z.mjs.map