@ralphralphai/playwright 2.6.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-H-EycbCA.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-CGIMWRQM.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-H-EycbCA.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-CGIMWRQM.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-CGIMWRQM.mjs → upload-CcdDM33Z.mjs}

@@ -45,7 +45,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "2.6.0";
+var version = "2.8.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -526,30 +526,57 @@ async function waitForAnimations(page, timeoutMs) {
 //#region src/image_responses.ts
 const IMAGE_HASH_TIMEOUT_MS = 3e4;
 const hashesByPage = /* @__PURE__ */ new WeakMap();
+/**
+* The latest hash per url across all of a context's pages. The HTTP cache is
+* shared by the context, so this is the copy a 304 tells any of them to reuse.
+*/
+const hashesByContext = /* @__PURE__ */ new WeakMap();
 function sha256(data) {
 	return createHash("sha256").update(data).digest("hex");
 }
 /**
-* Hashes every image the page loads, as it loads, so a snapshot hashes the
-* bytes the page showed instead of fetching them a second time. A second fetch
-* of a page's images comes as a burst, which hosts such as
+* Hashes every image the context's pages load, as they load, so a snapshot
+* hashes the bytes the page showed instead of fetching them a second time. A
+* second fetch of a page's images comes as a burst, which hosts such as
 * upload.wikimedia.org answer with 429 for a share of them, and the image then
 * reads as replaced. Only the hash is kept, not the body. Entries persist
 * across navigations until another request for the same image replaces them
 * or the page closes.
+*
+* Watched on the context rather than each page: Playwright reports a popup
+* only once its first navigation has committed, and the images that document
+* requests early are gone by the time a listener can be added to the page.
 */
-function watchImageResponses(page) {
-	if (hashesByPage.has(page)) return;
-	const hashes = /* @__PURE__ */ new Map();
-	hashesByPage.set(page, hashes);
-	page.on("request", (request) => {
-		if (request.resourceType() !== "image") return;
+function watchImageResponses(context) {
+	if (hashesByContext.has(context)) return;
+	const latest = /* @__PURE__ */ new Map();
+	hashesByContext.set(context, latest);
+	context.on("request", (request) => {
+		if (request.resourceType() !== "image" || request.serviceWorker()) return;
+		const hashes = pageHashes(request.frame().page());
+		const cached = latest.get(request.url());
 		const hash = request.response().then(async (response) => {
+			if (response?.status() === 304) return cached;
 			return response?.ok() ? sha256(await response.body()) : void 0;
 		}).catch(() => void 0);
-		for (let redirected = request; redirected !== null; redirected = redirected.redirectedFrom()) hashes.set(redirected.url(), hash);
+		for (const url of redirectChain(request)) {
+			hashes.set(url, hash);
+			latest.set(url, hash);
+		}
 	});
+}
+function pageHashes(page) {
+	const existing = hashesByPage.get(page);
+	if (existing) return existing;
+	const hashes = /* @__PURE__ */ new Map();
+	hashesByPage.set(page, hashes);
 	page.once("close", () => hashesByPage.delete(page));
+	return hashes;
+}
+function redirectChain(request) {
+	const urls = [];
+	for (let redirected = request; redirected !== null; redirected = redirected.redirectedFrom()) urls.push(redirected.url());
+	return urls;
 }
 /**
 * The hash from the latest observed request for this URL, across navigations.
@@ -623,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,
@@ -635,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;
 }
@@ -822,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;
@@ -846,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 }
 			};
 		}, {
@@ -883,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;
@@ -905,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 },
@@ -1399,6 +1454,7 @@ var Recorder = class {
 			freezer
 		});
 		this.actions.observe(context);
+		watchImageResponses(context);
 		context.on("page", onPage);
 		for (const page of context.pages()) onPage(page);
 		return ready;
@@ -1499,7 +1555,6 @@ var Recorder = class {
 			}
 		}).catch(() => void 0);
 		page.on("framenavigated", state.onNavigation);
-		watchImageResponses(page);
 		this.urlChanged(state);
 	}
 	urlChanged(state) {
@@ -1592,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();
@@ -2026,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-CGIMWRQM.mjs.map
+//# sourceMappingURL=upload-CcdDM33Z.mjs.map