@ralphralphai/playwright 1.1.0 → 1.3.0

package/README.md

@@ -50,15 +50,12 @@ export default defineConfig({
 });
 ```
 
-**4. Run:**
+**4. Run with your upload key** (see [Uploading to Ralph](#uploading-to-ralph)):
 
 ```sh
-RALPH_MODE=local pnpm exec playwright test
+RALPH_UPLOAD_KEY=… RALPH_APP_ID=… pnpm exec playwright test
 ```
 
-The merged graph for the run is written to `test-results/ralph/`. To send it to
-Ralph, see [Uploading to Ralph](#uploading-to-ralph).
-
 ## Tag your elements
 
 Add `data-track-id` to elements, using the same ids as your
@@ -112,6 +109,28 @@ test('shipping options', { tag: '@ralph' }, async ({ page, ralph }) => {
 
 `url` only changes what is recorded; the browser doesn't navigate.
 
+### Node conditions, for pages that render differently at one URL
+
+When one URL renders differently by visitor (a plan, an experiment group) or by
+page state (an open dialog), declare what each screenshot stands for. The test is
+the only source of a node's conditions, including sets of values:
+
+```ts
+await page.goto('https://example.com/checkout');
+const undo = await ralph.setNodeConditions(page, {
+  visitorTags: { plan: ['pro', 'enterprise'] },
+  pageTags: { dialog: [undefined, 'shipping'] }, // absent, or shipping
+});
+await undo();
+```
+
+It changes no app state. A declaration that moves the page to a different node
+records it again; declarations merge until the URL changes. If your app tags
+visitors and pages with `@ralphralphai/tracker`, each recording also checks the
+declaration against those tags: where the app reports a value outside it, the node
+lists it in `tagMismatches` and the upload page shows it, because those nodes would
+match no production traffic. `strictNodeTags` fails the test instead.
+
 ### Waiting for capture
 
 Recordings run in the background. If the test leaves a page before its
@@ -161,27 +180,24 @@ await context.close();
 
 Set with `RALPH_MODE` or the `mode` option:
 
-| Mode     | What happens                                                                                        |
-| -------- | --------------------------------------------------------------------------------------------------- |
-| `off`    | Default. Nothing is recorded, and no config or credentials are needed.                              |
-| `local`  | `@ralph` tests are recorded, and the reporter writes the merged graph locally.                      |
-| `upload` | As `local`, and the reporter uploads the graph once the run ends. Default when `RALPH_UPLOAD_KEY` is set. |
+| Mode     | What happens                                                                                    |
+| -------- | ----------------------------------------------------------------------------------------------- |
+| `off`    | Default. Nothing is recorded, and no config or credentials are needed.                          |
+| `upload` | `@ralph` tests are recorded, and the reporter uploads the run. Default when `RALPH_UPLOAD_KEY` is set. |
 
-Untagged tests are never recorded. In `local` or `upload` mode, calling
+Untagged tests are never recorded. In `upload` mode, calling
 `ralph.recordNode` in an untagged test throws.
 
 ## Uploading to Ralph
 
-1. Create an upload key for your project with `/api/project/key/create`, and
-   keep it in your CI secrets.
-2. Set these as environment variables, or `apiUrl` and `appId` as
+1. Create an upload key for your project in the project dashboard.
+2. Set these as environment variables, or `appId` as
    [reporter options](#reporter-options):
 
-   | Variable           | Value                                           |
-   | ------------------ | ----------------------------------------------- |
-   | `RALPH_UPLOAD_KEY` | The upload key. Environment only.               |
-   | `RALPH_API_URL`    | Your Ralph server. HTTPS, or HTTP on localhost. |
-   | `RALPH_APP_ID`     | The app the recordings belong to.               |
+   | Variable           | Value                                              |
+   | ------------------ | -------------------------------------------------- |
+   | `RALPH_UPLOAD_KEY` | The upload key. Environment only.                  |
+   | `RALPH_APP_ID`     | The app the recordings belong to.                  |
 
 3. Run:
 
@@ -189,16 +205,15 @@ Untagged tests are never recorded. In `local` or `upload` mode, calling
    RALPH_MODE=upload pnpm exec playwright test
    ```
 
-The reporter uploads the whole run once and prints the link:
+The reporter uploads the whole run once. It prints the result link before the
+upload starts, so you can open it straight away and watch the run upload and
+then be processed:
 
 ```
-Ralph: uploaded the run's raw graph. https://dash.ralphralph.ai/uploads/0f6c6a2e-…
+Ralph: uploading the run. Follow the upload and processing at https://dash.ralphralph.ai/uploads/0f6c6a2e-…
+Ralph: uploaded the run. Ralph is processing it at https://dash.ralphralph.ai/uploads/0f6c6a2e-…
 ```
 
-- Retried tests contribute only their final attempt.
-- Every test in a run must use the same Ralph config, `runId`, and `buildId`.
-- If the upload fails, the run fails.
-
 ### Sharded runs
 
 Use the `blob` reporter on each shard, then merge with the Ralph reporter:
@@ -208,7 +223,7 @@ Use the `blob` reporter on each shard, then merge with the Ralph reporter:
 RALPH_MODE=upload pnpm exec playwright test --shard=1/4 --reporter blob
 
 # Once, after collecting every shard's blob-report/ into all-blob-reports/:
