@ralphralphai/playwright 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -11,15 +11,15 @@ type RalphOptions = {
   runId?: string;
   buildId?: string;
   settleMs?: number;
-  captureTimeoutMs?: number;
+  recordTimeoutMs?: number;
   ready?: (page: Page, signal: AbortSignal) => Promise<void>;
 };
-type CaptureOptions = {
+type RecordNodeOptions = {
   state?: string;
   url?: string;
 };
 type Ralph = {
-  captureNode(page: Page, options?: CaptureOptions): Promise<void>;
+  recordNode(page: Page, options?: RecordNodeOptions): Promise<void>;
   flush(): Promise<void>;
   observe(context: BrowserContext): void;
 };
@@ -56,14 +56,14 @@ type RawNode = {
   trigger: 'url-change' | 'explicit';
   state?: string;
   /**
-   * The capture this page state was reached from: the previous one on the same
-   * page, or for a popup's first capture, its opener's latest. Superseded
-   * captures are skipped.
+   * The node this page state was reached from: the previous one on the same
+   * page, or for a popup's first node, its opener's latest. Superseded nodes
+   * are skipped.
    */
   previousNodeId?: string;
 } & ({
-  status: 'captured';
-  capturedAt: string;
+  status: 'recorded';
+  recordedAt: string;
   layout: PageLayout;
   geometryStable: boolean;
   screenshot: {
@@ -82,7 +82,7 @@ type ConfigSnapshot = {
   config: WebRalphConfig$1;
   packageVersion: string;
 };
-type CaptureManifest = {
+type RawGraphManifest = {
   formatVersion: 1;
   producer: {
     name: '@ralphralphai/playwright';
@@ -135,7 +135,7 @@ type UploadOptions = {
   uploadKey: string;
   timeoutMs?: number;
 };
-type CaptureScreenshot = {
+type RawGraphScreenshot = {
   nodeId: string;
   contentType: Screenshot['contentType'];
   bytes: Uint8Array;
@@ -144,10 +144,11 @@ type UploadReceipt = {
   result: 'ok';
   status: 'received';
   attemptId: string;
+  resultId: string;
   replayed: boolean;
 };
-type CaptureBundleIndex = {
-  manifest: CaptureManifest;
+type RawGraphBundleIndex = {
+  manifest: RawGraphManifest;
   screenshots: {
     nodeId: string;
     path: string;
@@ -156,14 +157,14 @@ type CaptureBundleIndex = {
 /**
  * Packs the manifest and screenshots into a gzipped tar archive:
  *
- *   capture.json               { manifest, screenshots: [{ nodeId, path }] }
+ *   raw_graph.json               { manifest, screenshots: [{ nodeId, path }] }
  *   assets/images/<id>.webp    raw screenshot bytes (.png when too large for WebP)
  */
-declare function createCaptureBundle(manifest: CaptureManifest, screenshots: readonly CaptureScreenshot[]): Promise<Uint8Array>;
-declare function uploadCapture(manifest: CaptureManifest, screenshots: readonly CaptureScreenshot[], options: UploadOptions): Promise<UploadReceipt>;
+declare function createRawGraphBundle(manifest: RawGraphManifest, screenshots: readonly RawGraphScreenshot[]): Promise<Uint8Array>;
+declare function uploadRawGraph(manifest: RawGraphManifest, screenshots: readonly RawGraphScreenshot[], options: UploadOptions): Promise<UploadReceipt>;
 //#endregion
 //#region src/recorder.d.ts
-declare const MANIFEST_ATTACHMENT = "ralph-captures";
+declare const MANIFEST_ATTACHMENT = "ralph-raw-graph";
 //#endregion
 //#region src/screens.d.ts
 type RalphProject = Project<PlaywrightTestOptions & {
@@ -187,5 +188,5 @@ type RalphFixtures = {
 };
 declare const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 //#endregion
-export { type CaptureBundleIndex, type CaptureManifest, type CaptureOptions, type CaptureScreenshot, type ConfigSnapshot, MANIFEST_ATTACHMENT, type PageLayout, type Ralph, RalphFixtures, type RalphOptions, type RalphProjectOptions, type RawNode, SCREEN_TAG_PREFIX, type TrackedElement, type UploadOptions, type UploadReceipt, type WebRalphConfig, createCaptureBundle, expect, mergeTests, ralphProjects, test, uploadCapture };
+export { type ConfigSnapshot, MANIFEST_ATTACHMENT, type PageLayout, type Ralph, RalphFixtures, type RalphOptions, type RalphProjectOptions, type RawGraphBundleIndex, type RawGraphManifest, type RawGraphScreenshot, type RawNode, type RecordNodeOptions, SCREEN_TAG_PREFIX, type TrackedElement, type UploadOptions, type UploadReceipt, type WebRalphConfig, createRawGraphBundle, expect, mergeTests, ralphProjects, test, uploadRawGraph };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -44,11 +44,11 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "0.1.0";
+var version = "0.2.0";
 //#endregion
 //#region src/image.ts
 /**
-* Matches the crawler's full-page captures: lossless measured larger than this
+* Matches the crawler's full-page screenshots: lossless measured larger than this
 * on real sites, which are mostly photographic content.
 */
 const WEBP_QUALITY = 80;
@@ -148,21 +148,21 @@ function resolveUploadOptions(options) {
 		timeoutMs: options.uploadTimeoutMs
 	};
 }
-const CAPTURE_BUNDLE_INDEX = "capture.json";
-const CAPTURE_BUNDLE_IMAGE_DIR = "assets/images";
+const RAW_GRAPH_BUNDLE_INDEX = "raw_graph.json";
+const RAW_GRAPH_BUNDLE_IMAGE_DIR = "assets/images";
 /**
 * Packs the manifest and screenshots into a gzipped tar archive:
 *
-*   capture.json               { manifest, screenshots: [{ nodeId, path }] }
+*   raw_graph.json               { manifest, screenshots: [{ nodeId, path }] }
 *   assets/images/<id>.webp    raw screenshot bytes (.png when too large for WebP)
 */
-async function createCaptureBundle(manifest, screenshots) {
-	if (Buffer.byteLength(JSON.stringify(manifest)) > 2097152 || screenshots.length > 500 || screenshots.reduce((total, screenshot) => total + screenshot.bytes.byteLength, 0) > 67108864) throw new Error("Ralph capture attempt exceeds upload limits.");
+async function createRawGraphBundle(manifest, screenshots) {
+	if (Buffer.byteLength(JSON.stringify(manifest)) > 2097152 || screenshots.length > 500 || screenshots.reduce((total, screenshot) => total + screenshot.bytes.byteLength, 0) > 67108864) throw new Error("Ralph raw graph exceeds upload limits.");
 	const images = screenshots.map(({ nodeId, contentType, bytes }) => {
 		if (!/^[A-Za-z0-9-]{1,64}$/.test(nodeId)) throw new Error(`Ralph node id is not path-safe: ${nodeId}`);
 		return {
 			nodeId,
-			path: `${CAPTURE_BUNDLE_IMAGE_DIR}/${nodeId}${imageExtension(contentType)}`,
+			path: `${RAW_GRAPH_BUNDLE_IMAGE_DIR}/${nodeId}${imageExtension(contentType)}`,
 			bytes
 		};
 	});
@@ -180,7 +180,7 @@ async function createCaptureBundle(manifest, screenshots) {
 	};
 	const tar = pack();
 	tar.entry({
-		name: CAPTURE_BUNDLE_INDEX,
+		name: RAW_GRAPH_BUNDLE_INDEX,
 		...attrs
 	}, JSON.stringify(index));
 	for (const { path, bytes } of images) tar.entry({
@@ -191,19 +191,19 @@ async function createCaptureBundle(manifest, screenshots) {
 	const chunks = [];
 	for await (const chunk of tar) chunks.push(chunk);
 	const compressed = await promisify(gzip)(Buffer.concat(chunks));
-	if (compressed.byteLength > 67108864) throw new Error("Ralph compressed capture bundle exceeds upload limits.");
+	if (compressed.byteLength > 67108864) throw new Error("Ralph compressed raw graph bundle exceeds upload limits.");
 	return compressed;
 }
 function isLoopback(url) {
 	return url.hostname === "localhost" || url.hostname === "[::1]" || /^127(\.\d{1,3}){3}$/.test(url.hostname);
 }
-async function uploadCapture(manifest, screenshots, options) {
+async function uploadRawGraph(manifest, screenshots, options) {
 	if (!/^[A-Za-z0-9_-]{1,64}$/.test(options.appId)) throw new Error(`Ralph app id is not valid: ${options.appId}`);
 	const url = new URL(`/api/upload/playwright/apps/${options.appId}/attempts`, options.apiUrl);
 	if (!(url.protocol === "https:" || url.protocol === "http:" && isLoopback(url)) || !options.uploadKey) throw new Error("Ralph upload requires an HTTPS API URL (HTTP only for loopback hosts) and an upload key.");
 	const timeoutMs = options.timeoutMs ?? 3e4;
 	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("Ralph uploadTimeoutMs must be positive and finite.");
-	const blob = new Blob([new Uint8Array(await createCaptureBundle(manifest, screenshots))], { type: "application/gzip" });
+	const blob = new Blob([new Uint8Array(await createRawGraphBundle(manifest, screenshots))], { type: "application/gzip" });
 	const response = await fetch(url, {
 		method: "POST",
 		headers: { Authorization: `Bearer ${options.uploadKey}` },
@@ -211,17 +211,17 @@ async function uploadCapture(manifest, screenshots, options) {
 		redirect: "error",
 		signal: AbortSignal.timeout(timeoutMs)
 	});
-	if (!response.ok) throw new Error(`Ralph upload failed (HTTP ${response.status}). Local capture artifacts are retained for retry.`);
+	if (!response.ok) throw new Error(`Ralph upload failed (HTTP ${response.status}). Local Ralph artifacts are retained for retry.`);
 	const receipt = await response.json();
-	if (receipt.result !== "ok" || receipt.status !== "received" || receipt.attemptId !== manifest.attemptId || typeof receipt.replayed !== "boolean") throw new Error("Ralph server returned an invalid upload receipt.");
+	if (receipt.result !== "ok" || receipt.status !== "received" || receipt.attemptId !== manifest.attemptId || typeof receipt.resultId !== "string" || typeof receipt.replayed !== "boolean") throw new Error("Ralph server returned an invalid upload receipt.");
 	return receipt;
 }
 //#endregion
 //#region src/recorder.ts
-const MANIFEST_ATTACHMENT = "ralph-captures";
+const MANIFEST_ATTACHMENT = "ralph-raw-graph";
 const DEFAULT_SETTLE_MS = 150;
-const DEFAULT_CAPTURE_TIMEOUT_MS = 5e3;
-/** Where captures are written, inside Playwright's per-test output directory. */
+const DEFAULT_RECORD_TIMEOUT_MS = 5e3;
+/** Where the raw graph and screenshots are written, inside Playwright's per-test output directory. */
 const OUTPUT_DIR = "ralph";
 var Recorder = class {
 	options;
@@ -234,13 +234,13 @@ var Recorder = class {
 	*/
 	attemptId = randomUUID();
 	startedAt = (/* @__PURE__ */ new Date()).toISOString();
-	/** How long to wait after a navigation's DOM loads before capturing. */
+	/** How long to wait after a navigation's DOM loads before recording. */
 	settleMs;
 	/**
-	* The budget for one capture, from settling through the screenshot. Past it,
-	* the capture is recorded as failed.
+	* The budget for recording one node, from settling through the screenshot.
+	* Past it, the node is recorded as failed.
 	*/
-	captureTimeoutMs;
+	recordTimeoutMs;
 	/**
 	* Every context being watched. `onPage` is kept so `stopContext` can remove
 	* the exact listener `observe` added. The id is stored in the manifest's
@@ -249,17 +249,17 @@ var Recorder = class {
 	contexts = /* @__PURE__ */ new Map();
 	/**
 	* Every tab seen in a watched context, including closed ones, so their
-	* captures and opener links still reach the manifest.
+	* nodes and opener links still reach the manifest.
 	*/
 	pages = /* @__PURE__ */ new Map();
 	/**
-	* Each capture's outcome, in completion order. Captures in one tab complete
+	* Each node's outcome, in completion order. Nodes in one tab complete
 	* in sequence, but tabs interleave; `finish` sorts them.
 	*/
 	nodes = [];
 	/**
-	* When each capture was requested, keyed by capture id, for linking a
-	* popup's first capture to its opener's latest. Numbers, so they compare
+	* When each node was requested, keyed by node id, for linking a
+	* popup's first node to its opener's latest. Numbers, so they compare
 	* without parsing each node's `requestedAt` string.
 	*/
 	requestedAtMs = /* @__PURE__ */ new Map();
@@ -271,10 +271,10 @@ var Recorder = class {
 		this.testInfo = testInfo;
 		this.upload = upload;
 		this.settleMs = options.settleMs ?? DEFAULT_SETTLE_MS;
-		this.captureTimeoutMs = options.captureTimeoutMs ?? DEFAULT_CAPTURE_TIMEOUT_MS;
-		if (!(Number.isFinite(this.settleMs) && this.settleMs >= 0 && Number.isFinite(this.captureTimeoutMs) && this.captureTimeoutMs > this.settleMs)) throw new Error("Ralph captureTimeoutMs must be finite and greater than settleMs, which must be non-negative.");
+		this.recordTimeoutMs = options.recordTimeoutMs ?? DEFAULT_RECORD_TIMEOUT_MS;
+		if (!(Number.isFinite(this.settleMs) && this.settleMs >= 0 && Number.isFinite(this.recordTimeoutMs) && this.recordTimeoutMs > this.settleMs)) throw new Error("Ralph recordTimeoutMs must be finite and greater than settleMs, which must be non-negative.");
 	}
-	/** Starts capturing URL changes in every current and future tab of `context`. */
+	/** Starts recording URL changes in every current and future tab of `context`. */
 	observe(context) {
 		if (this.closed) throw new Error("The Ralph recorder has finished.");
 		if (this.contexts.has(context)) return;
@@ -287,18 +287,18 @@ var Recorder = class {
 		context.on("page", onPage);
 		for (const page of context.pages()) onPage(page);
 	}
-	/** Captures the page as it is now, e.g. an open dialog at the same URL. */
-	async captureNode(page, options = {}) {
+	/** Records the page as it is now, e.g. an open dialog at the same URL. */
+	async recordNode(page, options = {}) {
 		this.observe(page.context());
 		const state = this.pages.get(page);
-		if (!state) throw new Error("Cannot capture a closed browser page.");
+		if (!state) throw new Error("Cannot record a closed browser page.");
 		await this.enqueue(state, "explicit", options);
 	}
-	/** Waits for every queued capture to finish. */
+	/** Waits for every queued recording to finish. */
 	async flush() {
 		await Promise.all([...this.pages.values()].map((state) => state.tail));
 	}
-	/** Stops watching `context` and waits for its queued captures. */
+	/** Stops watching `context` and waits for its queued recordings. */
 	async stopContext(context) {
 		const entry = this.contexts.get(context);
 		if (entry) context.off("page", entry.onPage);
@@ -308,7 +308,7 @@ var Recorder = class {
 	}
 	/**
 	* Stops recording, then writes the manifest, uploads it if configured, and
-	* fails a passing test whose captures failed.
+	* fails a passing test whose nodes failed to record.
 	*/
 	async finish() {
 		this.closed = true;
@@ -320,7 +320,7 @@ var Recorder = class {
 		const manifest = this.buildManifest(nodes, failures.length);
 		await this.writeManifest(manifest);
 		if (this.upload) await this.uploadManifest(manifest, this.upload);
-		if (failures.length && this.testInfo.status === "passed") throw new Error("Ralph could not capture " + failures.length + " page state(s). See the ralph-captures attachment.");
+		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.");
 	}
 	watchPage(page, contextId) {
 		if (this.pages.has(page)) return;
@@ -354,11 +354,11 @@ var Recorder = class {
 		state.lastUrl = url;
 		if (isHttpUrl(url)) this.enqueue(state, "url-change", {}).catch(() => void 0);
 	}
-	/** Queues a capture behind the tab's earlier ones. */
+	/** Queues a recording behind the tab's earlier ones. */
 	enqueue(state, trigger, options) {
 		const actualUrl = state.page.url();
 		const url = options.url === void 0 ? actualUrl : new URL(options.url, actualUrl).href;
-		if (!isHttpUrl(actualUrl) || !isHttpUrl(url)) throw new Error("Ralph captures require HTTP or HTTPS page and recorded URLs.");
+		if (!isHttpUrl(actualUrl) || !isHttpUrl(url)) throw new Error("Ralph recordings require HTTP or HTTPS page and recorded URLs.");
 		const request = {
 			nodeId: randomUUID(),
 			pageId: state.info.pageId,
@@ -376,18 +376,18 @@ var Recorder = class {
 		return task;
 	}
 	/**
-	* Takes one capture and records its outcome. Fails if the tab navigates or
-	* closes before it finishes, or if it runs past the capture timeout.
+	* Records one node and its outcome. Fails if the tab navigates or
+	* closes before it finishes, or if it runs past the record timeout.
 	*/
 	async record(state, generation, request) {
 		const { page } = state;
-		const deadline = startDeadline(this.captureTimeoutMs, "Ralph capture timed out.");
+		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();
-			if (navigatedAway()) throw new Error("The page navigated before its capture completed.");
-			if (page.isClosed()) throw new Error("The page closed before its capture completed.");
+			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.");
 		};
 		try {
 			check();
@@ -401,8 +401,8 @@ var Recorder = class {
 			check();
 			this.nodes.push({
 				...request,
-				status: "captured",
-				capturedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				status: "recorded",
+				recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				layout: before,
 				geometryStable: JSON.stringify(before) === JSON.stringify(after),
 				screenshot: await this.saveScreenshot(request.nodeId, image)
@@ -420,7 +420,7 @@ var Recorder = class {
 	}
 	/** After a navigation: the DOM, the settle delay, then the `ready` hook. */
 	async waitForPageToSettle(page, { wait, signal }, check) {
-		await wait(page.waitForLoadState("domcontentloaded", { timeout: this.captureTimeoutMs }));
+		await wait(page.waitForLoadState("domcontentloaded", { timeout: this.recordTimeoutMs }));
 		await wait(setTimeout$1(this.settleMs, void 0, { signal }));
 		check();
 		if (this.options.ready) await wait(this.options.ready(page, signal));
@@ -477,11 +477,11 @@ var Recorder = class {
 			config: this.config,
 			pages: [...this.pages.values()].map((state) => state.info),
 			nodes,
-			complete: testPassed && nodes.length > 0 && nodes.every((item) => item.status === "captured" && item.geometryStable)
+			complete: testPassed && nodes.length > 0 && nodes.every((item) => item.status === "recorded" && item.geometryStable)
 		};
 	}
 	async writeManifest(manifest) {
-		const file = this.testInfo.outputPath(OUTPUT_DIR, "captures.json");
+		const file = this.testInfo.outputPath(OUTPUT_DIR, "raw_graph.json");
 		await mkdir(this.testInfo.outputPath(OUTPUT_DIR), { recursive: true });
 		await writeFile(file, JSON.stringify(manifest, null, 2) + "\n");
 		await this.testInfo.attach(MANIFEST_ATTACHMENT, {
@@ -490,14 +490,14 @@ var Recorder = class {
 		});
 	}
 	async uploadManifest(manifest, upload) {
-		const captured = manifest.nodes.filter((item) => item.status === "captured");
+		const recorded = manifest.nodes.filter((item) => item.status === "recorded");
 		const screenshots = [];
-		for (const { nodeId, screenshot } of captured) screenshots.push({
+		for (const { nodeId, screenshot } of recorded) screenshots.push({
 			nodeId,
 			contentType: screenshot.contentType,
 			bytes: await readFile(this.testInfo.outputPath(screenshot.path))
 		});
-		const receipt = await uploadCapture(manifest, screenshots, upload);
+		const receipt = await uploadRawGraph(manifest, screenshots, upload);
 		await this.testInfo.attach("ralph-upload-receipt", {
 			body: JSON.stringify(receipt),
 			contentType: "application/json"
@@ -524,7 +524,7 @@ function startDeadline(timeoutMs, message) {
 }
 /**
 * Sets `previousNodeId` on each node: the one before it in the same
-* tab, or for a popup's first capture, its opener's latest. Superseded captures
+* tab, or for a popup's first node, its opener's latest. Superseded nodes
 * are skipped, since their page state was never shown.
 *
 * `nodes` must be sorted by page, then sequence.
@@ -641,7 +641,7 @@ const test = test$1.extend({
 			if (resolveMode(ralphOptions) !== "off") throw new Error("Opt this test into Ralph with the @ralph tag.");
 		};
 		await use(_ralphRecorder ?? {
-			captureNode: async () => {
+			recordNode: async () => {
 				checkOptIn();
 			},
 			flush: async () => {},
@@ -660,6 +660,6 @@ const test = test$1.extend({
 	}
 });
 //#endregion
-export { MANIFEST_ATTACHMENT, SCREEN_TAG_PREFIX, createCaptureBundle, expect, mergeTests, ralphProjects, test, uploadCapture };
+export { MANIFEST_ATTACHMENT, SCREEN_TAG_PREFIX, createRawGraphBundle, expect, mergeTests, ralphProjects, test, uploadRawGraph };
 
 //# sourceMappingURL=index.mjs.map