@ralphralphai/playwright 1.9.0 → 2.1.0

package/dist/{upload-BZs6Vqix.mjs → upload-BhHRgN8t.mjs}

@@ -5,7 +5,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import configPackage from "@ralphralphai/config/package.json" with { type: "json" };
 import { WebRalphConfigSchema } from "@ralphralphai/config/zod";
 import { parse, printParseErrorCode } from "jsonc-parser";
-import { randomUUID } from "node:crypto";
+import { createHash, randomUUID } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import playwrightPackage from "@playwright/test/package.json" with { type: "json" };
 import { Readable } from "node:stream";
@@ -45,7 +45,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "1.9.0";
+var version = "2.1.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -522,6 +522,230 @@ async function waitForAnimations(page, timeoutMs) {
 		if (!(error instanceof errors.TimeoutError)) throw error;
 	}
 }
+const MAX_ARIA_DEPTH = Math.floor(128 / 2) - 2;
+const STYLE_PROPERTIES = [
+	"font-family",
+	"font-size",
+	"font-weight",
+	"font-style",
+	"line-height",
+	"letter-spacing",
+	"color",
+	"background-color",
+	"text-align",
+	"text-transform"
+];
+const UNINHERITED_PROPERTIES = {
+	"padding-top": "0px",
+	"padding-right": "0px",
+	"padding-bottom": "0px",
+	"padding-left": "0px",
+	"margin-top": "0px",
+	"margin-right": "0px",
+	"margin-bottom": "0px",
+	"margin-left": "0px",
+	"row-gap": "normal",
+	"column-gap": "normal",
+	"justify-content": "normal",
+	"align-items": "normal",
+	"flex-direction": "row",
+	"grid-template-columns": "none",
+	order: "0",
+	"border-width": "0px",
+	"border-color": "currentcolor",
+	"border-radius": "0px",
+	"box-shadow": "none",
+	opacity: "1",
+	"text-decoration-line": "none"
+};
+const IMAGE_PROPERTIES = {
+	width: "auto",
+	height: "auto"
+};
+const TRANSPARENT = "rgba(0, 0, 0, 0)";
+const ELEMENT_LOOKUP_TIMEOUT_MS = 2e3;
+/**
+* The page's aria tree as JSON, with each element's box in document
+* coordinates, its distinctive styles, and a hash of its image. Undefined when
+* the snapshot is past the server's limits.
+*
+* The page is not scrolled first, because scrolling changes the page the
+* screenshot just showed: sticky headers, lazy loading, scroll-triggered
+* animation.
+*/
+async function captureAriaSnapshot(page, { viewport, scroll }) {
+	const snapshot = await page.locator("body").ariaSnapshotJSON({
+		mode: "ai",
+		boxes: true,
+		depth: MAX_ARIA_DEPTH
+	});
+	const visible = (await Promise.all(snapshot.map((node) => toDocument(page, node, scroll)))).flatMap((node) => {
+		const kept = keepShown(node, viewport.width);
+		return kept === void 0 ? [] : [kept];
+	});
+	const described = await Promise.all(visible.map((node) => describe(page, node, {})));
+	const json = Buffer.from(JSON.stringify(fillMissingRefs(described)));
+	return json.byteLength > 4194304 ? void 0 : json;
+}
+/**
+* Moves the viewport boxes Playwright reports into the full-page screenshot's
+* space. This has to happen before `keepShown`, which in viewport space would
+* drop everything scrolled above the viewport, and no later move brings those
+* back.
+*
+* An iframe's descendants are boxed in its own viewport, so they move by
+* where that viewport sits: the iframe's box plus its border and padding.
+*/
+async function toDocument(page, node, offset) {
+	const box = node.box && {
+		...node.box,
+		x: node.box.x + offset.x,
+		y: node.box.y + offset.y
+	};
+	let childOffset = offset;
+	if (node.role === "iframe" && box !== void 0) {
+		const inset = (node.ref === void 0 ? void 0 : await readContentInset(page, node.ref)) ?? {
+			x: 0,
+			y: 0
+		};
+		childOffset = {
+			x: box.x + inset.x,
+			y: box.y + inset.y
+		};
+	}
+	return {
+		...node,
+		...box && { box },
+		...node.children && { children: await Promise.all(node.children.map((child) => typeof child === "string" ? child : toDocument(page, child, childOffset))) }
+	};
+}
+async function readContentInset(page, ref) {
+	try {
+		return await page.locator(`aria-ref=${ref}`).evaluate((element) => {
+			const computed = getComputedStyle(element);
+			return {
+				x: element.clientLeft + parseFloat(computed.paddingLeft),
+				y: element.clientTop + parseFloat(computed.paddingTop)
+			};
+		}, void 0, { timeout: ELEMENT_LOOKUP_TIMEOUT_MS });
+	} catch {
+		return;
+	}
+}
+/**
+* In document space, the only boxes no scroll reveals are those past the left
+* or right of the viewport's width (a collapsed sidebar, an off-canvas menu)
+* or above the top of the document.
+*/
+function isReachable(box, viewportWidth) {
+	if (box === void 0) return false;
+	return box.x < viewportWidth && box.x + box.width > 0 && box.y + box.height > 0;
+}
+function isShown(node, viewportWidth) {
+	return node.ref !== void 0 && isReachable(node.box, viewportWidth);
+}
+function keepShown(node, viewportWidth) {
+	const shown = isShown(node, viewportWidth);
+	const children = (node.children ?? []).flatMap((child) => {
+		if (typeof child === "string") return shown ? [child] : [];
+		const kept = keepShown(child, viewportWidth);
+		return kept === void 0 ? [] : [kept];
+	});
+	if (!shown && children.length === 0) return;
+	return node.children === void 0 ? node : {
+		...node,
+		children
+	};
+}
+function fillMissingRefs(nodes) {
+	let generated = 0;
+	const fill = (child) => {
+		if (typeof child === "string") return child;
+		generated += 1;
+		const ref = child.ref ?? `n${generated}`;
+		return child.children === void 0 ? {
+			...child,
+			ref
+		} : {
+			...child,
+			ref,
+			children: child.children.map(fill)
+		};
+	};
+	return nodes.map(fill);
+}
+async function readElement(page, ref, isImage) {
+	try {
+		return await page.locator(`aria-ref=${ref}`).evaluate((element, { properties, isImage }) => {
+			const computed = getComputedStyle(element);
+			const style = Object.fromEntries(properties.map((property) => [property, computed.getPropertyValue(property)]));
+			if (!isImage) return { style };
+			if (element instanceof HTMLImageElement) return {
+				style,
+				image: { src: element.currentSrc || element.src }
+			};
+			if (element instanceof SVGElement) return {
+				style,
+				image: { markup: element.outerHTML }
+			};
+			const backgroundUrl = /url\("(.+)"\)/.exec(computed.backgroundImage)?.[1];
+			return backgroundUrl === void 0 ? { style } : {
+				style,
+				image: { src: new URL(backgroundUrl, document.baseURI).href }
+			};
+		}, {
+			properties: [
+				...STYLE_PROPERTIES,
+				...Object.keys(UNINHERITED_PROPERTIES),
+				...isImage ? Object.keys(IMAGE_PROPERTIES) : []
+			],
+			isImage
+		}, { timeout: ELEMENT_LOOKUP_TIMEOUT_MS });
+	} catch {
+		return;
+	}
+}
+function sha256(data) {
+	return createHash("sha256").update(data).digest("hex");
+}
+async function hashImage(page, image) {
+	if ("markup" in image) return sha256(image.markup);
+	if (image.src === "") return;
+	if (image.src.startsWith("data:")) return sha256(image.src);
+	try {
+		const response = await page.request.get(image.src);
+		try {
+			return response.ok() ? sha256(await response.body()) : void 0;
+		} finally {
+			await response.dispose();
+		}
+	} catch {
+		return;
+	}
+}
+function distinctStyle(style, inherited) {
+	const distinct = Object.entries(style).filter(([property, value]) => {
+		if (property === "border-color") return style["border-width"] !== "0px";
+		const initial = UNINHERITED_PROPERTIES[property] ?? IMAGE_PROPERTIES[property];
+		if (initial !== void 0) return value !== initial;
+		if (property === "background-color" && value === TRANSPARENT) return false;
+		return inherited[property] !== value;
+	});
+	return distinct.length === 0 ? void 0 : Object.fromEntries(distinct);
+}
+async function describe(page, child, inherited) {
+	if (typeof child === "string") return child;
+	const facts = child.ref === void 0 ? void 0 : await readElement(page, child.ref, child.role === "img");
+	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 children = child.children === void 0 ? void 0 : await Promise.all(child.children.map((grandchild) => describe(page, grandchild, facts?.style ?? inherited)));
+	return {
+		...child,
+		...style && { style },
+		...imageHash && { imageHash },
+		...children && { children }
+	};
+}
 //#endregion
 //#region src/conditions.ts
 const declared = (declaration = {}) => {
@@ -701,6 +925,8 @@ const MANIFEST_ATTACHMENT = "ralph-raw-graph";
 const REPORTER_ENV = "RALPH_PLAYWRIGHT_REPORTER";
 /** Prefix of the attachment holding each recorded node's screenshot; the node id follows. */
 const SCREENSHOT_ATTACHMENT_PREFIX = "ralph-screenshot-";
+/** Prefix of the attachment holding each recorded node's aria snapshot; the node id follows. */
+const ARIA_SNAPSHOT_ATTACHMENT_PREFIX = "ralph-aria-snapshot-";
 /** Once per worker: a run without the tracker says so once, not per node. */
 let warnedNoTracker = false;
 const DEFAULT_SETTLE_MS = 150;
@@ -918,11 +1144,14 @@ var Recorder = class {
 		const deadline = startDeadline(this.recordTimeoutMs, "Ralph recording timed out.");
 		const { wait } = deadline;
 		const navigatedAway = () => state.generation !== generation || page.url() !== request.actualUrl;
-		const check = () => {
-			deadline.signal.throwIfAborted();
+		const checkPage = () => {
 			if (navigatedAway()) throw new Error("The page navigated before its recording completed.");
 			if (page.isClosed()) throw new Error("The page closed before its recording completed.");
 		};
+		const check = () => {
+			deadline.signal.throwIfAborted();
+			checkPage();
+		};
 		try {
 			check();
 			if (request.trigger !== "explicit") await this.waitForPageToSettle(page, deadline, check);
@@ -948,6 +1177,8 @@ var Recorder = class {
 			check();
 			const after = await wait(readLayout(page));
 			check();
+			const snapshot = await Promise.race([captureAriaSnapshot(page, after).catch(() => void 0), setTimeout$1(Math.max(0, deadline.endsAt - Date.now()), void 0, { ref: false })]);
+			checkPage();
 			const recorded = {
 				...request,
 				...withConditions(conditions),
@@ -957,7 +1188,8 @@ var Recorder = class {
 				recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				layout: before,
 				geometryStable: JSON.stringify(before) === JSON.stringify(after),
-				screenshot: await this.saveScreenshot(request.nodeId, image)
+				screenshot: await this.saveScreenshot(request.nodeId, image),
+				...snapshot && { ariaSnapshot: await this.saveAriaSnapshot(request.nodeId, snapshot) }
 			};
 			const retaken = sameNode ? this.nodes.findIndex(({ nodeId }) => nodeId === state.lastRecorded?.nodeId) : -1;
 			if (retaken === -1) {
@@ -1017,6 +1249,21 @@ var Recorder = class {
 			contentType: image.contentType
 		};
 	}
+	/** Writes the snapshot to the test output and attaches it to the report. */
+	async saveAriaSnapshot(nodeId, snapshot) {
+		const path = "ralph/" + nodeId + ".aria.json";
+		const attachmentName = ARIA_SNAPSHOT_ATTACHMENT_PREFIX + nodeId;
+		await mkdir(this.testInfo.outputPath(OUTPUT_DIR), { recursive: true });
+		await writeFile(this.testInfo.outputPath(path), snapshot);
+		await this.testInfo.attach(attachmentName, {
+			...this.testInfo.config.preserveOutput === "always" ? { path: this.testInfo.outputPath(path) } : { body: snapshot },
+			contentType: "application/json"
+		});
+		return {
+			path,
+			attachmentName
+		};
+	}
 	/** Gives each node the actions taken since the node it was reached from was requested. */
 	attachActions(nodes) {
 		const byId = new Map(nodes.map((item) => [item.nodeId, item]));
@@ -1151,11 +1398,17 @@ function resolveUploadOptions(options) {
 }
 const RAW_GRAPH_BUNDLE_INDEX = "raw_graph.json";
 const RAW_GRAPH_BUNDLE_IMAGE_DIR = "assets/images";
+const RAW_GRAPH_BUNDLE_SNAPSHOT_DIR = "assets/snapshots";
 /** Where a node's screenshot sits inside the bundle. */
 function bundleImagePath(nodeId, contentType) {
 	if (!/^[A-Za-z0-9-]{1,64}$/.test(nodeId)) throw new Error(`Ralph node id is not path-safe: ${nodeId}`);
 	return `${RAW_GRAPH_BUNDLE_IMAGE_DIR}/${nodeId}${imageExtension(contentType)}`;
 }
+/** Where a node's aria snapshot sits inside the bundle. */
+function bundleSnapshotPath(nodeId) {
+	if (!/^[A-Za-z0-9-]{1,64}$/.test(nodeId)) throw new Error(`Ralph node id is not path-safe: ${nodeId}`);
+	return `${RAW_GRAPH_BUNDLE_SNAPSHOT_DIR}/${nodeId}.json`;
+}
 const TOO_BIG = "This run is too big to upload to Ralph. Record fewer pages or screen sizes, or split the tests across runs.";
 var TooBigError = class extends Error {
 	constructor() {
@@ -1166,23 +1419,33 @@ var TooBigError = class extends Error {
 * Packs the manifest and screenshots into a gzipped tar archive, produced as it
 * is read so the compressed bundle is never held whole:
 *
-*   raw_graph.json               { manifest, screenshots: [{ nodeId, path }] }
+*   raw_graph.json             { manifest, screenshots: [{ nodeId, path }], snapshots: [...] }
 *   assets/images/<id>.webp    raw screenshot bytes (.png when too large for WebP)
+*   assets/snapshots/<id>.json the node's aria snapshot, when it has one
 *
 * Fails with a `TooBigError` once the compressed bytes pass the limit.
 */
-function rawGraphBundleStream(manifest, screenshots) {
+function rawGraphBundleStream(manifest, screenshots, snapshots) {
 	if (Buffer.byteLength(JSON.stringify(manifest)) > 16777216 || screenshots.length > 5e3 || screenshots.reduce((total, screenshot) => total + screenshot.bytes.byteLength, 0) > 268435456) throw new TooBigError();
 	const images = screenshots.map(({ nodeId, contentType, bytes }) => ({
 		nodeId,
 		path: bundleImagePath(nodeId, contentType),
 		bytes
 	}));
+	const files = [...images, ...snapshots.map(({ nodeId, bytes }) => ({
+		nodeId,
+		path: bundleSnapshotPath(nodeId),
+		bytes
+	}))];
 	const index = {
 		manifest,
 		screenshots: images.map(({ nodeId, path }) => ({
 			nodeId,
 			path
+		})),
+		snapshots: snapshots.map(({ nodeId }) => ({
+			nodeId,
+			path: bundleSnapshotPath(nodeId)
 		}))
 	};
 	const attrs = {
@@ -1196,7 +1459,7 @@ function rawGraphBundleStream(manifest, screenshots) {
 		name: RAW_GRAPH_BUNDLE_INDEX,
 		...attrs
 	}, JSON.stringify(index)).on("error", onEntryError);
-	for (const { path, bytes } of images) tar.entry({
+	for (const { path, bytes } of files) tar.entry({
 		name: path,
 		...attrs
 	}, Buffer.from(bytes)).on("error", onEntryError);
@@ -1213,9 +1476,9 @@ function rawGraphBundleStream(manifest, screenshots) {
 	})());
 }
 /** The bundle `uploadRawGraph` streams, whole, for saving or inspecting it. */
-async function createRawGraphBundle(manifest, screenshots) {
+async function createRawGraphBundle(manifest, screenshots, snapshots = []) {
 	const chunks = [];
-	for await (const chunk of rawGraphBundleStream(manifest, screenshots)) chunks.push(chunk);
+	for await (const chunk of rawGraphBundleStream(manifest, screenshots, snapshots)) chunks.push(chunk);
 	return Buffer.concat(chunks);
 }
 function isLoopback(url) {
@@ -1290,7 +1553,7 @@ async function reserve(options, route, body) {
 * `prepareArtifactUpload` has to have reserved. Ralph processes it after this
 * returns; the result page shows when it is ready.
 */
-async function uploadRawGraph(manifest, screenshots, options) {
+async function uploadRawGraph(manifest, screenshots, options, snapshots = []) {
 	const url = checkedApiUrl(options, `/api/upload/web/apps/${options.appId}/artifact/${encodeURIComponent(manifest.artifactId)}`);
 	const storage = process.env["RALPH_UPLOAD_STORAGE"] || "gcs";
 	if (storage !== "gcs" && storage !== "local") throw new Error(`RALPH_UPLOAD_STORAGE must be gcs or local, not ${storage}.`);
@@ -1299,7 +1562,7 @@ async function uploadRawGraph(manifest, screenshots, options) {
 	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("uploadTimeoutMs in the Ralph reporter options must be a positive number of milliseconds.");
 	const receipt = await request(url, {
 		headers: { "content-type": "application/gzip" },
-		body: Readable.toWeb(rawGraphBundleStream(manifest, screenshots)),
+		body: Readable.toWeb(rawGraphBundleStream(manifest, screenshots, snapshots)),
 		duplex: "half"
 	}, options, timeoutMs);
 	if (receipt["result"] !== "ok" || receipt["status"] !== "queued" || receipt["artifactId"] !== manifest.artifactId || receipt["resultUrl"] !== void 0 && typeof receipt["resultUrl"] !== "string" || typeof receipt["replayed"] !== "boolean") throw unreadableReply(url);
@@ -1343,6 +1606,6 @@ async function responseDetail(response) {
 	return text.length > 200 ? text.slice(0, 200) + "…" : text || void 0;
 }
 //#endregion
-export { registerDeployment as a, uploadRawGraph as c, Recorder as d, version as f, resolveMode as h, prepareArtifactUpload as i, MANIFEST_ATTACHMENT as l, loadConfigSync as m, bundleImagePath as n, resolveUploadOptions as o, loadConfig as p, createRawGraphBundle as r, resultLink as s, RAW_GRAPH_BUNDLE_INDEX as t, REPORTER_ENV as u };
+export { prepareArtifactUpload as a, resultLink as c, REPORTER_ENV as d, Recorder as f, resolveMode as g, loadConfigSync as h, createRawGraphBundle as i, uploadRawGraph as l, loadConfig as m, bundleImagePath as n, registerDeployment as o, version as p, bundleSnapshotPath as r, resolveUploadOptions as s, RAW_GRAPH_BUNDLE_INDEX as t, MANIFEST_ATTACHMENT as u };
 
-//# sourceMappingURL=upload-BZs6Vqix.mjs.map
+//# sourceMappingURL=upload-BhHRgN8t.mjs.map