-RALPH_MODE=upload RALPH_UPLOAD_KEY=… RALPH_API_URL=… RALPH_APP_ID=… \
+RALPH_MODE=upload RALPH_UPLOAD_KEY=… RALPH_APP_ID=… \
   pnpm exec playwright merge-reports --reporter @ralphralphai/playwright/reporter ./all-blob-reports
 ```
 
@@ -260,14 +275,14 @@ Set `ralphOptions` in `playwright.config.ts`, or per file with `test.use`:
 ```ts
 export default defineConfig<RalphFixtures>({
   use: {
-    ralphOptions: { mode: 'local', buildId: process.env.GIT_SHA, settleMs: 300 },
+    ralphOptions: { buildId: process.env.GIT_SHA, settleMs: 300 },
   },
 });
 ```
 
 | Option            | Default                  | What it does                                                                                    |
 | ----------------- | ------------------------ | ----------------------------------------------------------------------------------------------- |
-| `mode`            | `RALPH_MODE`, else `off` | `off`, `local`, or `upload`. See [Modes](#modes).                                               |
+| `mode`            | `RALPH_MODE`, else `off` | `off` or `upload`. See [Modes](#modes).                                                         |
 | `configPath`      | `ralph.jsonc`            | Path to the config, relative to the Playwright config.                                          |
 | `config`          |                          | An inline config instead of a file (type: `WebRalphConfig`).                                    |
 | `buildId`         | `RALPH_BUILD_ID`         | Your app's build, to line up recordings with its analytics.                                     |
@@ -276,6 +291,7 @@ export default defineConfig<RalphFixtures>({
 | `recordTimeoutMs` | 5000                     | Budget for one recording, including `settleMs` and `ready`. Must exceed `settleMs`.             |
 | `ready`           |                          | `(page, signal) => Promise<void>`. Waits for your app before an automatic recording. Honor `signal`. |
 | `reduceMotion`    | `false`                  | Emulates `prefers-reduced-motion: reduce` and waits for finite animations before recording.     |
+| `strictNodeTags`  | `false`                  | Fails the test when the app reports a tag outside what `ralph.setNodeConditions` declared.      |
 
 ## Reporter options
 
@@ -286,7 +302,6 @@ reporter: [['list'], ['@ralphralphai/playwright/reporter', { appId: 'my-app' }]]
 | Option            | Default                                           | What it does                                    |
 | ----------------- | ------------------------------------------------- | ----------------------------------------------- |
 | `mode`            | `RALPH_MODE`, else `upload` if `RALPH_UPLOAD_KEY` | `upload` uploads the run.                       |
-| `apiUrl`          | `RALPH_API_URL`                                   | Your Ralph server.                              |
 | `appId`           | `RALPH_APP_ID`                                    | The app the recordings belong to.               |
 | `uploadTimeoutMs` | 120000                                            | Upload timeout.                                 |
 | `outputDir`       | `ralph/` in the first project's output directory  | Where the merged graph is written.              |

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_upload = require("./upload-QZreR5i6.cjs");
+const require_upload = require("./upload-BzqsXl26.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let _playwright_test = require("@playwright/test");
@@ -100,6 +100,10 @@ const test = _playwright_test.test.extend({
 			recordNode: async () => {
 				checkOptIn();
 			},
+			setNodeConditions: async () => {
+				checkOptIn();
+				return async () => {};
+			},
 			waitForCapture: async () => {},
 			pause: () => {},
 			resume: () => {},
@@ -139,6 +143,7 @@ Object.defineProperty(exports, "mergeTests", {
 		return _playwright_test.mergeTests;
 	}
 });
+exports.prepareArtifactUpload = require_upload.prepareArtifactUpload;
 exports.ralphProjects = ralphProjects;
 exports.test = test;
 exports.uploadRawGraph = require_upload.uploadRawGraph;

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["loadConfigSync","base","resolveMode","path","loadConfig","Recorder"],"sources":["../src/screens.ts","../src/index.ts"],"sourcesContent":["import type {\n  PlaywrightTestOptions,\n  PlaywrightWorkerOptions,\n  Project,\n  TestInfo,\n} from '@playwright/test';\nimport type { ScreenSize } from '@ralphralphai/config';\n\nimport { loadConfigSync } from './config';\nimport type { RalphOptions } from './types';\n\ntype RalphProject = Project<\n  PlaywrightTestOptions & { ralphOptions: RalphOptions },\n  PlaywrightWorkerOptions\n>;\n\nexport const SCREEN_TAG_PREFIX = '@ralph-screen:';\n\nexport type RalphProjectOptions = Pick<\n  RalphOptions,\n  'config' | 'configPath'\n> & {\n  /** Resolves a relative `configPath`; defaults to the current directory. */\n  root?: string;\n};\n\ntype ScreenMetadata = { screenSize: ScreenSize; screenSizes: ScreenSize[] };\n\nexport function screenLabel(size: ScreenSize): string {\n  return size.width + 'x' + size.height;\n}\n\n/**\n * Expands `base` into one project per `screenSizes` entry of the Ralph config.\n * Each project's viewport is that screen size.\n */\nexport function ralphProjects(\n  base: RalphProject = {},\n  options: RalphProjectOptions = {},\n): RalphProject[] {\n  const { screenSizes } = loadConfigSync(\n    options,\n    options.root ?? process.cwd(),\n  ).config;\n  if (!screenSizes.length) {\n    throw new Error('The Ralph config declares no screenSizes.');\n  }\n  return screenSizes.map((screenSize) => {\n    const label = screenLabel(screenSize);\n    const ralph: ScreenMetadata = { screenSize, screenSizes };\n    return {\n      ...base,\n      name: base.name ? base.name + ' ' + label : label,\n      use: {\n        ...base.use,\n        viewport: { width: screenSize.width, height: screenSize.height },\n      },\n      metadata: { ...base.metadata, ralph },\n    };\n  });\n}\n\n/**\n * Skips a test whose `@ralph-screen:WxH` tags exclude the current project's\n * screen size. Untagged tests run at every size; other projects are untouched.\n */\nexport function applyScreenSelection(testInfo: TestInfo): void {\n  const selected = testInfo.tags\n    .filter((tag) => tag.startsWith(SCREEN_TAG_PREFIX))\n    .map((tag) => tag.slice(SCREEN_TAG_PREFIX.length));\n  const metadata = (testInfo.project.metadata as { ralph?: ScreenMetadata })\n    .ralph;\n  if (!selected.length || !metadata) {\n    return;\n  }\n  const known = metadata.screenSizes.map(screenLabel);\n  const unknown = selected.filter((label) => !known.includes(label));\n  if (unknown.length) {\n    throw new Error(\n      'Unknown Ralph screen size ' +\n        unknown.join(', ') +\n        '; the config declares ' +\n        known.join(', ') +\n        '.',\n    );\n  }\n  const current = screenLabel(metadata.screenSize);\n  testInfo.skip(\n    !selected.includes(current),\n    'Not selected for Ralph screen size ' + current + '.',\n  );\n}\n","import path from 'node:path';\n\nimport { test as base } from '@playwright/test';\nimport type {\n  PlaywrightTestArgs,\n  PlaywrightTestOptions,\n  PlaywrightWorkerArgs,\n  PlaywrightWorkerOptions,\n  TestType,\n} from '@playwright/test';\n\nimport { loadConfig, resolveMode } from './config';\nimport { Recorder, REPORTER_ENV } from './recorder';\nimport { applyScreenSelection } from './screens';\nimport type { ConfigSnapshot, Ralph, RalphOptions } from './types';\n\nexport { expect, mergeTests } from '@playwright/test';\nexport type { WebRalphConfig } from '@ralphralphai/config';\nexport { createRawGraphBundle, uploadRawGraph } from './upload';\nexport type {\n  UploadOptions,\n  UploadReceipt,\n  RawGraphScreenshot,\n  RawGraphBundleIndex,\n} from './upload';\nexport { MANIFEST_ATTACHMENT } from './recorder';\nexport { ralphProjects, SCREEN_TAG_PREFIX } from './screens';\nexport type { RalphProjectOptions } from './screens';\nexport type { RalphReporterOptions } from './reporter';\nexport type {\n  RawGraphManifest,\n  RawGraph,\n  RawGraphFile,\n  RawPage,\n  RawNode,\n  RecordNodeOptions,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n} from './types';\n\nexport type RalphFixtures = { ralph: Ralph; ralphOptions: RalphOptions };\n\ntype InternalFixtures = {\n  _ralphScreen: void;\n  _ralphRecorder: Recorder | null;\n};\ntype WorkerFixtures = { _ralphConfigs: Map<string, Promise<ConfigSnapshot>> };\n\nexport const test: TestType<\n  PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures,\n  PlaywrightWorkerArgs & PlaywrightWorkerOptions\n> = base.extend<RalphFixtures & InternalFixtures, WorkerFixtures>({\n  ralphOptions: [{}, { option: true }],\n  _ralphConfigs: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use) => {\n      await use(new Map());\n    },\n    { scope: 'worker' },\n  ],\n  _ralphScreen: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use, testInfo) => {\n      // Screen selection chooses which flows run, so it applies in every mode.\n      applyScreenSelection(testInfo);\n      await use();\n    },\n    { auto: true },\n  ],\n  _ralphRecorder: [\n    // _ralphScreen is specified here so that the playwright treat that it is\n    // a dependency of this fixture.\n    async ({ ralphOptions, _ralphConfigs, _ralphScreen }, use, testInfo) => {\n      const mode = resolveMode(ralphOptions);\n      if (!testInfo.tags.includes('@ralph') || mode === 'off') {\n        await use(null);\n        return;\n      }\n\n      // A sharded run's blob reports are merged, and uploaded by the Ralph\n      // reporter, in `playwright merge-reports`.\n      const reported =\n        process.env[REPORTER_ENV] ||\n        testInfo.config.reporter.some(([name]) => name === 'blob');\n      if (mode === 'upload' && !reported) {\n        throw new Error(\n          \"Ralph uploads one merged graph per run from its reporter. Add ['@ralphralphai/playwright/reporter'] to `reporter` in playwright.config, or use the blob reporter and merge-reports when sharding.\",\n        );\n      }\n\n      const root = testInfo.config.configFile\n        ? path.dirname(testInfo.config.configFile)\n        : process.cwd();\n\n      const key = JSON.stringify({\n        root,\n        config: ralphOptions.config,\n        configPath: ralphOptions.configPath,\n      });\n\n      let pending = _ralphConfigs.get(key);\n      if (!pending) {\n        pending = loadConfig(ralphOptions, root);\n        _ralphConfigs.set(key, pending);\n      }\n\n      const recorder = new Recorder(\n        ralphOptions,\n        await pending,\n        testInfo,\n        mode,\n      );\n\n      try {\n        await use(recorder);\n      } finally {\n        await recorder.finish();\n      }\n    },\n    { auto: true, timeout: 30_000 },\n  ],\n  ralph: async ({ _ralphRecorder, ralphOptions }, use) => {\n    const checkOptIn = () => {\n      if (resolveMode(ralphOptions) !== 'off') {\n        throw new Error('Opt this test into Ralph with the @ralph tag.');\n      }\n    };\n\n    await use(\n      _ralphRecorder ?? {\n        recordNode: async () => {\n          checkOptIn();\n        },\n        waitForCapture: async () => {},\n        pause: () => {},\n        resume: () => {},\n        observe: () => {\n          checkOptIn();\n        },\n      },\n    );\n  },\n  // On the context rather than per page, so popups start out reduced too.\n  contextOptions: async ({ contextOptions, ralphOptions }, use, testInfo) => {\n    const recording =\n      testInfo.tags.includes('@ralph') && resolveMode(ralphOptions) !== 'off';\n    await use(\n      recording && ralphOptions.reduceMotion\n        ? { ...contextOptions, reducedMotion: 'reduce' }\n        : contextOptions,\n    );\n  },\n  context: async ({ context, _ralphRecorder }, use) => {\n    _ralphRecorder?.observe(context);\n    try {\n      await use(context);\n    } finally {\n      // The base context fixture closes its pages next; pending recordings still need them alive.\n      await _ralphRecorder?.stopContext(context);\n    }\n  },\n});\n"],"mappings":"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"}
+{"version":3,"file":"index.cjs","names":["loadConfigSync","base","resolveMode","path","loadConfig","Recorder"],"sources":["../src/screens.ts","../src/index.ts"],"sourcesContent":["import type {\n  PlaywrightTestOptions,\n  PlaywrightWorkerOptions,\n  Project,\n  TestInfo,\n} from '@playwright/test';\nimport type { ScreenSize } from '@ralphralphai/config';\n\nimport { loadConfigSync } from './config';\nimport type { RalphOptions } from './types';\n\ntype RalphProject = Project<\n  PlaywrightTestOptions & { ralphOptions: RalphOptions },\n  PlaywrightWorkerOptions\n>;\n\nexport const SCREEN_TAG_PREFIX = '@ralph-screen:';\n\nexport type RalphProjectOptions = Pick<\n  RalphOptions,\n  'config' | 'configPath'\n> & {\n  /** Resolves a relative `configPath`; defaults to the current directory. */\n  root?: string;\n};\n\ntype ScreenMetadata = { screenSize: ScreenSize; screenSizes: ScreenSize[] };\n\nexport function screenLabel(size: ScreenSize): string {\n  return size.width + 'x' + size.height;\n}\n\n/**\n * Expands `base` into one project per `screenSizes` entry of the Ralph config.\n * Each project's viewport is that screen size.\n */\nexport function ralphProjects(\n  base: RalphProject = {},\n  options: RalphProjectOptions = {},\n): RalphProject[] {\n  const { screenSizes } = loadConfigSync(\n    options,\n    options.root ?? process.cwd(),\n  ).config;\n  if (!screenSizes.length) {\n    throw new Error('The Ralph config declares no screenSizes.');\n  }\n  return screenSizes.map((screenSize) => {\n    const label = screenLabel(screenSize);\n    const ralph: ScreenMetadata = { screenSize, screenSizes };\n    return {\n      ...base,\n      name: base.name ? base.name + ' ' + label : label,\n      use: {\n        ...base.use,\n        viewport: { width: screenSize.width, height: screenSize.height },\n      },\n      metadata: { ...base.metadata, ralph },\n    };\n  });\n}\n\n/**\n * Skips a test whose `@ralph-screen:WxH` tags exclude the current project's\n * screen size. Untagged tests run at every size; other projects are untouched.\n */\nexport function applyScreenSelection(testInfo: TestInfo): void {\n  const selected = testInfo.tags\n    .filter((tag) => tag.startsWith(SCREEN_TAG_PREFIX))\n    .map((tag) => tag.slice(SCREEN_TAG_PREFIX.length));\n  const metadata = (testInfo.project.metadata as { ralph?: ScreenMetadata })\n    .ralph;\n  if (!selected.length || !metadata) {\n    return;\n  }\n  const known = metadata.screenSizes.map(screenLabel);\n  const unknown = selected.filter((label) => !known.includes(label));\n  if (unknown.length) {\n    throw new Error(\n      'Unknown Ralph screen size ' +\n        unknown.join(', ') +\n        '; the config declares ' +\n        known.join(', ') +\n        '.',\n    );\n  }\n  const current = screenLabel(metadata.screenSize);\n  testInfo.skip(\n    !selected.includes(current),\n    'Not selected for Ralph screen size ' + current + '.',\n  );\n}\n","import path from 'node:path';\n\nimport { test as base } from '@playwright/test';\nimport type {\n  PlaywrightTestArgs,\n  PlaywrightTestOptions,\n  PlaywrightWorkerArgs,\n  PlaywrightWorkerOptions,\n  TestType,\n} from '@playwright/test';\n\nimport { loadConfig, resolveMode } from './config';\nimport { Recorder, REPORTER_ENV } from './recorder';\nimport { applyScreenSelection } from './screens';\nimport type { ConfigSnapshot, Ralph, RalphOptions } from './types';\n\nexport { expect, mergeTests } from '@playwright/test';\nexport type { WebRalphConfig } from '@ralphralphai/config';\nexport {\n  createRawGraphBundle,\n  prepareArtifactUpload,\n  uploadRawGraph,\n} from './upload';\nexport type {\n  PreparedUpload,\n  UploadOptions,\n  UploadReceipt,\n  RawGraphScreenshot,\n  RawGraphBundleIndex,\n} from './upload';\nexport { MANIFEST_ATTACHMENT } from './recorder';\nexport { ralphProjects, SCREEN_TAG_PREFIX } from './screens';\nexport type { RalphProjectOptions } from './screens';\nexport type { RalphReporterOptions } from './reporter';\nexport type {\n  RawGraphManifest,\n  RawGraph,\n  RawGraphFile,\n  RawPage,\n  RawNode,\n  RecordNodeOptions,\n  ConditionsDeclaration,\n  NodeConditions,\n  RecordedTags,\n  TagConditions,\n  TagDeclaration,\n  TagValue,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n} from './types';\n\nexport type RalphFixtures = { ralph: Ralph; ralphOptions: RalphOptions };\n\ntype InternalFixtures = {\n  _ralphScreen: void;\n  _ralphRecorder: Recorder | null;\n};\ntype WorkerFixtures = { _ralphConfigs: Map<string, Promise<ConfigSnapshot>> };\n\nexport const test: TestType<\n  PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures,\n  PlaywrightWorkerArgs & PlaywrightWorkerOptions\n> = base.extend<RalphFixtures & InternalFixtures, WorkerFixtures>({\n  ralphOptions: [{}, { option: true }],\n  _ralphConfigs: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use) => {\n      await use(new Map());\n    },\n    { scope: 'worker' },\n  ],\n  _ralphScreen: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use, testInfo) => {\n      // Screen selection chooses which flows run, so it applies in every mode.\n      applyScreenSelection(testInfo);\n      await use();\n    },\n    { auto: true },\n  ],\n  _ralphRecorder: [\n    // _ralphScreen is specified here so that the playwright treat that it is\n    // a dependency of this fixture.\n    async ({ ralphOptions, _ralphConfigs, _ralphScreen }, use, testInfo) => {\n      const mode = resolveMode(ralphOptions);\n      if (!testInfo.tags.includes('@ralph') || mode === 'off') {\n        await use(null);\n        return;\n      }\n\n      // A sharded run's blob reports are merged, and uploaded by the Ralph\n      // reporter, in `playwright merge-reports`.\n      const reported =\n        process.env[REPORTER_ENV] ||\n        testInfo.config.reporter.some(([name]) => name === 'blob');\n      if (mode === 'upload' && !reported) {\n        throw new Error(\n          \"Ralph uploads one merged graph per run from its reporter. Add ['@ralphralphai/playwright/reporter'] to `reporter` in playwright.config, or use the blob reporter and merge-reports when sharding.\",\n        );\n      }\n\n      const root = testInfo.config.configFile\n        ? path.dirname(testInfo.config.configFile)\n        : process.cwd();\n\n      const key = JSON.stringify({\n        root,\n        config: ralphOptions.config,\n        configPath: ralphOptions.configPath,\n      });\n\n      let pending = _ralphConfigs.get(key);\n      if (!pending) {\n        pending = loadConfig(ralphOptions, root);\n        _ralphConfigs.set(key, pending);\n      }\n\n      const recorder = new Recorder(\n        ralphOptions,\n        await pending,\n        testInfo,\n        mode,\n      );\n\n      try {\n        await use(recorder);\n      } finally {\n        await recorder.finish();\n      }\n    },\n    { auto: true, timeout: 30_000 },\n  ],\n  ralph: async ({ _ralphRecorder, ralphOptions }, use) => {\n    const checkOptIn = () => {\n      if (resolveMode(ralphOptions) !== 'off') {\n        throw new Error('Opt this test into Ralph with the @ralph tag.');\n      }\n    };\n\n    await use(\n      _ralphRecorder ?? {\n        recordNode: async () => {\n          checkOptIn();\n        },\n        setNodeConditions: async () => {\n          checkOptIn();\n          return async () => {};\n        },\n        waitForCapture: async () => {},\n        pause: () => {},\n        resume: () => {},\n        observe: () => {\n          checkOptIn();\n        },\n      },\n    );\n  },\n  // On the context rather than per page, so popups start out reduced too.\n  contextOptions: async ({ contextOptions, ralphOptions }, use, testInfo) => {\n    const recording =\n      testInfo.tags.includes('@ralph') && resolveMode(ralphOptions) !== 'off';\n    await use(\n      recording && ralphOptions.reduceMotion\n        ? { ...contextOptions, reducedMotion: 'reduce' }\n        : contextOptions,\n    );\n  },\n  context: async ({ context, _ralphRecorder }, use) => {\n    _ralphRecorder?.observe(context);\n    try {\n      await use(context);\n    } finally {\n      // The base context fixture closes its pages next; pending recordings still need them alive.\n      await _ralphRecorder?.stopContext(context);\n    }\n  },\n});\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -12,13 +12,43 @@ type RalphOptions = {
   reduceMotion?: boolean;
   recordTimeoutMs?: number;
   ready?: (page: Page, signal: AbortSignal) => Promise<void>;
+  /**
+   * Fail the test when the app reports a tag outside the set the test
+   * declared for it. Otherwise the mismatch is only listed on the node.
+   */
+  strictNodeTags?: boolean;
 };
 type RecordNodeOptions = {
   state?: string;
   url?: string;
 };
+type TagValue = boolean | number | string;
+/** One value, or the set of values the node stands for. `null` and `undefined` in a set mean the key is absent. */
+type TagDeclaration = Record<string, TagValue | (TagValue | null | undefined)[] | undefined>;
+type ConditionsDeclaration = {
+  visitorTags?: TagDeclaration;
+  pageTags?: TagDeclaration;
+};
+/** Each key's accepted values, `null` accepting the key's absence. */
+type TagConditions = Record<string, (TagValue | null)[]>;
+type NodeConditions = {
+  visitorTags?: TagConditions;
+  pageTags?: TagConditions;
+};
+/** The tags the app's tracker had in effect. */
+type RecordedTags = {
+  visitorTags: Record<string, TagValue>;
+  pageTags: Record<string, TagValue>;
+};
 type Ralph = {
   recordNode(page: Page, options?: RecordNodeOptions): Promise<void>;
+  /**
+   * Declares which visitor and page tags the node on screen stands for,
+   * merged over earlier declarations until the URL changes, and records the
+   * node. It changes no app state. The returned function removes this call's
+   * declaration and records again.
+   */
+  setNodeConditions(page: Page, conditions: ConditionsDeclaration): Promise<() => Promise<void>>;
   waitForCapture(): Promise<void>;
   pause(): void;
   resume(): void;
@@ -54,8 +84,14 @@ type RawNode = {
   requestedAt: string;
   actualUrl: string;
   url: string;
-  trigger: 'url-change' | 'explicit';
+  trigger: 'url-change' | 'condition-change' | 'explicit';
   state?: string;
+  /** What the node stands for, as the test declared it. */
+  conditions?: NodeConditions;
+  /** What the app's tracker had in effect, absent when the page runs none. */
+  reportedTags?: RecordedTags;
+  /** Declared keys the reported value falls outside, as `visitorTags.plan`. */
+  tagMismatches?: string[];
   /**
    * 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 and
@@ -175,12 +211,17 @@ type RawGraphScreenshot = {
   contentType: Screenshot['contentType'];
   bytes: Uint8Array;
 };
+/** An artifact the server reserved, which the upload and the manifest must name. */
+type PreparedUpload = {
+  artifactId: string;
+  /** Where the result opens in the Ralph dashboard, when the server knows. */
+  resultUrl?: string;
+};
+/** The bundle is stored and queued; the result page shows it being processed. */
 type UploadReceipt = {
   result: 'ok';
-  status: 'received';
+  status: 'queued';
   artifactId: string;
-  resultId: string;
-  /** Where the result opens in the Ralph dashboard, when the server knows. */
   resultUrl?: string;
   replayed: boolean;
 };
@@ -191,13 +232,18 @@ type RawGraphBundleIndex = {
     path: string;
   }[];
 };
+/** The bundle `uploadRawGraph` streams, whole, for saving or inspecting it. */
+declare function createRawGraphBundle(manifest: RawGraphManifest, screenshots: readonly RawGraphScreenshot[]): Promise<Uint8Array>;
 /**
- * Packs the manifest and screenshots into a gzipped tar archive:
- *
- *   raw_graph.json               { manifest, screenshots: [{ nodeId, path }] }
- *   assets/images/<id>.webp    raw screenshot bytes (.png when too large for WebP)
+ * 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.
+ */
+declare function prepareArtifactUpload(options: UploadOptions): Promise<PreparedUpload>;
+/**
+ * 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.
  */
-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
@@ -226,5 +272,5 @@ type RalphFixtures = {
 };
 declare const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 //#endregion
-export { type ConfigSnapshot, MANIFEST_ATTACHMENT, type PageLayout, type Ralph, RalphFixtures, type RalphOptions, type RalphProjectOptions, type RalphReporterOptions, type RawGraph, type RawGraphBundleIndex, type RawGraphFile, type RawGraphManifest, type RawGraphScreenshot, type RawNode, type RawPage, type RecordNodeOptions, SCREEN_TAG_PREFIX, type TrackedElement, type UploadOptions, type UploadReceipt, type WebRalphConfig, createRawGraphBundle, expect, mergeTests, ralphProjects, test, uploadRawGraph };
+export { type ConditionsDeclaration, type ConfigSnapshot, MANIFEST_ATTACHMENT, type NodeConditions, type PageLayout, type PreparedUpload, type Ralph, RalphFixtures, type RalphOptions, type RalphProjectOptions, type RalphReporterOptions, type RawGraph, type RawGraphBundleIndex, type RawGraphFile, type RawGraphManifest, type RawGraphScreenshot, type RawNode, type RawPage, type RecordNodeOptions, type RecordedTags, SCREEN_TAG_PREFIX, type TagConditions, type TagDeclaration, type TagValue, type TrackedElement, type UploadOptions, type UploadReceipt, type WebRalphConfig, createRawGraphBundle, expect, mergeTests, prepareArtifactUpload, ralphProjects, test, uploadRawGraph };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as uploadRawGraph, c as Recorder, d as loadConfigSync, f as resolveMode, o as MANIFEST_ATTACHMENT, r as createRawGraphBundle, u as loadConfig } from "./upload-giSVxpun.mjs";
+import { c as MANIFEST_ATTACHMENT, f as loadConfig, i as prepareArtifactUpload, m as resolveMode, p as loadConfigSync, r as createRawGraphBundle, s as uploadRawGraph, u as Recorder } from "./upload-Bd6rKvUx.mjs";
 import path from "node:path";
 import { expect, mergeTests, test as test$1 } from "@playwright/test";
 //#region src/screens.ts
@@ -98,6 +98,10 @@ const test = test$1.extend({
 			recordNode: async () => {
 				checkOptIn();
 			},
+			setNodeConditions: async () => {
+				checkOptIn();
+				return async () => {};
+			},
 			waitForCapture: async () => {},
 			pause: () => {},
 			resume: () => {},
@@ -122,6 +126,6 @@ const test = test$1.extend({
 	}
 });
 //#endregion
-export { MANIFEST_ATTACHMENT, SCREEN_TAG_PREFIX, createRawGraphBundle, expect, mergeTests, ralphProjects, test, uploadRawGraph };
+export { MANIFEST_ATTACHMENT, SCREEN_TAG_PREFIX, createRawGraphBundle, expect, mergeTests, prepareArtifactUpload, ralphProjects, test, uploadRawGraph };
 
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["base"],"sources":["../src/screens.ts","../src/index.ts"],"sourcesContent":["import type {\n  PlaywrightTestOptions,\n  PlaywrightWorkerOptions,\n  Project,\n  TestInfo,\n} from '@playwright/test';\nimport type { ScreenSize } from '@ralphralphai/config';\n\nimport { loadConfigSync } from './config';\nimport type { RalphOptions } from './types';\n\ntype RalphProject = Project<\n  PlaywrightTestOptions & { ralphOptions: RalphOptions },\n  PlaywrightWorkerOptions\n>;\n\nexport const SCREEN_TAG_PREFIX = '@ralph-screen:';\n\nexport type RalphProjectOptions = Pick<\n  RalphOptions,\n  'config' | 'configPath'\n> & {\n  /** Resolves a relative `configPath`; defaults to the current directory. */\n  root?: string;\n};\n\ntype ScreenMetadata = { screenSize: ScreenSize; screenSizes: ScreenSize[] };\n\nexport function screenLabel(size: ScreenSize): string {\n  return size.width + 'x' + size.height;\n}\n\n/**\n * Expands `base` into one project per `screenSizes` entry of the Ralph config.\n * Each project's viewport is that screen size.\n */\nexport function ralphProjects(\n  base: RalphProject = {},\n  options: RalphProjectOptions = {},\n): RalphProject[] {\n  const { screenSizes } = loadConfigSync(\n    options,\n    options.root ?? process.cwd(),\n  ).config;\n  if (!screenSizes.length) {\n    throw new Error('The Ralph config declares no screenSizes.');\n  }\n  return screenSizes.map((screenSize) => {\n    const label = screenLabel(screenSize);\n    const ralph: ScreenMetadata = { screenSize, screenSizes };\n    return {\n      ...base,\n      name: base.name ? base.name + ' ' + label : label,\n      use: {\n        ...base.use,\n        viewport: { width: screenSize.width, height: screenSize.height },\n      },\n      metadata: { ...base.metadata, ralph },\n    };\n  });\n}\n\n/**\n * Skips a test whose `@ralph-screen:WxH` tags exclude the current project's\n * screen size. Untagged tests run at every size; other projects are untouched.\n */\nexport function applyScreenSelection(testInfo: TestInfo): void {\n  const selected = testInfo.tags\n    .filter((tag) => tag.startsWith(SCREEN_TAG_PREFIX))\n    .map((tag) => tag.slice(SCREEN_TAG_PREFIX.length));\n  const metadata = (testInfo.project.metadata as { ralph?: ScreenMetadata })\n    .ralph;\n  if (!selected.length || !metadata) {\n    return;\n  }\n  const known = metadata.screenSizes.map(screenLabel);\n  const unknown = selected.filter((label) => !known.includes(label));\n  if (unknown.length) {\n    throw new Error(\n      'Unknown Ralph screen size ' +\n        unknown.join(', ') +\n        '; the config declares ' +\n        known.join(', ') +\n        '.',\n    );\n  }\n  const current = screenLabel(metadata.screenSize);\n  testInfo.skip(\n    !selected.includes(current),\n    'Not selected for Ralph screen size ' + current + '.',\n  );\n}\n","import path from 'node:path';\n\nimport { test as base } from '@playwright/test';\nimport type {\n  PlaywrightTestArgs,\n  PlaywrightTestOptions,\n  PlaywrightWorkerArgs,\n  PlaywrightWorkerOptions,\n  TestType,\n} from '@playwright/test';\n\nimport { loadConfig, resolveMode } from './config';\nimport { Recorder, REPORTER_ENV } from './recorder';\nimport { applyScreenSelection } from './screens';\nimport type { ConfigSnapshot, Ralph, RalphOptions } from './types';\n\nexport { expect, mergeTests } from '@playwright/test';\nexport type { WebRalphConfig } from '@ralphralphai/config';\nexport { createRawGraphBundle, uploadRawGraph } from './upload';\nexport type {\n  UploadOptions,\n  UploadReceipt,\n  RawGraphScreenshot,\n  RawGraphBundleIndex,\n} from './upload';\nexport { MANIFEST_ATTACHMENT } from './recorder';\nexport { ralphProjects, SCREEN_TAG_PREFIX } from './screens';\nexport type { RalphProjectOptions } from './screens';\nexport type { RalphReporterOptions } from './reporter';\nexport type {\n  RawGraphManifest,\n  RawGraph,\n  RawGraphFile,\n  RawPage,\n  RawNode,\n  RecordNodeOptions,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n} from './types';\n\nexport type RalphFixtures = { ralph: Ralph; ralphOptions: RalphOptions };\n\ntype InternalFixtures = {\n  _ralphScreen: void;\n  _ralphRecorder: Recorder | null;\n};\ntype WorkerFixtures = { _ralphConfigs: Map<string, Promise<ConfigSnapshot>> };\n\nexport const test: TestType<\n  PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures,\n  PlaywrightWorkerArgs & PlaywrightWorkerOptions\n> = base.extend<RalphFixtures & InternalFixtures, WorkerFixtures>({\n  ralphOptions: [{}, { option: true }],\n  _ralphConfigs: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use) => {\n      await use(new Map());\n    },\n    { scope: 'worker' },\n  ],\n  _ralphScreen: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use, testInfo) => {\n      // Screen selection chooses which flows run, so it applies in every mode.\n      applyScreenSelection(testInfo);\n      await use();\n    },\n    { auto: true },\n  ],\n  _ralphRecorder: [\n    // _ralphScreen is specified here so that the playwright treat that it is\n    // a dependency of this fixture.\n    async ({ ralphOptions, _ralphConfigs, _ralphScreen }, use, testInfo) => {\n      const mode = resolveMode(ralphOptions);\n      if (!testInfo.tags.includes('@ralph') || mode === 'off') {\n        await use(null);\n        return;\n      }\n\n      // A sharded run's blob reports are merged, and uploaded by the Ralph\n      // reporter, in `playwright merge-reports`.\n      const reported =\n        process.env[REPORTER_ENV] ||\n        testInfo.config.reporter.some(([name]) => name === 'blob');\n      if (mode === 'upload' && !reported) {\n        throw new Error(\n          \"Ralph uploads one merged graph per run from its reporter. Add ['@ralphralphai/playwright/reporter'] to `reporter` in playwright.config, or use the blob reporter and merge-reports when sharding.\",\n        );\n      }\n\n      const root = testInfo.config.configFile\n        ? path.dirname(testInfo.config.configFile)\n        : process.cwd();\n\n      const key = JSON.stringify({\n        root,\n        config: ralphOptions.config,\n        configPath: ralphOptions.configPath,\n      });\n\n      let pending = _ralphConfigs.get(key);\n      if (!pending) {\n        pending = loadConfig(ralphOptions, root);\n        _ralphConfigs.set(key, pending);\n      }\n\n      const recorder = new Recorder(\n        ralphOptions,\n        await pending,\n        testInfo,\n        mode,\n      );\n\n      try {\n        await use(recorder);\n      } finally {\n        await recorder.finish();\n      }\n    },\n    { auto: true, timeout: 30_000 },\n  ],\n  ralph: async ({ _ralphRecorder, ralphOptions }, use) => {\n    const checkOptIn = () => {\n      if (resolveMode(ralphOptions) !== 'off') {\n        throw new Error('Opt this test into Ralph with the @ralph tag.');\n      }\n    };\n\n    await use(\n      _ralphRecorder ?? {\n        recordNode: async () => {\n          checkOptIn();\n        },\n        waitForCapture: async () => {},\n        pause: () => {},\n        resume: () => {},\n        observe: () => {\n          checkOptIn();\n        },\n      },\n    );\n  },\n  // On the context rather than per page, so popups start out reduced too.\n  contextOptions: async ({ contextOptions, ralphOptions }, use, testInfo) => {\n    const recording =\n      testInfo.tags.includes('@ralph') && resolveMode(ralphOptions) !== 'off';\n    await use(\n      recording && ralphOptions.reduceMotion\n        ? { ...contextOptions, reducedMotion: 'reduce' }\n        : contextOptions,\n    );\n  },\n  context: async ({ context, _ralphRecorder }, use) => {\n    _ralphRecorder?.observe(context);\n    try {\n      await use(context);\n    } finally {\n      // The base context fixture closes its pages next; pending recordings still need them alive.\n      await _ralphRecorder?.stopContext(context);\n    }\n  },\n});\n"],"mappings":";;;;AAgBA,MAAa,oBAAoB;AAYjC,SAAgB,YAAY,MAA0B;CACpD,OAAO,KAAK,QAAQ,MAAM,KAAK;AACjC;;;;;AAMA,SAAgB,cACd,OAAqB,CAAC,GACtB,UAA+B,CAAC,GAChB;CAChB,MAAM,EAAE,gBAAgB,eACtB,SACA,QAAQ,QAAQ,QAAQ,IAAI,CAC9B,CAAC,CAAC;CACF,IAAI,CAAC,YAAY,QACf,MAAM,IAAI,MAAM,2CAA2C;CAE7D,OAAO,YAAY,KAAK,eAAe;EACrC,MAAM,QAAQ,YAAY,UAAU;EACpC,MAAM,QAAwB;GAAE;GAAY;EAAY;EACxD,OAAO;GACL,GAAG;GACH,MAAM,KAAK,OAAO,KAAK,OAAO,MAAM,QAAQ;GAC5C,KAAK;IACH,GAAG,KAAK;IACR,UAAU;KAAE,OAAO,WAAW;KAAO,QAAQ,WAAW;IAAO;GACjE;GACA,UAAU;IAAE,GAAG,KAAK;IAAU;GAAM;EACtC;CACF,CAAC;AACH;;;;;AAMA,SAAgB,qBAAqB,UAA0B;CAC7D,MAAM,WAAW,SAAS,KACvB,QAAQ,QAAQ,IAAI,WAAW,iBAAiB,CAAC,CAAC,CAClD,KAAK,QAAQ,IAAI,MAAM,EAAwB,CAAC;CACnD,MAAM,WAAY,SAAS,QAAQ,SAChC;CACH,IAAI,CAAC,SAAS,UAAU,CAAC,UACvB;CAEF,MAAM,QAAQ,SAAS,YAAY,IAAI,WAAW;CAClD,MAAM,UAAU,SAAS,QAAQ,UAAU,CAAC,MAAM,SAAS,KAAK,CAAC;CACjE,IAAI,QAAQ,QACV,MAAM,IAAI,MACR,+BACE,QAAQ,KAAK,IAAI,IACjB,2BACA,MAAM,KAAK,IAAI,IACf,GACJ;CAEF,MAAM,UAAU,YAAY,SAAS,UAAU;CAC/C,SAAS,KACP,CAAC,SAAS,SAAS,OAAO,GAC1B,wCAAwC,UAAU,GACpD;AACF;;;ACxCA,MAAa,OAGTA,OAAK,OAAyD;CAChE,cAAc,CAAC,CAAC,GAAG,EAAE,QAAQ,KAAK,CAAC;CACnC,eAAe,CAGb,OAAO,IAAI,QAAQ;EACjB,MAAM,oBAAI,IAAI,IAAI,CAAC;CACrB,GACA,EAAE,OAAO,SAAS,CACpB;CACA,cAAc,CAGZ,OAAO,IAAI,KAAK,aAAa;EAE3B,qBAAqB,QAAQ;EAC7B,MAAM,IAAI;CACZ,GACA,EAAE,MAAM,KAAK,CACf;CACA,gBAAgB,CAGd,OAAO,EAAE,cAAc,eAAe,gBAAgB,KAAK,aAAa;EACtE,MAAM,OAAO,YAAY,YAAY;EACrC,IAAI,CAAC,SAAS,KAAK,SAAS,QAAQ,KAAK,SAAS,OAAO;GACvD,MAAM,IAAI,IAAI;GACd;EACF;EAIA,MAAM,WACJ,QAAQ,IAAA,gCACR,SAAS,OAAO,SAAS,MAAM,CAAC,UAAU,SAAS,MAAM;EAC3D,IAAI,SAAS,YAAY,CAAC,UACxB,MAAM,IAAI,MACR,mMACF;EAGF,MAAM,OAAO,SAAS,OAAO,aACzB,KAAK,QAAQ,SAAS,OAAO,UAAU,IACvC,QAAQ,IAAI;EAEhB,MAAM,MAAM,KAAK,UAAU;GACzB;GACA,QAAQ,aAAa;GACrB,YAAY,aAAa;EAC3B,CAAC;EAED,IAAI,UAAU,cAAc,IAAI,GAAG;EACnC,IAAI,CAAC,SAAS;GACZ,UAAU,WAAW,cAAc,IAAI;GACvC,cAAc,IAAI,KAAK,OAAO;EAChC;EAEA,MAAM,WAAW,IAAI,SACnB,cACA,MAAM,SACN,UACA,IACF;EAEA,IAAI;GACF,MAAM,IAAI,QAAQ;EACpB,UAAU;GACR,MAAM,SAAS,OAAO;EACxB;CACF,GACA;EAAE,MAAM;EAAM,SAAS;CAAO,CAChC;CACA,OAAO,OAAO,EAAE,gBAAgB,gBAAgB,QAAQ;EACtD,MAAM,mBAAmB;GACvB,IAAI,YAAY,YAAY,MAAM,OAChC,MAAM,IAAI,MAAM,+CAA+C;EAEnE;EAEA,MAAM,IACJ,kBAAkB;GAChB,YAAY,YAAY;IACtB,WAAW;GACb;GACA,gBAAgB,YAAY,CAAC;GAC7B,aAAa,CAAC;GACd,cAAc,CAAC;GACf,eAAe;IACb,WAAW;GACb;EACF,CACF;CACF;CAEA,gBAAgB,OAAO,EAAE,gBAAgB,gBAAgB,KAAK,aAAa;EAGzE,MAAM,IADJ,SAAS,KAAK,SAAS,QAAQ,KAAK,YAAY,YAAY,MAAM,SAErD,aAAa,eACtB;GAAE,GAAG;GAAgB,eAAe;EAAS,IAC7C,cACN;CACF;CACA,SAAS,OAAO,EAAE,SAAS,kBAAkB,QAAQ;EACnD,gBAAgB,QAAQ,OAAO;EAC/B,IAAI;GACF,MAAM,IAAI,OAAO;EACnB,UAAU;GAER,MAAM,gBAAgB,YAAY,OAAO;EAC3C;CACF;AACF,CAAC"}
+{"version":3,"file":"index.mjs","names":["base"],"sources":["../src/screens.ts","../src/index.ts"],"sourcesContent":["import type {\n  PlaywrightTestOptions,\n  PlaywrightWorkerOptions,\n  Project,\n  TestInfo,\n} from '@playwright/test';\nimport type { ScreenSize } from '@ralphralphai/config';\n\nimport { loadConfigSync } from './config';\nimport type { RalphOptions } from './types';\n\ntype RalphProject = Project<\n  PlaywrightTestOptions & { ralphOptions: RalphOptions },\n  PlaywrightWorkerOptions\n>;\n\nexport const SCREEN_TAG_PREFIX = '@ralph-screen:';\n\nexport type RalphProjectOptions = Pick<\n  RalphOptions,\n  'config' | 'configPath'\n> & {\n  /** Resolves a relative `configPath`; defaults to the current directory. */\n  root?: string;\n};\n\ntype ScreenMetadata = { screenSize: ScreenSize; screenSizes: ScreenSize[] };\n\nexport function screenLabel(size: ScreenSize): string {\n  return size.width + 'x' + size.height;\n}\n\n/**\n * Expands `base` into one project per `screenSizes` entry of the Ralph config.\n * Each project's viewport is that screen size.\n */\nexport function ralphProjects(\n  base: RalphProject = {},\n  options: RalphProjectOptions = {},\n): RalphProject[] {\n  const { screenSizes } = loadConfigSync(\n    options,\n    options.root ?? process.cwd(),\n  ).config;\n  if (!screenSizes.length) {\n    throw new Error('The Ralph config declares no screenSizes.');\n  }\n  return screenSizes.map((screenSize) => {\n    const label = screenLabel(screenSize);\n    const ralph: ScreenMetadata = { screenSize, screenSizes };\n    return {\n      ...base,\n      name: base.name ? base.name + ' ' + label : label,\n      use: {\n        ...base.use,\n        viewport: { width: screenSize.width, height: screenSize.height },\n      },\n      metadata: { ...base.metadata, ralph },\n    };\n  });\n}\n\n/**\n * Skips a test whose `@ralph-screen:WxH` tags exclude the current project's\n * screen size. Untagged tests run at every size; other projects are untouched.\n */\nexport function applyScreenSelection(testInfo: TestInfo): void {\n  const selected = testInfo.tags\n    .filter((tag) => tag.startsWith(SCREEN_TAG_PREFIX))\n    .map((tag) => tag.slice(SCREEN_TAG_PREFIX.length));\n  const metadata = (testInfo.project.metadata as { ralph?: ScreenMetadata })\n    .ralph;\n  if (!selected.length || !metadata) {\n    return;\n  }\n  const known = metadata.screenSizes.map(screenLabel);\n  const unknown = selected.filter((label) => !known.includes(label));\n  if (unknown.length) {\n    throw new Error(\n      'Unknown Ralph screen size ' +\n        unknown.join(', ') +\n        '; the config declares ' +\n        known.join(', ') +\n        '.',\n    );\n  }\n  const current = screenLabel(metadata.screenSize);\n  testInfo.skip(\n    !selected.includes(current),\n    'Not selected for Ralph screen size ' + current + '.',\n  );\n}\n","import path from 'node:path';\n\nimport { test as base } from '@playwright/test';\nimport type {\n  PlaywrightTestArgs,\n  PlaywrightTestOptions,\n  PlaywrightWorkerArgs,\n  PlaywrightWorkerOptions,\n  TestType,\n} from '@playwright/test';\n\nimport { loadConfig, resolveMode } from './config';\nimport { Recorder, REPORTER_ENV } from './recorder';\nimport { applyScreenSelection } from './screens';\nimport type { ConfigSnapshot, Ralph, RalphOptions } from './types';\n\nexport { expect, mergeTests } from '@playwright/test';\nexport type { WebRalphConfig } from '@ralphralphai/config';\nexport {\n  createRawGraphBundle,\n  prepareArtifactUpload,\n  uploadRawGraph,\n} from './upload';\nexport type {\n  PreparedUpload,\n  UploadOptions,\n  UploadReceipt,\n  RawGraphScreenshot,\n  RawGraphBundleIndex,\n} from './upload';\nexport { MANIFEST_ATTACHMENT } from './recorder';\nexport { ralphProjects, SCREEN_TAG_PREFIX } from './screens';\nexport type { RalphProjectOptions } from './screens';\nexport type { RalphReporterOptions } from './reporter';\nexport type {\n  RawGraphManifest,\n  RawGraph,\n  RawGraphFile,\n  RawPage,\n  RawNode,\n  RecordNodeOptions,\n  ConditionsDeclaration,\n  NodeConditions,\n  RecordedTags,\n  TagConditions,\n  TagDeclaration,\n  TagValue,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n} from './types';\n\nexport type RalphFixtures = { ralph: Ralph; ralphOptions: RalphOptions };\n\ntype InternalFixtures = {\n  _ralphScreen: void;\n  _ralphRecorder: Recorder | null;\n};\ntype WorkerFixtures = { _ralphConfigs: Map<string, Promise<ConfigSnapshot>> };\n\nexport const test: TestType<\n  PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures,\n  PlaywrightWorkerArgs & PlaywrightWorkerOptions\n> = base.extend<RalphFixtures & InternalFixtures, WorkerFixtures>({\n  ralphOptions: [{}, { option: true }],\n  _ralphConfigs: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use) => {\n      await use(new Map());\n    },\n    { scope: 'worker' },\n  ],\n  _ralphScreen: [\n    // Playwright requires destructuring here to discover fixture dependencies.\n    // oxlint-disable-next-line no-empty-pattern\n    async ({}, use, testInfo) => {\n      // Screen selection chooses which flows run, so it applies in every mode.\n      applyScreenSelection(testInfo);\n      await use();\n    },\n    { auto: true },\n  ],\n  _ralphRecorder: [\n    // _ralphScreen is specified here so that the playwright treat that it is\n    // a dependency of this fixture.\n    async ({ ralphOptions, _ralphConfigs, _ralphScreen }, use, testInfo) => {\n      const mode = resolveMode(ralphOptions);\n      if (!testInfo.tags.includes('@ralph') || mode === 'off') {\n        await use(null);\n        return;\n      }\n\n      // A sharded run's blob reports are merged, and uploaded by the Ralph\n      // reporter, in `playwright merge-reports`.\n      const reported =\n        process.env[REPORTER_ENV] ||\n        testInfo.config.reporter.some(([name]) => name === 'blob');\n      if (mode === 'upload' && !reported) {\n        throw new Error(\n          \"Ralph uploads one merged graph per run from its reporter. Add ['@ralphralphai/playwright/reporter'] to `reporter` in playwright.config, or use the blob reporter and merge-reports when sharding.\",\n        );\n      }\n\n      const root = testInfo.config.configFile\n        ? path.dirname(testInfo.config.configFile)\n        : process.cwd();\n\n      const key = JSON.stringify({\n        root,\n        config: ralphOptions.config,\n        configPath: ralphOptions.configPath,\n      });\n\n      let pending = _ralphConfigs.get(key);\n      if (!pending) {\n        pending = loadConfig(ralphOptions, root);\n        _ralphConfigs.set(key, pending);\n      }\n\n      const recorder = new Recorder(\n        ralphOptions,\n        await pending,\n        testInfo,\n        mode,\n      );\n\n      try {\n        await use(recorder);\n      } finally {\n        await recorder.finish();\n      }\n    },\n    { auto: true, timeout: 30_000 },\n  ],\n  ralph: async ({ _ralphRecorder, ralphOptions }, use) => {\n    const checkOptIn = () => {\n      if (resolveMode(ralphOptions) !== 'off') {\n        throw new Error('Opt this test into Ralph with the @ralph tag.');\n      }\n    };\n\n    await use(\n      _ralphRecorder ?? {\n        recordNode: async () => {\n          checkOptIn();\n        },\n        setNodeConditions: async () => {\n          checkOptIn();\n          return async () => {};\n        },\n        waitForCapture: async () => {},\n        pause: () => {},\n        resume: () => {},\n        observe: () => {\n          checkOptIn();\n        },\n      },\n    );\n  },\n  // On the context rather than per page, so popups start out reduced too.\n  contextOptions: async ({ contextOptions, ralphOptions }, use, testInfo) => {\n    const recording =\n      testInfo.tags.includes('@ralph') && resolveMode(ralphOptions) !== 'off';\n    await use(\n      recording && ralphOptions.reduceMotion\n        ? { ...contextOptions, reducedMotion: 'reduce' }\n        : contextOptions,\n    );\n  },\n  context: async ({ context, _ralphRecorder }, use) => {\n    _ralphRecorder?.observe(context);\n    try {\n      await use(context);\n    } finally {\n      // The base context fixture closes its pages next; pending recordings still need them alive.\n      await _ralphRecorder?.stopContext(context);\n    }\n  },\n});\n"],"mappings":"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"}

package/dist/reporter.cjs

@@ -1,4 +1,4 @@
-const require_upload = require("./upload-QZreR5i6.cjs");
+const require_upload = require("./upload-BzqsXl26.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let node_fs_promises = require("node:fs/promises");
@@ -16,7 +16,6 @@ _playwright_test_package_json = require_upload.__toESM(_playwright_test_package_
 */
 var RalphReporter = class {
 	options;
-	artifactId = (0, node_crypto.randomUUID)();
 	startedAt = (/* @__PURE__ */ new Date()).toISOString();
 	config;
 	/**
@@ -41,18 +40,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 (0, node_fs_promises.readFile)(source) : source
 			})));
+			const uploading = require_upload.resolveMode(this.options) === "upload" || collected.some(({ file }) => file.mode === "upload");
+			let prepared;
+			if (uploading) {
+				try {
+					prepared = await require_upload.prepareArtifactUpload(require_upload.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 ${require_upload.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 (require_upload.resolveMode(this.options) === "upload" || collected.some(({ file }) => file.mode === "upload")) {
-				const receipt = await require_upload.uploadRawGraph(manifest, screenshots, require_upload.resolveUploadOptions(this.options));
+			if (prepared !== void 0) {
+				const receipt = await require_upload.uploadRawGraph(manifest, screenshots, require_upload.resolveUploadOptions(this.options)).catch((error) => {
+					throw new Error(`${error instanceof Error ? error.message : String(error)} The recording was saved to ${outputDir}.`, { cause: error });
+				});
 				await (0, node_fs_promises.writeFile)(node_path.default.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 ${require_upload.resultLink(receipt)}`);
 			}
 			return;
 		} catch (error) {
@@ -108,7 +124,7 @@ var RalphReporter = class {
 				},
 				runId: first.file.runId,
 				buildId: first.file.buildId,
-				artifactId: this.artifactId,
+				artifactId: (0, node_crypto.randomUUID)(),
 				shard: this.config?.shard ?? null,
 				startedAt: this.startedAt,
 				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),

