@ralphralphai/playwright 2.8.0 → 2.10.0

package/dist/{upload-KEwXpYxG.cjs → upload-D_OHCpvL.cjs}

@@ -40,8 +40,8 @@ let tar_stream = require("tar-stream");
 //#region src/config.ts
 function resolveMode(options) {
 	const mode = options.mode ?? process.env["RALPH_MODE"] ?? (process.env["RALPH_UPLOAD_KEY"] ? "upload" : "off");
-	if (mode === "off" || mode === "local" || mode === "upload") return mode;
-	throw new Error("RALPH_MODE must be off, local, or upload.");
+	if (mode === "off" || mode === "local" || mode === "upload" || mode === "deploy") return mode;
+	throw new Error("RALPH_MODE must be off, local, upload, or deploy.");
 }
 async function loadConfig(options, root) {
 	const file = configFile(options, root);
@@ -70,7 +70,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "2.8.0";
+var version = "2.10.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -689,7 +689,12 @@ async function captureAriaSnapshot(page, { viewport, scroll }, ignore = []) {
 	});
 	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 detached = [];
+	const normalized = (await Promise.all(visible.map((node) => readTree(page, node, ignoreSelector, facts, detached)))).filter((node) => node !== void 0);
+	if (detached.length > 0) {
+		const listed = detached.slice(0, 5).map(({ role, name }) => name ? `${role} "${name}"` : role).join(", ");
+		console.warn(`Ralph: ${detached.length} element(s) left ${page.url()} during capture and were dropped from its aria snapshot: ${listed}${detached.length > 5 ? ", ..." : ""}`);
+	}
 	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;
@@ -904,8 +909,11 @@ function fillMissingRefs(nodes) {
 	return nodes.map(fill);
 }
 async function readElement(page, ref, isImage, ignoreSelector) {
+	const locator = page.locator(`aria-ref=${ref}`);
+	const isDetached = async () => await locator.count().catch(() => 0) === 0;
 	try {
-		return await page.locator(`aria-ref=${ref}`).evaluate((element, { properties, isImage, dynamicAttribute, ignoreSelector }) => {
+		if (await isDetached()) return "detached";
+		return await locator.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)]));
@@ -950,7 +958,7 @@ async function readElement(page, ref, isImage, ignoreSelector) {
 			ignoreSelector
 		}, { timeout: ELEMENT_LOOKUP_TIMEOUT_MS });
 	} catch {
-		return;
+		return await isDetached() ? "detached" : void 0;
 	}
 }
 async function hashImage(page, image) {
@@ -969,12 +977,16 @@ function distinctStyle(style, inherited) {
 	});
 	return distinct.length === 0 ? void 0 : Object.fromEntries(distinct);
 }
-async function readTree(page, child, ignoreSelector, factsByRef) {
+async function readTree(page, child, ignoreSelector, factsByRef, detached) {
 	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 === "detached") {
+		detached.push(child);
+		return;
+	}
 	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);
