@ralphralphai/playwright 2.9.0 → 2.11.0

package/dist/{upload-DKeVoDQ2.mjs → upload-C_KLRH9y.mjs}

@@ -45,7 +45,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "2.9.0";
+var version = "2.11.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -664,7 +664,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;
@@ -879,8 +884,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)]));
@@ -925,7 +933,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) {
@@ -944,12 +952,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);
@@ -1204,6 +1216,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
@@ -1430,6 +1507,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;
@@ -1474,9 +1552,26 @@ var Recorder = class {
 		const key = Symbol();
 		state.declared.set(key, declaredConditions(declaration));
 		await this.recordConditionChange(state);
-		return async () => {
-			if (state.declared.delete(key)) await this.recordConditionChange(state);
-		};
+		return this.undoDeclaration(state, key);
+	}
+	async waitForNode(page, url, declaration = {}) {
+		await this.observe(page.context());
+		const state = this.pages.get(page);
+		if (!state) throw new Error("Cannot wait on a closed browser page.");
+		await page.waitForURL(url, { waitUntil: "commit" });
+		this.urlChanged(state);
+		const generation = state.generation;
+		const key = Symbol();
+		state.declared.set(key, declaredConditions(declaration));
+		await state.tail;
+		if (!this.paused && state.generation === generation && !this.retagVisitNode(state)) await this.recordConditionChange(state);
+		return this.undoDeclaration(state, key);
+	}
+	startFlow(name) {
+		return this.flows.start(name, this.lastRequestedNodeId);
+	}
+	endFlow(name) {
+		this.flows.end(name);
 	}
 	/**
 	* Stops requesting nodes, automatic or explicit, until `resume`. Recordings
@@ -1521,7 +1616,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.");
@@ -1565,11 +1660,42 @@ var Recorder = class {
 		state.generation++;
 		state.lastUrl = url;
 		state.declared.clear();
+		state.visitNodeId = void 0;
 		if (!this.paused && isHttpUrl(url)) this.enqueueCreateNodeRequest(state, "url-change").catch(() => void 0);
 	}
 	async recordConditionChange(state) {
 		if (!this.paused && isHttpUrl(state.page.url())) await this.enqueueCreateNodeRequest(state, "condition-change");
 	}
+	undoDeclaration(state, key) {
+		return async () => {
+			if (state.declared.delete(key)) await this.recordConditionChange(state);
+		};
+	}
+	/**
+	* Gives the URL's automatic capture the conditions declared since. They
+	* describe the visit from its start, and declarations change no app state,
+	* so the screenshot already taken stands for the declared node.
+	*/
+	retagVisitNode(state) {
+		const nodeId = state.visitNodeId;
+		if (!nodeId || state.lastRecorded?.nodeId !== nodeId) return false;
+		const index = this.nodes.findIndex((item) => item.nodeId === nodeId);
+		const visit = this.nodes[index];
+		if (visit?.status !== "recorded") return false;
+		const conditions = this.declaredConditions(state);
+		const mismatches = mismatchesOf(conditions, visit.reportedTags);
+		const { conditions: _conditions, tagMismatches: _tagMismatches, ...rest } = visit;
+		this.nodes[index] = {
+			...rest,
+			...withConditions(conditions),
+			...mismatches.length > 0 ? { tagMismatches: mismatches } : {}
+		};
+		state.lastRecorded = {
+			...state.lastRecorded,
+			node: nodeKey(conditions)
+		};
+		return true;
+	}
 	declaredConditions(state) {
 		return mergeConditions([...state.declared.values()]);
 	}
@@ -1594,6 +1720,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);
@@ -1626,7 +1753,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.");
@@ -1673,6 +1803,7 @@ var Recorder = class {
 					node,
 					nodeId: request.nodeId
 				};
+				if (request.trigger === "url-change" && state.generation === generation) state.visitNodeId = request.nodeId;
 			} else {
 				const { nodeId, sequence, requestedAt, name, edgeLabel } = this.nodes[retaken];
 				this.nodes[retaken] = {
@@ -1683,6 +1814,7 @@ var Recorder = class {
 					sequence,
 					requestedAt
 				};
+				this.flows.nodeReused(request.nodeId, nodeId);
 			}
 		} catch (error) {
 			this.nodes.push({
@@ -1762,7 +1894,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 {
@@ -1790,6 +1922,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)
 			}
 		};
@@ -2082,4 +2215,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-DKeVoDQ2.mjs.map
+//# sourceMappingURL=upload-C_KLRH9y.mjs.map