package/dist/reporter.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"reporter.cjs","names":["randomUUID","REPORTER_ENV","resolveMode","readFile","uploadRawGraph","resolveUploadOptions","writeFile","path","bundleImagePath","playwrightPackage","rm","mkdir","RAW_GRAPH_BUNDLE_INDEX","MANIFEST_ATTACHMENT"],"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.cjs","names":["REPORTER_ENV","resolveMode","readFile","prepareArtifactUpload","resolveUploadOptions","resultLink","uploadRawGraph","writeFile","path","bundleImagePath","playwrightPackage","randomUUID","rm","mkdir","RAW_GRAPH_BUNDLE_INDEX","MANIFEST_ATTACHMENT"],"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/reporter.d.mts

@@ -7,7 +7,7 @@ type RalphReporterOptions = {
    * test ran in `upload` mode.
    */
   mode?: 'off' | 'local' | 'upload';
-  /** Your Ralph server. Defaults to `RALPH_API_URL`. */
+  /** Your Ralph server. Defaults to `RALPH_API_URL`, else `https://api.ralphralph.ai`. */
   apiUrl?: string;
   /** The app the recordings belong to. Defaults to `RALPH_APP_ID`. */
   appId?: string;
@@ -29,7 +29,6 @@ type RalphReporterOptions = {
  */
 declare class RalphReporter implements Reporter {
   private readonly options;
-  private readonly artifactId;
   private readonly startedAt;
   private config?;
   /**