+	const children = child.children === void 0 ? void 0 : (await Promise.all(child.children.map((grandchild) => readTree(page, grandchild, ignoreSelector, factsByRef, detached)))).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);
@@ -995,6 +1007,7 @@ async function describe(page, child, inherited, insideDynamic, factsByRef) {
 	return {
 		...child,
 		...style && { style },
+		...facts === void 0 && { unread: true },
 		...imageHash && { imageHash },
 		...dynamic && { dynamic },
 		...children && { children }
@@ -1228,6 +1241,71 @@ function nodeKey(conditions) {
 	return JSON.stringify([sorted(conditions.visitorTags), sorted(conditions.pageTags)]);
 }
 //#endregion
+//#region src/flows.ts
+const MAX_FLOW_NAME_LENGTH = 64;
+var FlowRuns = class {
+	runs = [];
+	retainedNodeIds = /* @__PURE__ */ new Map();
+	/** `currentNodeId` is the node on screen, the run's first step. */
+	start(name, currentNodeId) {
+		const flowName = flowNameOf(name);
+		if (this.openRun(flowName)) throw new Error(`Ralph flow "${flowName}" is already open.`);
+		const run = {
+			name: flowName,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			nodeIds: currentNodeId === void 0 ? [] : [currentNodeId]
+		};
+		this.runs.push(run);
+		return {
+			name: flowName,
+			end: () => {
+				if (run.ended) throw new Error(`This run of Ralph flow "${flowName}" has already ended.`);
+				endRun(run, "endFlow");
+			}
+		};
+	}
+	end(name) {
+		const flowName = flowNameOf(name);
+		const run = this.openRun(flowName);
+		if (!run) throw new Error(`Ralph flow "${flowName}" is not open.`);
+		endRun(run, "endFlow");
+	}
+	nodeRequested(nodeId) {
+		for (const run of this.runs) if (!run.ended) run.nodeIds.push(nodeId);
+	}
+	/** A retake or unchanged condition update kept an existing node's ID. */
+	nodeReused(requestId, retainedNodeId) {
+		this.retainedNodeIds.set(requestId, retainedNodeId);
+	}
+	/** Ends the runs still open, as the test has, and returns every run. */
+	finish() {
+		return this.runs.map((run) => {
+			if (!run.ended) endRun(run, "test-end");
+			return {
+				name: run.name,
+				startedAt: run.startedAt,
+				endedAt: run.ended.at,
+				endedBy: run.ended.by,
+				nodeIds: run.nodeIds.map((nodeId) => this.retainedNodeIds.get(nodeId) ?? nodeId)
+			};
+		});
+	}
+	openRun(name) {
+		return this.runs.find((run) => run.name === name && !run.ended);
+	}
+};
+function endRun(run, by) {
+	run.ended = {
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		by
+	};
+}
+function flowNameOf(name) {
+	const trimmed = name.trim();
+	if (!trimmed || trimmed.length > MAX_FLOW_NAME_LENGTH) throw new Error(`A Ralph flow name must be 1 to ${MAX_FLOW_NAME_LENGTH} characters.`);
+	return trimmed;
+}
+//#endregion
 //#region src/image.ts
 /**
 * Matches the crawler's full-page screenshots: lossless measured larger than this
@@ -1454,6 +1532,7 @@ var Recorder = class {
 	*/
 	order = 0;
 	requestOrder = /* @__PURE__ */ new Map();
+	flows = new FlowRuns();
 	actions = new ActionLog(() => ++this.order, () => !this.paused && !this.closed, (page) => this.pages.get(page)?.info.pageId, () => [...this.pages.values()].filter((state) => !state.page.isClosed()).map((state) => state.info.pageId));
 	constructor(options, config, testInfo, mode, playwright) {
 		this.options = options;
@@ -1502,6 +1581,12 @@ var Recorder = class {
 			if (state.declared.delete(key)) await this.recordConditionChange(state);
 		};
 	}
+	startFlow(name) {
+		return this.flows.start(name, this.lastRequestedNodeId);
+	}
+	endFlow(name) {
+		this.flows.end(name);
+	}
 	/**
 	* Stops requesting nodes, automatic or explicit, until `resume`. Recordings
 	* already requested still complete. The next node after `resume` links to
@@ -1545,7 +1630,7 @@ var Recorder = class {
 		linkPreviousNodes(nodes, (pageId) => this.pageInfo(pageId)?.openerPageId, (nodeId) => this.requestedAtMs.get(nodeId) ?? 0, (pageId) => this.pageState(pageId)?.pauseAnchor);
 		this.attachActions(nodes);
 		const failures = nodes.filter((item) => item.status === "uncaptured" && item.reason === "error");
-		await this.writeRawGraph(this.buildRawGraph(nodes, failures.length));
+		await this.writeRawGraph(this.buildRawGraph(nodes, this.flows.finish(), failures.length));
 		const mismatched = nodes.filter((item) => item.tagMismatches?.length);
 		if (this.options.strictNodeTags && mismatched.length && this.testInfo.status === "passed") throw new Error("Ralph: the app reported tags outside what the test declared, on " + mismatched.map((item) => item.url + " (" + item.tagMismatches.join(", ") + ")").join("; ") + ".");
 		if (failures.length && this.testInfo.status === "passed") throw new Error("Ralph could not record " + failures.length + " page state(s). See the ralph-raw-graph attachment.");
@@ -1618,6 +1703,7 @@ var Recorder = class {
 		this.requestedAtMs.set(request.nodeId, Date.now());
 		this.requestOrder.set(request.nodeId, ++this.order);
 		this.lastRequestedNodeId = request.nodeId;
+		this.flows.nodeRequested(request.nodeId);
 		const generation = state.generation;
 		const task = state.tail.then(() => this.createNode(state, generation, request));
 		state.tail = task.catch(() => void 0);
@@ -1650,7 +1736,10 @@ var Recorder = class {
 			const mismatches = mismatchesOf(conditions, reported);
 			const node = nodeKey(conditions);
 			const sameNode = state.lastRecorded?.url === request.url && state.lastRecorded.node === node;
-			if (sameNode && request.trigger !== "explicit") return;
+			if (sameNode && request.trigger !== "explicit") {
+				this.flows.nodeReused(request.nodeId, state.lastRecorded.nodeId);
+				return;
+			}
 			if (reported === void 0 && compactConditions(conditions) !== void 0 && !warnedNoTracker) {
 				warnedNoTracker = true;
 				console.warn("Ralph: this page runs no tracker, so the node conditions the test declares cannot be checked against the tags the app reports. Production events must carry the same tags, or these nodes will match no visitors.");
@@ -1707,6 +1796,7 @@ var Recorder = class {
 					sequence,
 					requestedAt
 				};
+				this.flows.nodeReused(request.nodeId, nodeId);
 			}
 		} catch (error) {
 			this.nodes.push({
@@ -1786,7 +1876,7 @@ var Recorder = class {
 	pageInfo(pageId) {
 		return this.pageState(pageId)?.info;
 	}
-	buildRawGraph(nodes, failureCount) {
+	buildRawGraph(nodes, flowRuns, failureCount) {
 		const { testInfo } = this;
 		const testPassed = testInfo.status === "passed";
 		return {
@@ -1814,6 +1904,7 @@ var Recorder = class {
 				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				pages: [...this.pages.values()].map((state) => state.info),
 				nodes,
+				...flowRuns.length ? { flowRuns } : {},
 				complete: testPassed && nodes.length > 0 && nodes.every((item) => item.status === "recorded" && item.geometryStable)
 			}
 		};
@@ -2213,4 +2304,4 @@ Object.defineProperty(exports, "visitAllLinks", {
 	}
 });
 
-//# sourceMappingURL=upload-KEwXpYxG.cjs.map
+//# sourceMappingURL=upload-D_OHCpvL.cjs.map