@ralphralphai/playwright 1.1.0 → 1.3.0

package/dist/reporter.mjs

@@ -1,4 +1,4 @@
-import { a as uploadRawGraph, f as resolveMode, i as resolveUploadOptions, l as version, n as bundleImagePath, o as MANIFEST_ATTACHMENT, s as REPORTER_ENV, t as RAW_GRAPH_BUNDLE_INDEX } from "./upload-giSVxpun.mjs";
+import { a as resolveUploadOptions, c as MANIFEST_ATTACHMENT, d as version, i as prepareArtifactUpload, l as REPORTER_ENV, m as resolveMode, n as bundleImagePath, o as resultLink, s as uploadRawGraph, t as RAW_GRAPH_BUNDLE_INDEX } from "./upload-Bd6rKvUx.mjs";
 import path from "node:path";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -14,7 +14,6 @@ import playwrightPackage from "@playwright/test/package.json" with { type: "json
 */
 var RalphReporter = class {
 	options;
-	artifactId = randomUUID();
 	startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	config;
 	/**
@@ -39,18 +38,35 @@ var RalphReporter = class {
 		try {
 			const collected = (await Promise.all(this.tests.values())).filter((item) => item !== void 0);
 			if (collected.length === 0) return;
-			const { manifest, images } = this.merge(collected);
-			const screenshots = await Promise.all(images.map(async ({ source, ...image }) => ({
+			const merged = this.merge(collected);
+			const screenshots = await Promise.all(merged.images.map(async ({ source, ...image }) => ({
 				...image,
 				bytes: typeof source === "string" ? await readFile(source) : source
 			})));
+			const uploading = resolveMode(this.options) === "upload" || collected.some(({ file }) => file.mode === "upload");
+			let prepared;
+			if (uploading) {
+				try {
+					prepared = await prepareArtifactUpload(resolveUploadOptions(this.options));
+				} catch (error) {
+					const outputDir = await this.write(merged.manifest, screenshots);
+					throw new Error(`${error instanceof Error ? error.message : String(error)} The recording was saved to ${outputDir}.`, { cause: error });
+				}
+				log(`Ralph: uploading the run. Follow the upload and processing at ${resultLink(prepared)}`);
+			}
+			const manifest = prepared === void 0 ? merged.manifest : {
+				...merged.manifest,
+				artifactId: prepared.artifactId
+			};
 			const nodeCount = manifest.rawGraphs.reduce((total, graph) => total + graph.nodes.length, 0);
 			const outputDir = await this.write(manifest, screenshots);
 			log(`Ralph: merged ${manifest.rawGraphs.length} test(s), ${nodeCount} node(s) into ${outputDir}`);
-			if (resolveMode(this.options) === "upload" || collected.some(({ file }) => file.mode === "upload")) {
-				const receipt = await uploadRawGraph(manifest, screenshots, resolveUploadOptions(this.options));
+			if (prepared !== void 0) {
+				const receipt = await uploadRawGraph(manifest, screenshots, resolveUploadOptions(this.options)).catch((error) => {
+					throw new Error(`${error instanceof Error ? error.message : String(error)} The recording was saved to ${outputDir}.`, { cause: error });
+				});
 				await writeFile(path.join(outputDir, "upload_receipt.json"), JSON.stringify(receipt, null, 2) + "\n");
-				log(`Ralph: uploaded the run's raw graph. ${receipt.resultUrl ?? "Result id: " + receipt.resultId}`);
+				log(`Ralph: uploaded the run. Ralph is processing it at ${resultLink(receipt)}`);
 			}
 			return;
 		} catch (error) {
@@ -106,7 +122,7 @@ var RalphReporter = class {
 				},
 				runId: first.file.runId,
 				buildId: first.file.buildId,
-				artifactId: this.artifactId,
+				artifactId: randomUUID(),
 				shard: this.config?.shard ?? null,
 				startedAt: this.startedAt,
 				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),

package/dist/reporter.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.mjs","names":["packageInfo.version"],"sources":["../src/reporter.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\n\nimport playwrightPackage from '@playwright/test/package.json' with { type: 'json' };\nimport type {\n  FullConfig,\n  FullResult,\n  Reporter,\n  TestCase,\n  TestResult,\n} from '@playwright/test/reporter';\n\nimport packageInfo from '../package.json';\nimport { resolveMode } from './config';\nimport { MANIFEST_ATTACHMENT, REPORTER_ENV } from './recorder';\nimport type { RawGraphManifest, RawGraph, RawGraphFile } from './types';\nimport {\n  RAW_GRAPH_BUNDLE_INDEX,\n  resolveUploadOptions,\n  bundleImagePath,\n  uploadRawGraph,\n  type RawGraphBundleIndex,\n  type RawGraphScreenshot,\n} from './upload';\n\nexport type RalphReporterOptions = {\n  /**\n   * `upload` uploads the merged raw graph. Defaults to `RALPH_MODE`, else\n   * `upload` when `RALPH_UPLOAD_KEY` is set. The run is also uploaded when any\n   * test ran in `upload` mode.\n   */\n  mode?: 'off' | 'local' | 'upload';\n  /** Your Ralph server. Defaults to `RALPH_API_URL`. */\n  apiUrl?: string;\n  /** The app the recordings belong to. Defaults to `RALPH_APP_ID`. */\n  appId?: string;\n  /** How long the upload may take, in milliseconds. Defaults to 120000. */\n  uploadTimeoutMs?: number;\n  /**\n   * Where the merged raw graph is written, laid out like the uploaded bundle.\n   * Defaults to `ralph` inside the first project's output directory.\n   */\n  outputDir?: string;\n};\n\n/** One test's final attempt, as the reporter collected it. */\ntype Collected = {\n  file: RawGraphFile;\n  status: TestResult['status'];\n  /** Screenshot attachment paths or preserved bodies, by attachment name. */\n  attachments: Map<string, string | Buffer>;\n};\n\n/**\n * Merges every recorded test's raw graph into one for the whole run, writes it\n * locally, and uploads it once when the mode is `upload`.\n *\n * Tests run in worker processes, so only a reporter, in the main process,\n * sees them all. For a sharded run, it runs in `playwright merge-reports` over\n * the shards' blob reports.\n */\nexport default class RalphReporter implements Reporter {\n  private readonly artifactId = randomUUID();\n  private readonly startedAt = new Date().toISOString();\n  private config?: FullConfig;\n\n  /**\n   * By test id, so a retry replaces the attempt before it. Read as each test\n   * ends, and awaited in `onEnd`.\n   */\n  private readonly tests = new Map<string, Promise<Collected | undefined>>();\n\n  constructor(private readonly options: RalphReporterOptions = {}) {\n    // Before any worker starts, so the fixtures can tell the reporter is on.\n    process.env[REPORTER_ENV] = '1';\n    if (resolveMode(options) === 'upload') {\n      // Throws, so missing credentials stop the run before any test.\n      resolveUploadOptions(options);\n    }\n  }\n\n  onBegin(config: FullConfig): void {\n    this.config = config;\n  }\n\n  onTestEnd(test: TestCase, result: TestResult): void {\n    const collected = collect(result);\n    // Rejections are reported in `onEnd`; this only stops Node from calling\n    // them unhandled in the meantime.\n    collected.catch(() => undefined);\n    this.tests.set(test.id, collected);\n  }\n\n  async onEnd(): Promise<{ status?: FullResult['status'] } | undefined> {\n    try {\n      const collected = (await Promise.all(this.tests.values())).filter(\n        (item) => item !== undefined,\n      );\n      if (collected.length === 0) {\n        return undefined;\n      }\n\n      const { manifest, images } = this.merge(collected);\n      const screenshots = await Promise.all(\n        images.map(\n          async ({ source, ...image }): Promise<RawGraphScreenshot> => ({\n            ...image,\n            bytes: typeof source === 'string' ? await readFile(source) : source,\n          }),\n        ),\n      );\n      const nodeCount = manifest.rawGraphs.reduce(\n        (total, graph) => total + graph.nodes.length,\n        0,\n      );\n      const outputDir = await this.write(manifest, screenshots);\n      log(\n        `Ralph: merged ${manifest.rawGraphs.length} test(s), ${nodeCount} node(s) into ${outputDir}`,\n      );\n\n      if (\n        resolveMode(this.options) === 'upload' ||\n        collected.some(({ file }) => file.mode === 'upload')\n      ) {\n        const receipt = await uploadRawGraph(\n          manifest,\n          screenshots,\n          resolveUploadOptions(this.options),\n        );\n        await writeFile(\n          path.join(outputDir, 'upload_receipt.json'),\n          JSON.stringify(receipt, null, 2) + '\\n',\n        );\n        log(\n          `Ralph: uploaded the run's raw graph. ${receipt.resultUrl ?? 'Result id: ' + receipt.resultId}`,\n        );\n      }\n      return undefined;\n    } catch (error) {\n      console.error(\n        'Ralph: ' + (error instanceof Error ? error.message : String(error)),\n      );\n      return { status: 'failed' };\n    }\n  }\n\n  printsToStdio(): boolean {\n    return false;\n  }\n\n  /** Merges the tests into one manifest, with where to read their screenshots. */\n  private merge(collected: Collected[]): {\n    manifest: RawGraphManifest;\n    images: (Omit<RawGraphScreenshot, 'bytes'> & { source: string | Buffer })[];\n  } {\n    const [first] = collected;\n    const same = (pick: (file: RawGraphFile) => unknown, what: string) => {\n      const expected = JSON.stringify(pick(first!.file));\n      if (\n        collected.some(({ file }) => JSON.stringify(pick(file)) !== expected)\n      ) {\n        throw new Error(\n          `Every recorded test in a run must share one ${what}; merge them per run.`,\n        );\n      }\n    };\n    same((file) => file.config, 'Ralph config');\n    same((file) => [file.runId, file.buildId], 'runId and buildId');\n\n    const images: (Omit<RawGraphScreenshot, 'bytes'> & {\n      source: string | Buffer;\n    })[] = [];\n    const rawGraphs = collected\n      .map(({ file, status, attachments }): RawGraph => {\n        const nodes = file.rawGraph.nodes.map((node) => {\n          if (node.status !== 'recorded') {\n            return node;\n          }\n          const source = attachments.get(node.screenshot.attachmentName);\n          if (source === undefined) {\n            throw new Error(\n              `The screenshot of node ${node.nodeId} is missing from the test results.`,\n            );\n          }\n          images.push({\n            nodeId: node.nodeId,\n            contentType: node.screenshot.contentType,\n            source,\n          });\n          return {\n            ...node,\n            screenshot: {\n              ...node.screenshot,\n              path: bundleImagePath(node.nodeId, node.screenshot.contentType),\n            },\n          };\n        });\n        return {\n          ...file.rawGraph,\n          // The final status, which includes failures after the recorder\n          // finished, such as a later fixture's teardown.\n          status,\n          nodes,\n          complete: file.rawGraph.complete && status === 'passed',\n        };\n      })\n      .sort(\n        (a, b) =>\n          a.project.localeCompare(b.project) ||\n          a.titlePath.join('\\0').localeCompare(b.titlePath.join('\\0')) ||\n          a.repeatEachIndex - b.repeatEachIndex,\n      );\n\n    const manifest: RawGraphManifest = {\n      formatVersion: 1,\n      producer: {\n        name: '@ralphralphai/playwright',\n        version: packageInfo.version,\n        playwrightVersion: playwrightPackage.version,\n      },\n      runId: first!.file.runId,\n      buildId: first!.file.buildId,\n      artifactId: this.artifactId,\n      shard: this.config?.shard ?? null,\n      startedAt: this.startedAt,\n      finishedAt: new Date().toISOString(),\n      config: first!.file.config,\n      rawGraphs,\n      complete: rawGraphs.every((graph) => graph.complete),\n    };\n\n    return {\n      manifest,\n      images,\n    };\n  }\n\n  /** Writes the manifest and screenshots in the bundle's layout. */\n  private async write(\n    manifest: RawGraphManifest,\n    screenshots: RawGraphScreenshot[],\n  ): Promise<string> {\n    const outputDir = path.resolve(\n      this.options.outputDir ??\n        path.join(\n          this.config?.projects[0]?.outputDir ??\n            path.join(this.config?.rootDir ?? process.cwd(), 'test-results'),\n          'ralph',\n        ),\n    );\n    await rm(outputDir, { recursive: true, force: true });\n\n    const index: RawGraphBundleIndex = { manifest, screenshots: [] };\n    for (const { nodeId, contentType, bytes } of screenshots) {\n      const imagePath = bundleImagePath(nodeId, contentType);\n      index.screenshots.push({ nodeId, path: imagePath });\n      await mkdir(path.dirname(path.join(outputDir, imagePath)), {\n        recursive: true,\n      });\n      await writeFile(path.join(outputDir, imagePath), bytes);\n    }\n    await mkdir(outputDir, { recursive: true });\n    await writeFile(\n      path.join(outputDir, RAW_GRAPH_BUNDLE_INDEX),\n      JSON.stringify(index, null, 2) + '\\n',\n    );\n    return outputDir;\n  }\n}\n\n/** Reads a test's raw graph from its attachments; undefined if it recorded nothing. */\nasync function collect(result: TestResult): Promise<Collected | undefined> {\n  const manifest = result.attachments.find(\n    (item) => item.name === MANIFEST_ATTACHMENT,\n  );\n  if (!manifest || (!manifest.body && !manifest.path)) {\n    return undefined;\n  }\n  const file = JSON.parse(\n    manifest.body?.toString('utf8') ?? (await readFile(manifest.path!, 'utf8')),\n  ) as RawGraphFile;\n  const attachments = new Map<string, string | Buffer>();\n  for (const { name, path: attachmentPath, body } of result.attachments) {\n    const source = body ?? attachmentPath;\n    if (source !== undefined) {\n      attachments.set(name, source);\n    }\n  }\n  return { file, status: result.status, attachments };\n}\n\nfunction log(message: string): void {\n  process.stdout.write(message + '\\n');\n}\n"],"mappings":"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"}
+{"version":3,"file":"reporter.mjs","names":["packageInfo.version"],"sources":["../src/reporter.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport { mkdir, readFile, rm, writeFile } from 'node:fs/promises';\nimport path from 'node:path';\n\nimport playwrightPackage from '@playwright/test/package.json' with { type: 'json' };\nimport type {\n  FullConfig,\n  FullResult,\n  Reporter,\n  TestCase,\n  TestResult,\n} from '@playwright/test/reporter';\n\nimport packageInfo from '../package.json';\nimport { resolveMode } from './config';\nimport { MANIFEST_ATTACHMENT, REPORTER_ENV } from './recorder';\nimport type { RawGraphManifest, RawGraph, RawGraphFile } from './types';\nimport {\n  RAW_GRAPH_BUNDLE_INDEX,\n  prepareArtifactUpload,\n  resolveUploadOptions,\n  resultLink,\n  bundleImagePath,\n  uploadRawGraph,\n  type PreparedUpload,\n  type RawGraphBundleIndex,\n  type RawGraphScreenshot,\n} from './upload';\n\nexport type RalphReporterOptions = {\n  /**\n   * `upload` uploads the merged raw graph. Defaults to `RALPH_MODE`, else\n   * `upload` when `RALPH_UPLOAD_KEY` is set. The run is also uploaded when any\n   * test ran in `upload` mode.\n   */\n  mode?: 'off' | 'local' | 'upload';\n  /** Your Ralph server. Defaults to `RALPH_API_URL`, else `https://api.ralphralph.ai`. */\n  apiUrl?: string;\n  /** The app the recordings belong to. Defaults to `RALPH_APP_ID`. */\n  appId?: string;\n  /** How long the upload may take, in milliseconds. Defaults to 120000. */\n  uploadTimeoutMs?: number;\n  /**\n   * Where the merged raw graph is written, laid out like the uploaded bundle.\n   * Defaults to `ralph` inside the first project's output directory.\n   */\n  outputDir?: string;\n};\n\n/** One test's final attempt, as the reporter collected it. */\ntype Collected = {\n  file: RawGraphFile;\n  status: TestResult['status'];\n  /** Screenshot attachment paths or preserved bodies, by attachment name. */\n  attachments: Map<string, string | Buffer>;\n};\n\n/**\n * Merges every recorded test's raw graph into one for the whole run, writes it\n * locally, and uploads it once when the mode is `upload`.\n *\n * Tests run in worker processes, so only a reporter, in the main process,\n * sees them all. For a sharded run, it runs in `playwright merge-reports` over\n * the shards' blob reports.\n */\nexport default class RalphReporter implements Reporter {\n  private readonly startedAt = new Date().toISOString();\n  private config?: FullConfig;\n\n  /**\n   * By test id, so a retry replaces the attempt before it. Read as each test\n   * ends, and awaited in `onEnd`.\n   */\n  private readonly tests = new Map<string, Promise<Collected | undefined>>();\n\n  constructor(private readonly options: RalphReporterOptions = {}) {\n    // Before any worker starts, so the fixtures can tell the reporter is on.\n    process.env[REPORTER_ENV] = '1';\n    if (resolveMode(options) === 'upload') {\n      // Throws, so missing credentials stop the run before any test.\n      resolveUploadOptions(options);\n    }\n  }\n\n  onBegin(config: FullConfig): void {\n    this.config = config;\n  }\n\n  onTestEnd(test: TestCase, result: TestResult): void {\n    const collected = collect(result);\n    // Rejections are reported in `onEnd`; this only stops Node from calling\n    // them unhandled in the meantime.\n    collected.catch(() => undefined);\n    this.tests.set(test.id, collected);\n  }\n\n  async onEnd(): Promise<{ status?: FullResult['status'] } | undefined> {\n    try {\n      const collected = (await Promise.all(this.tests.values())).filter(\n        (item) => item !== undefined,\n      );\n      if (collected.length === 0) {\n        return undefined;\n      }\n\n      const merged = this.merge(collected);\n      const screenshots = await Promise.all(\n        merged.images.map(\n          async ({ source, ...image }): Promise<RawGraphScreenshot> => ({\n            ...image,\n            bytes: typeof source === 'string' ? await readFile(source) : source,\n          }),\n        ),\n      );\n      const uploading =\n        resolveMode(this.options) === 'upload' ||\n        collected.some(({ file }) => file.mode === 'upload');\n\n      // Before the local copy is written, so it names the same artifact as the\n      // upload, and the link is printed as soon as it works.\n      let prepared: PreparedUpload | undefined;\n      if (uploading) {\n        try {\n          prepared = await prepareArtifactUpload(\n            resolveUploadOptions(this.options),\n          );\n        } catch (error) {\n          const outputDir = await this.write(merged.manifest, screenshots);\n          throw new Error(\n            `${error instanceof Error ? error.message : String(error)} The recording was saved to ${outputDir}.`,\n            { cause: error },\n          );\n        }\n        log(\n          `Ralph: uploading the run. Follow the upload and processing at ${resultLink(prepared)}`,\n        );\n      }\n      const manifest =\n        prepared === undefined\n          ? merged.manifest\n          : { ...merged.manifest, artifactId: prepared.artifactId };\n      const nodeCount = manifest.rawGraphs.reduce(\n        (total, graph) => total + graph.nodes.length,\n        0,\n      );\n      const outputDir = await this.write(manifest, screenshots);\n      log(\n        `Ralph: merged ${manifest.rawGraphs.length} test(s), ${nodeCount} node(s) into ${outputDir}`,\n      );\n\n      if (prepared !== undefined) {\n        const receipt = await uploadRawGraph(\n          manifest,\n          screenshots,\n          resolveUploadOptions(this.options),\n        ).catch((error: unknown) => {\n          throw new Error(\n            `${error instanceof Error ? error.message : String(error)} The recording was saved to ${outputDir}.`,\n            { cause: error },\n          );\n        });\n        await writeFile(\n          path.join(outputDir, 'upload_receipt.json'),\n          JSON.stringify(receipt, null, 2) + '\\n',\n        );\n        log(\n          `Ralph: uploaded the run. Ralph is processing it at ${resultLink(receipt)}`,\n        );\n      }\n      return undefined;\n    } catch (error) {\n      console.error(\n        'Ralph: ' + (error instanceof Error ? error.message : String(error)),\n      );\n      return { status: 'failed' };\n    }\n  }\n\n  printsToStdio(): boolean {\n    return false;\n  }\n\n  /** Merges the tests into one manifest, with where to read their screenshots. */\n  private merge(collected: Collected[]): {\n    manifest: RawGraphManifest;\n    images: (Omit<RawGraphScreenshot, 'bytes'> & { source: string | Buffer })[];\n  } {\n    const [first] = collected;\n    const same = (pick: (file: RawGraphFile) => unknown, what: string) => {\n      const expected = JSON.stringify(pick(first!.file));\n      if (\n        collected.some(({ file }) => JSON.stringify(pick(file)) !== expected)\n      ) {\n        throw new Error(\n          `Every recorded test in a run must share one ${what}; merge them per run.`,\n        );\n      }\n    };\n    same((file) => file.config, 'Ralph config');\n    same((file) => [file.runId, file.buildId], 'runId and buildId');\n\n    const images: (Omit<RawGraphScreenshot, 'bytes'> & {\n      source: string | Buffer;\n    })[] = [];\n    const rawGraphs = collected\n      .map(({ file, status, attachments }): RawGraph => {\n        const nodes = file.rawGraph.nodes.map((node) => {\n          if (node.status !== 'recorded') {\n            return node;\n          }\n          const source = attachments.get(node.screenshot.attachmentName);\n          if (source === undefined) {\n            throw new Error(\n              `The screenshot of node ${node.nodeId} is missing from the test results.`,\n            );\n          }\n          images.push({\n            nodeId: node.nodeId,\n            contentType: node.screenshot.contentType,\n            source,\n          });\n          return {\n            ...node,\n            screenshot: {\n              ...node.screenshot,\n              path: bundleImagePath(node.nodeId, node.screenshot.contentType),\n            },\n          };\n        });\n        return {\n          ...file.rawGraph,\n          // The final status, which includes failures after the recorder\n          // finished, such as a later fixture's teardown.\n          status,\n          nodes,\n          complete: file.rawGraph.complete && status === 'passed',\n        };\n      })\n      .sort(\n        (a, b) =>\n          a.project.localeCompare(b.project) ||\n          a.titlePath.join('\\0').localeCompare(b.titlePath.join('\\0')) ||\n          a.repeatEachIndex - b.repeatEachIndex,\n      );\n\n    const manifest: RawGraphManifest = {\n      formatVersion: 1,\n      producer: {\n        name: '@ralphralphai/playwright',\n        version: packageInfo.version,\n        playwrightVersion: playwrightPackage.version,\n      },\n      runId: first!.file.runId,\n      buildId: first!.file.buildId,\n      // Replaced by the prepared artifact's id when the run is uploaded.\n      artifactId: randomUUID(),\n      shard: this.config?.shard ?? null,\n      startedAt: this.startedAt,\n      finishedAt: new Date().toISOString(),\n      config: first!.file.config,\n      rawGraphs,\n      complete: rawGraphs.every((graph) => graph.complete),\n    };\n\n    return {\n      manifest,\n      images,\n    };\n  }\n\n  /** Writes the manifest and screenshots in the bundle's layout. */\n  private async write(\n    manifest: RawGraphManifest,\n    screenshots: RawGraphScreenshot[],\n  ): Promise<string> {\n    const outputDir = path.resolve(\n      this.options.outputDir ??\n        path.join(\n          this.config?.projects[0]?.outputDir ??\n            path.join(this.config?.rootDir ?? process.cwd(), 'test-results'),\n          'ralph',\n        ),\n    );\n    await rm(outputDir, { recursive: true, force: true });\n\n    const index: RawGraphBundleIndex = { manifest, screenshots: [] };\n    for (const { nodeId, contentType, bytes } of screenshots) {\n      const imagePath = bundleImagePath(nodeId, contentType);\n      index.screenshots.push({ nodeId, path: imagePath });\n      await mkdir(path.dirname(path.join(outputDir, imagePath)), {\n        recursive: true,\n      });\n      await writeFile(path.join(outputDir, imagePath), bytes);\n    }\n    await mkdir(outputDir, { recursive: true });\n    await writeFile(\n      path.join(outputDir, RAW_GRAPH_BUNDLE_INDEX),\n      JSON.stringify(index, null, 2) + '\\n',\n    );\n    return outputDir;\n  }\n}\n\n/** Reads a test's raw graph from its attachments; undefined if it recorded nothing. */\nasync function collect(result: TestResult): Promise<Collected | undefined> {\n  const manifest = result.attachments.find(\n    (item) => item.name === MANIFEST_ATTACHMENT,\n  );\n  if (!manifest || (!manifest.body && !manifest.path)) {\n    return undefined;\n  }\n  const file = JSON.parse(\n    manifest.body?.toString('utf8') ?? (await readFile(manifest.path!, 'utf8')),\n  ) as RawGraphFile;\n  const attachments = new Map<string, string | Buffer>();\n  for (const { name, path: attachmentPath, body } of result.attachments) {\n    const source = body ?? attachmentPath;\n    if (source !== undefined) {\n      attachments.set(name, source);\n    }\n  }\n  return { file, status: result.status, attachments };\n}\n\nfunction log(message: string): void {\n  process.stdout.write(message + '\\n');\n}\n"],"mappings":"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"}

package/dist/{upload-giSVxpun.mjs → upload-Bd6rKvUx.mjs}

@@ -8,8 +8,9 @@ import { parse, printParseErrorCode } from "jsonc-parser";
 import { randomUUID } from "node:crypto";
 import { setTimeout as setTimeout$1 } from "node:timers/promises";
 import playwrightPackage from "@playwright/test/package.json" with { type: "json" };
-import { promisify } from "node:util";
-import { gzip } from "node:zlib";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { createGzip } from "node:zlib";
 import { pack } from "tar-stream";
 //#region src/config.ts
 function resolveMode(options) {
@@ -44,7 +45,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "1.1.0";
+var version = "1.3.0";
 //#endregion
 //#region src/animations.ts
 /**
@@ -66,6 +67,57 @@ async function waitForAnimations(page, timeoutMs) {
 	}
 }
 //#endregion
+//#region src/conditions.ts
+const declared = (declaration = {}) => {
+	const conditions = {};
+	for (const [key, value] of Object.entries(declaration)) {
+		if (value === void 0) continue;
+		conditions[key] = [...new Set((Array.isArray(value) ? value : [value]).map((item) => item ?? null))];
+	}
+	return conditions;
+};
+/** A declaration as sets: a scalar is a one-element set, `undefined` is `null`. */
+function declaredConditions(declaration) {
+	return {
+		visitorTags: declared(declaration.visitorTags),
+		pageTags: declared(declaration.pageTags)
+	};
+}
+/** Later declarations win per key, as later `tagPage` calls do in the app. */
+function mergeConditions(layers) {
+	return {
+		visitorTags: Object.assign({}, ...layers.map((layer) => layer.visitorTags)),
+		pageTags: Object.assign({}, ...layers.map((layer) => layer.pageTags))
+	};
+}
+/**
+* Declared keys the app's tracker disagrees with, as `visitorTags.plan`. A
+* node's conditions come from the test alone, so this is the only check that
+* production events will carry the tags its conditions name: a key the app
+* never sets, or sets under another name, leaves the node without traffic.
+*/
+function mismatchesOf(declared, reported) {
+	if (reported === void 0) return [];
+	const mismatches = [];
+	for (const kind of ["visitorTags", "pageTags"]) for (const [key, allowed] of Object.entries(declared[kind] ?? {})) if (!allowed.includes(reported[kind][key] ?? null)) mismatches.push(`${kind}.${key}`);
+	return mismatches.sort();
+}
+/** Absent kinds are left out, so an unconditional node has no conditions. */
+function compactConditions(conditions) {
+	const compact = {};
+	for (const kind of ["visitorTags", "pageTags"]) if (Object.keys(conditions[kind] ?? {}).length > 0) compact[kind] = conditions[kind];
+	return Object.keys(compact).length === 0 ? void 0 : compact;
+}
+/**
+* The node a state belongs to, as a string, whatever the order of keys or
+* values. Equal keys are one node, so a tag change that leaves this alone
+* records nothing.
+*/
+function nodeKey(conditions) {
+	const sorted = (tags = {}) => Object.entries(tags).map(([key, values]) => [key, values.map((value) => JSON.stringify(value)).sort()]).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+	return JSON.stringify([sorted(conditions.visitorTags), sorted(conditions.pageTags)]);
+}
+//#endregion
 //#region src/image.ts
 /**
 * Matches the crawler's full-page screenshots: lossless measured larger than this
@@ -166,6 +218,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-";
+/** Once per worker: a run without the tracker says so once, not per node. */
+let warnedNoTracker = false;
 const DEFAULT_SETTLE_MS = 150;
 const DEFAULT_RECORD_TIMEOUT_MS = 5e3;
 /** Where the raw graph and screenshots are written, inside Playwright's per-test output directory. */
@@ -236,6 +290,17 @@ var Recorder = class {
 		if (this.paused) return;
 		await this.enqueueCreateNodeRequest(state, "explicit", options);
 	}
+	async setNodeConditions(page, declaration) {
+		this.observe(page.context());
+		const state = this.pages.get(page);
+		if (!state) throw new Error("Cannot tag a closed browser page.");
+		const key = Symbol();
+		state.declared.set(key, declaredConditions(declaration));
+		await this.recordConditionChange(state);
+		return async () => {
+			if (state.declared.delete(key)) await this.recordConditionChange(state);
+		};
+	}
 	/**
 	* Stops requesting nodes, automatic or explicit, until `resume`. Recordings
 	* already requested still complete. The next node after `resume` links to
@@ -272,6 +337,8 @@ var Recorder = class {
 		linkPreviousNodes(nodes, (pageId) => this.pageInfo(pageId)?.openerPageId, (nodeId) => this.requestedAtMs.get(nodeId) ?? 0, (pageId) => this.pageState(pageId)?.pauseAnchor);
 		const failures = nodes.filter((item) => item.status === "uncaptured" && item.reason === "error");
 		await this.writeRawGraph(this.buildRawGraph(nodes, 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.");
 	}
 	watchPage(page) {
@@ -285,6 +352,7 @@ var Recorder = class {
 			lastUrl: "",
 			generation: 0,
 			sequence: 0,
+			declared: /* @__PURE__ */ new Map(),
 			tail: Promise.resolve(),
 			opener: Promise.resolve(),
 			onNavigation: (frame) => {
@@ -308,8 +376,18 @@ var Recorder = class {
 		if (url === state.lastUrl) return;
 		state.generation++;
 		state.lastUrl = url;
+		state.declared.clear();
 		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", {});
+	}
+	declaredConditions(state) {
+		return mergeConditions([...state.declared.values()]);
+	}
+	async reportedTags(page) {
+		return page.evaluate(() => window.__ralphTags?.()).catch(() => void 0);
+	}
 	/** Queues a recording behind the tab's earlier ones. */
 	enqueueCreateNodeRequest(state, trigger, options) {
 		const actualUrl = state.page.url();
@@ -348,7 +426,17 @@ var Recorder = class {
 		};
 		try {
 			check();
-			if (request.trigger === "url-change") await this.waitForPageToSettle(page, deadline, check);
+			if (request.trigger !== "explicit") await this.waitForPageToSettle(page, deadline, check);
+			check();
+			const conditions = this.declaredConditions(state);
+			const reported = await wait(this.reportedTags(page));
+			const mismatches = mismatchesOf(conditions, reported);
+			const node = nodeKey(conditions);
+			if (request.trigger === "condition-change" && state.lastRecorded?.url === request.url && state.lastRecorded.node === node) 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.");
+			}
 			if (this.options.reduceMotion) {
 				check();
 				await wait(waitForAnimations(page, (deadline.endsAt - Date.now()) / 2));
@@ -362,20 +450,28 @@ var Recorder = class {
 			check();
 			this.nodes.push({
 				...request,
+				...withConditions(conditions),
+				...reported === void 0 ? {} : { reportedTags: reported },
+				...mismatches.length > 0 ? { tagMismatches: mismatches } : {},
 				status: "recorded",
 				recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				layout: before,
 				geometryStable: JSON.stringify(before) === JSON.stringify(after),
 				screenshot: await this.saveScreenshot(request.nodeId, image)
 			});
+			state.lastRecorded = {
+				url: request.url,
+				node
+			};
 		} catch (error) {
 			this.nodes.push({
 				...request,
+				...withConditions(this.declaredConditions(state)),
 				status: "uncaptured",
 				reason: navigatedAway() ? "navigated-away" : "error",
 				message: error instanceof Error ? error.message : String(error)
 			});
-			if (request.trigger === "explicit") throw error;
+			if (request.trigger !== "url-change") throw error;
 		} finally {
 			deadline.cancel();
 		}
@@ -455,6 +551,10 @@ var Recorder = class {
 		});
 	}
 };
+function withConditions(conditions) {
+	const compact = compactConditions(conditions);
+	return compact === void 0 ? {} : { conditions: compact };
+}
 function isHttpUrl(url) {
 	return /^https?:/.test(url);
 }
@@ -498,14 +598,17 @@ function linkPreviousNodes(nodes, openerOf, requestedAtMs, pauseAnchorOf) {
 		if (from) item.previousNodeId = from.nodeId;
 	});
 }
-//#endregion
-//#region src/upload.ts
-/** Where the reporter uploads: its options, else the environment. */
+/** Where the uploaded run opens: the server's link, else the Ralph dashboard. */
+function resultLink({ artifactId, resultUrl }) {
+	return resultUrl ?? `https://dash.ralphralph.ai/uploads/${encodeURIComponent(artifactId)}`;
+}
+/** Where the reporter uploads: its options, else the environment, else Ralph's production server. */
 function resolveUploadOptions(options) {
 	const uploadKey = process.env["RALPH_UPLOAD_KEY"];
-	const apiUrl = options.apiUrl ?? process.env["RALPH_API_URL"];
+	const apiUrl = options.apiUrl || process.env["RALPH_API_URL"] || "https://api.ralphralph.ai";
 	const appId = options.appId ?? process.env["RALPH_APP_ID"];
-	if (!uploadKey || !apiUrl || !appId) throw new Error("Ralph upload requires RALPH_UPLOAD_KEY, RALPH_API_URL (or the reporter option apiUrl), and RALPH_APP_ID (or appId).");
+	if (!uploadKey) throw new Error(`To upload to Ralph, set RALPH_UPLOAD_KEY. ${CREATE_KEY_HINT}`);
+	if (!appId) throw new Error("To upload to Ralph, set RALPH_APP_ID (or the reporter option appId) to the app the recordings belong to.");
 	return {
 		uploadKey,
 		apiUrl,
@@ -520,14 +623,23 @@ 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)}`;
 }
+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() {
+		super(TOO_BIG);
+	}
+};
 /**
-* Packs the manifest and screenshots into a gzipped tar archive:
+* 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 }] }
 *   assets/images/<id>.webp    raw screenshot bytes (.png when too large for WebP)
+*
+* Fails with a `TooBigError` once the compressed bytes pass the limit.
 */
-async function createRawGraphBundle(manifest, screenshots) {
-	if (Buffer.byteLength(JSON.stringify(manifest)) > 16777216 || screenshots.length > 5e3 || screenshots.reduce((total, screenshot) => total + screenshot.bytes.byteLength, 0) > 268435456) throw new Error("Ralph raw graph exceeds upload limits.");
+function rawGraphBundleStream(manifest, screenshots) {
+	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),
@@ -546,47 +658,144 @@ async function createRawGraphBundle(manifest, screenshots) {
 		gid: 0
 	};
 	const tar = pack();
+	const onEntryError = (error) => tar.destroy(error);
 	tar.entry({
 		name: RAW_GRAPH_BUNDLE_INDEX,
 		...attrs
-	}, JSON.stringify(index));
+	}, JSON.stringify(index)).on("error", onEntryError);
 	for (const { path, bytes } of images) tar.entry({
 		name: path,
 		...attrs
-	}, Buffer.from(bytes));
+	}, Buffer.from(bytes)).on("error", onEntryError);
 	tar.finalize();
+	const gzip = createGzip();
+	pipeline(tar, gzip).catch((error) => gzip.destroy(error));
+	return Readable.from((async function* () {
+		let size = 0;
+		for await (const chunk of gzip) {
+			size += chunk.byteLength;
+			if (size > 268435456) throw new TooBigError();
+			yield chunk;
+		}
+	})());
+}
+/** The bundle `uploadRawGraph` streams, whole, for saving or inspecting it. */
+async function createRawGraphBundle(manifest, screenshots) {
 	const chunks = [];
-	for await (const chunk of tar) chunks.push(chunk);
-	const compressed = await promisify(gzip)(Buffer.concat(chunks));
-	if (compressed.byteLength > 268435456) throw new Error("Ralph compressed raw graph bundle exceeds upload limits.");
-	return compressed;
+	for await (const chunk of rawGraphBundleStream(manifest, screenshots)) chunks.push(chunk);
+	return Buffer.concat(chunks);
 }
 function isLoopback(url) {
 	return url.hostname === "localhost" || url.hostname === "[::1]" || /^127(\.\d{1,3}){3}$/.test(url.hostname);
 }
+function checkedApiUrl(options, path) {
+	if (!/^[A-Za-z0-9_-]{1,64}$/.test(options.appId)) throw new Error(`"${options.appId}" isn't a valid Ralph app id. Check RALPH_APP_ID.`);
+	const url = new URL(path, options.apiUrl);
+	if (!(url.protocol === "https:" || url.protocol === "http:" && isLoopback(url))) throw new Error(`RALPH_API_URL must start with https:// (http:// only works for localhost), not ${options.apiUrl}.`);
+	if (!options.uploadKey) throw new Error(`To upload to Ralph, set RALPH_UPLOAD_KEY. ${CREATE_KEY_HINT}`);
+	return url;
+}
+/** Sends one request, turning every way it can fail into a message that says what to fix. */
+async function request(url, init, options, timeoutMs) {
+	let response;
+	try {
+		response = await fetch(url, {
+			...init,
+			method: "POST",
+			headers: {
+				...init.headers,
+				Authorization: `Bearer ${options.uploadKey}`
+			},
+			redirect: "error",
+			signal: AbortSignal.timeout(timeoutMs)
+		});
+	} catch (error) {
+		if (error instanceof TooBigError || error instanceof Error && error.cause instanceof TooBigError) throw new Error(TOO_BIG, { cause: error });
+		throw new Error(describeRequestFailure(error, url, timeoutMs), { cause: error });
+	}
+	if (!response.ok) throw new Error(describeHttpFailure(response.status, await responseDetail(response), url, options.appId));
+	try {
+		return await response.json();
+	} catch {
+		return {};
+	}
+}
+const unreadableReply = (url) => /* @__PURE__ */ new Error("Upload to Ralph failed. Ralph's reply couldn't be read. Update @ralphralphai/playwright to the latest version and run again." + customServerHint(url));
+const PREPARE_TIMEOUT_MS = 3e4;
+/**
+* Reserves an artifact for the run. Its `resultUrl` works from now on, so the
+* run can be followed while it uploads and while Ralph processes it.
+*/
+async function prepareArtifactUpload(options) {
+	const url = checkedApiUrl(options, "/api/upload/artifact/prepare");
+	const reply = await request(url, {
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ externalAppId: options.appId })
+	}, options, PREPARE_TIMEOUT_MS);
+	if (reply["result"] !== "ok" || typeof reply["artifactId"] !== "string" || reply["resultUrl"] !== void 0 && typeof reply["resultUrl"] !== "string") throw unreadableReply(url);
+	return {
+		artifactId: reply["artifactId"],
+		resultUrl: reply["resultUrl"]
+	};
+}
+/**
+* Streams the run's bundle to the artifact `manifest.artifactId` names, which
+* `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) {
-	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}/artifact`, options.apiUrl);
+	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}.`);
 	if (storage === "local") url.searchParams.set("storage", "local");
-	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 ?? 12e4;
-	if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("Ralph uploadTimeoutMs must be positive and finite.");
-	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}` },
-		body: blob,
-		redirect: "error",
-		signal: AbortSignal.timeout(timeoutMs)
-	});
-	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.artifactId !== manifest.artifactId || typeof receipt.resultId !== "string" || receipt.resultUrl !== void 0 && typeof receipt.resultUrl !== "string" || typeof receipt.replayed !== "boolean") throw new Error("Ralph server returned an invalid upload receipt.");
+	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)),
+		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);
 	return receipt;
 }
+const CREATE_KEY_HINT = "You can create an upload key in your project dashboard on Ralph.";
+const SUPPORT_HINT = "If it keeps failing, contact Ralph support.";
+/** Only users who set their own server need to hear about it. */
+function customServerHint(url) {
+	return url.origin === new URL("https://api.ralphralph.ai").origin ? "" : ` Also check RALPH_API_URL (${url.origin}) is right.`;
+}
+function describeRequestFailure(error, url, timeoutMs) {
+	if (error instanceof Error && error.name === "TimeoutError") return `Upload to Ralph took longer than ${timeoutMs / 1e3}s and was stopped. Check your network, or raise uploadTimeoutMs in the reporter options.`;
+	return `Couldn't connect to Ralph (${error instanceof Error && error.cause instanceof Error ? error.cause.message : error instanceof Error ? error.message : String(error)}). Check that this machine can reach ${url.origin}.` + customServerHint(url);
+}
+function describeHttpFailure(status, detail, url, appId) {
+	let message;
+	if (status === 401) message = `Ralph didn't accept your upload key. Check RALPH_UPLOAD_KEY. ${CREATE_KEY_HINT}`;
+	else if (status === 403) message = `Your upload key can't upload to the app "${appId}". Check RALPH_APP_ID is an app in the same project as the key.`;
+	else if (status === 404) message = `Ralph couldn't find the app "${appId}". Check RALPH_APP_ID.` + customServerHint(url);
+	else if (status === 413) message = "This run is too big to upload. Record fewer pages or screen sizes, or split the tests across runs.";
+	else if (status === 429) message = "Too many uploads right now. Wait a minute and run again.";
+	else if (status >= 500) message = `Something went wrong on Ralph's side. Run again later. ${SUPPORT_HINT}`;
+	else message = `Ralph couldn't accept this upload. Update @ralphralphai/playwright to the latest version and run again. ${SUPPORT_HINT}`;
+	return `Upload to Ralph failed. ${message} (HTTP ${status}${detail ? `: ${detail}` : ""})`;
+}
+/** The server's reason for rejecting the upload, kept short. */
+async function responseDetail(response) {
+	let text;
+	try {
+		text = (await response.text()).trim();
+	} catch {
+		return;
+	}
+	try {
+		const body = JSON.parse(text);
+		const message = body.result ?? body.message ?? body.error;
+		if (typeof message === "string") text = message;
+	} catch {}
+	text = text.replace(/\s+/g, " ");
+	return text.length > 200 ? text.slice(0, 200) + "…" : text || void 0;
+}
 //#endregion
-export { uploadRawGraph as a, Recorder as c, loadConfigSync as d, resolveMode as f, resolveUploadOptions as i, version as l, bundleImagePath as n, MANIFEST_ATTACHMENT as o, createRawGraphBundle as r, REPORTER_ENV as s, RAW_GRAPH_BUNDLE_INDEX as t, loadConfig as u };
+export { resolveUploadOptions as a, MANIFEST_ATTACHMENT as c, version as d, loadConfig as f, prepareArtifactUpload as i, REPORTER_ENV as l, resolveMode as m, bundleImagePath as n, resultLink as o, loadConfigSync as p, createRawGraphBundle as r, uploadRawGraph as s, RAW_GRAPH_BUNDLE_INDEX as t, Recorder as u };
 
-//# sourceMappingURL=upload-giSVxpun.mjs.map
+//# sourceMappingURL=upload-Bd6rKvUx.mjs.map