@ralphralphai/playwright 2.9.0 → 2.11.0

package/README.md

@@ -223,6 +223,52 @@ This changes no app state. A declaration that moves the page to a different
 node records it again, and declarations merge until the URL changes. A dialog
 at the same URL is the same node unless you give it a page tag like this.
 
+When the conditions belong to the page a step navigates to, wait for it with
+`ralph.waitForNode`:
+
+```ts
+await page.getByRole("button", { name: "Upgrade" }).click();
+await ralph.waitForNode(page, "**/checkout?plan=*", /*tag to apply*/{
+  visitorTags: { plan: "pro" },
+});
+```
+
+It takes the URL as `page.waitForURL` does. Every URL change is recorded
+automatically once the page settles, which can be before the test declares
+anything. `waitForNode` gives that recording the conditions instead of
+recording the page a second time, so the URL gets one node with them, however
+the timing falls. `setNodeConditions` right after `page.waitForURL` would
+record the page twice when the automatic capture wins: once without
+conditions, once with them.
+
+### Flows
+
+Name the journey a test walks, such as sign-up or onboarding, so the graph can
+show it on its own and Ralph can report its funnel:
+
+```ts
+await page.goto("https://example.com/");
+ralph.startFlow("Sign up"); // the page on screen is the first step
+await page.getByRole("link", { name: "Sign up" }).click();
+await page.getByRole("button", { name: "Continue" }).click();
+ralph.endFlow("Sign up");
+```
+
+Every node recorded while a flow is open joins it, on every tab. A flow still
+open when the test finishes ends there. Flows can overlap, and one page can be
+in several. Tests that walk a flow differently, such as sign-up by email and by
+Google, become separate paths of the same flow.
+
+`startFlow` also returns a handle, so a helper can end what it started:
+
+```ts
+const flow = ralph.startFlow("Onboarding");
+await completeProfile(page);
+flow.end();
+```
+
+In a test without the `@ralph` tag, both calls do nothing.
+
 ### Waiting for capture
 
 To make sure a page is captured before leaving it:
@@ -457,6 +503,12 @@ and is not removed. Wrap it in an element with a role, or match the whole
 paragraph. The space ignored elements take up still moves the elements around
 them.
 
+Elements are checked against `ignoreInDiff` after the snapshot is taken. An
+element the page removes in between, like a chat widget swapping its launcher
+for an iframe while the page is captured, is dropped from the snapshot, because
+it is no longer on the page. Each capture that drops one logs
+`Ralph: N element(s) left <url> during capture ...` with the first few.
+
 ### `freezeDuringCapture` in detail
 
 Ralph installs Playwright's clock before the app loads. Before capture it

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_upload = require("./upload-8iYQZaCa.cjs");
+const require_upload = require("./upload-B7tSC0NA.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let _playwright_test = require("@playwright/test");
@@ -104,6 +104,16 @@ const test = _playwright_test.test.extend({
 				checkOptIn();
 				return async () => {};
 			},
+			waitForNode: async (page, url, conditions) => {
+				if (conditions !== void 0) checkOptIn();
+				await page.waitForURL(url, { waitUntil: "commit" });
+				return async () => {};
+			},
+			startFlow: (name) => ({
+				name,
+				end: () => {}
+			}),
+			endFlow: () => {},
 			waitForCapture: async () => {},
 			visitAllLinks: (links, options) => require_upload.visitAllLinks(links, async () => {}, options),
 			pause: () => {},

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["loadConfigSync","base","resolveMode","path","loadConfig","Recorder","visitAllLinks"],"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';\nimport { visitAllLinks } from './visit_links';\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  RawAction,\n  ActionKind,\n  ActionTarget,\n  ConditionsDeclaration,\n  NodeConditions,\n  RecordedTags,\n  RecordNodeOptions,\n  TagConditions,\n  TagDeclaration,\n  TagValue,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n  VisitAllLinksOptions,\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 (\n      { ralphOptions, _ralphConfigs, _ralphScreen, playwright },\n      use,\n      testInfo,\n    ) => {\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' || mode === 'deploy') && !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        playwright,\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 (\n        resolveMode(ralphOptions) !== 'off' &&\n        !ralphOptions.ignoreUntaggedCalls\n      ) {\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        visitAllLinks: (links, options) =>\n          visitAllLinks(links, async () => {}, options),\n        pause: () => {},\n        resume: () => {},\n        observe: async () => {\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    await _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","visitAllLinks"],"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';\nimport { visitAllLinks } from './visit_links';\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  RawAction,\n  ActionKind,\n  ActionTarget,\n  ConditionsDeclaration,\n  FlowRun,\n  FlowRunHandle,\n  NodeConditions,\n  RecordedTags,\n  RecordNodeOptions,\n  TagConditions,\n  TagDeclaration,\n  TagValue,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n  VisitAllLinksOptions,\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 (\n      { ralphOptions, _ralphConfigs, _ralphScreen, playwright },\n      use,\n      testInfo,\n    ) => {\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' || mode === 'deploy') && !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        playwright,\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 (\n        resolveMode(ralphOptions) !== 'off' &&\n        !ralphOptions.ignoreUntaggedCalls\n      ) {\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        // The wait is the test's own step, so it happens unrecorded too.\n        waitForNode: async (page, url, conditions) => {\n          if (conditions !== undefined) {\n            checkOptIn();\n          }\n          await page.waitForURL(url, { waitUntil: 'commit' });\n          return async () => {};\n        },\n        // Flows only label nodes, so a helper shared with untagged tests can\n        // declare them without opting those tests in.\n        startFlow: (name) => ({ name, end: () => {} }),\n        endFlow: () => {},\n        waitForCapture: async () => {},\n        visitAllLinks: (links, options) =>\n          visitAllLinks(links, async () => {}, options),\n        pause: () => {},\n        resume: () => {},\n        observe: async () => {\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    await _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

@@ -68,6 +68,15 @@ type RecordNodeOptions = {
    */
   edgeLabel?: string;
 };
+/** The run `startFlow` began, so a helper can end what it started. */
+type FlowRunHandle = {
+  name: string;
+  /**
+   * Ends this run, as `endFlow(name)` would. Throws when the run has already
+   * ended, even if a new run of the same name is open.
+   */
+  end(): void;
+};
 type VisitAllLinksOptions = {
   /**
    * Runs in each opened tab before it closes, e.g. to assert where it landed
@@ -89,6 +98,22 @@ type Ralph = {
    * declaration and records again.
    */
   setNodeConditions(page: Page, conditions: ConditionsDeclaration): Promise<() => Promise<void>>;
+  /**
+   * Waits for the page to reach `url`, as `page.waitForURL` does, and declares
+   * `conditions` for the node it lands on. The URL's automatic recording
+   * carries them even when it captured before this call: it is retagged
+   * rather than recorded again. Returns what `setNodeConditions` returns.
+   */
+  waitForNode(page: Page, url: Parameters<Page['waitForURL']>[0], conditions?: ConditionsDeclaration): Promise<() => Promise<void>>;
+  /**
+   * Starts a run of the named flow, such as `Sign up`. The node most recently
+   * requested in the test is its first step, and every node requested until
+   * `endFlow` joins it, on every tab. A run still open when the test finishes
+   * ends there. Throws when a run of that name is already open.
+   */
+  startFlow(name: string): FlowRunHandle;
+  /** Ends the open run of the named flow. Throws when none is open. */
+  endFlow(name: string): void;
   waitForCapture(): Promise<void>;
   /**
    * Opens each link `links` matches in its own tab, one at a time, records
@@ -235,6 +260,15 @@ type RawPage = {
   browserName?: string;
   openerPageId?: string;
 };
+/** One start-to-end span of a flow within a test. */
+type FlowRun = {
+  name: string;
+  startedAt: string;
+  endedAt: string;
+  endedBy: 'endFlow' | 'test-end';
+  /** The nodes requested while the run was open, in request order. */
+  nodeIds: string[];
+};
 /** One test's recordings. Its nodes link only to each other. */
 type RawGraph = {
   id: string;
@@ -250,6 +284,8 @@ type RawGraph = {
   finishedAt: string;
   pages: RawPage[];
   nodes: RawNode[];
+  /** Absent when the test declared no flow. */
+  flowRuns?: FlowRun[];
   /** The test passed and every node was recorded with stable geometry. */
   complete: boolean;
 };
@@ -380,5 +416,5 @@ type RalphFixtures = {
 };
 declare const test: TestType<PlaywrightTestArgs & PlaywrightTestOptions & RalphFixtures, PlaywrightWorkerArgs & PlaywrightWorkerOptions>;
 //#endregion
-export { type ActionKind, type ActionTarget, type ConditionsDeclaration, type ConfigSnapshot, MANIFEST_ATTACHMENT, type NodeConditions, type PageLayout, type PreparedUpload, type Ralph, RalphFixtures, type RalphOptions, type RalphProjectOptions, type RalphReporterOptions, type RawAction, 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 VisitAllLinksOptions, type WebRalphConfig, createRawGraphBundle, expect, mergeTests, prepareArtifactUpload, ralphProjects, test, uploadRawGraph };
+export { type ActionKind, type ActionTarget, type ConditionsDeclaration, type ConfigSnapshot, type FlowRun, type FlowRunHandle, MANIFEST_ATTACHMENT, type NodeConditions, type PageLayout, type PreparedUpload, type Ralph, RalphFixtures, type RalphOptions, type RalphProjectOptions, type RalphReporterOptions, type RawAction, 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 VisitAllLinksOptions, type WebRalphConfig, createRawGraphBundle, expect, mergeTests, prepareArtifactUpload, ralphProjects, test, uploadRawGraph };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as resolveMode, a as prepareArtifactUpload, f as Recorder, g as loadConfigSync, h as loadConfig, i as createRawGraphBundle, l as uploadRawGraph, p as visitAllLinks, u as MANIFEST_ATTACHMENT } from "./upload-DKeVoDQ2.mjs";
+import { _ as resolveMode, a as prepareArtifactUpload, f as Recorder, g as loadConfigSync, h as loadConfig, i as createRawGraphBundle, l as uploadRawGraph, p as visitAllLinks, u as MANIFEST_ATTACHMENT } from "./upload-C_KLRH9y.mjs";
 import path from "node:path";
 import { expect, mergeTests, test as test$1 } from "@playwright/test";
 //#region src/screens.ts
@@ -102,6 +102,16 @@ const test = test$1.extend({
 				checkOptIn();
 				return async () => {};
 			},
+			waitForNode: async (page, url, conditions) => {
+				if (conditions !== void 0) checkOptIn();
+				await page.waitForURL(url, { waitUntil: "commit" });
+				return async () => {};
+			},
+			startFlow: (name) => ({
+				name,
+				end: () => {}
+			}),
+			endFlow: () => {},
 			waitForCapture: async () => {},
 			visitAllLinks: (links, options) => visitAllLinks(links, async () => {}, options),
 			pause: () => {},

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';\nimport { visitAllLinks } from './visit_links';\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  RawAction,\n  ActionKind,\n  ActionTarget,\n  ConditionsDeclaration,\n  NodeConditions,\n  RecordedTags,\n  RecordNodeOptions,\n  TagConditions,\n  TagDeclaration,\n  TagValue,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n  VisitAllLinksOptions,\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 (\n      { ralphOptions, _ralphConfigs, _ralphScreen, playwright },\n      use,\n      testInfo,\n    ) => {\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' || mode === 'deploy') && !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        playwright,\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 (\n        resolveMode(ralphOptions) !== 'off' &&\n        !ralphOptions.ignoreUntaggedCalls\n      ) {\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        visitAllLinks: (links, options) =>\n          visitAllLinks(links, async () => {}, options),\n        pause: () => {},\n        resume: () => {},\n        observe: async () => {\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    await _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;;;ACxBA,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,OACE,EAAE,cAAc,eAAe,cAAc,cAC7C,KACA,aACG;EACH,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,KAAK,SAAS,YAAY,SAAS,aAAa,CAAC,UAC/C,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,MACA,UACF;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,IACE,YAAY,YAAY,MAAM,SAC9B,CAAC,aAAa,qBAEd,MAAM,IAAI,MAAM,+CAA+C;EAEnE;EAEA,MAAM,IACJ,kBAAkB;GAChB,YAAY,YAAY;IACtB,WAAW;GACb;GACA,mBAAmB,YAAY;IAC7B,WAAW;IACX,OAAO,YAAY,CAAC;GACtB;GACA,gBAAgB,YAAY,CAAC;GAC7B,gBAAgB,OAAO,YACrB,cAAc,OAAO,YAAY,CAAC,GAAG,OAAO;GAC9C,aAAa,CAAC;GACd,cAAc,CAAC;GACf,SAAS,YAAY;IACnB,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,MAAM,gBAAgB,QAAQ,OAAO;EACrC,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';\nimport { visitAllLinks } from './visit_links';\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  RawAction,\n  ActionKind,\n  ActionTarget,\n  ConditionsDeclaration,\n  FlowRun,\n  FlowRunHandle,\n  NodeConditions,\n  RecordedTags,\n  RecordNodeOptions,\n  TagConditions,\n  TagDeclaration,\n  TagValue,\n  ConfigSnapshot,\n  PageLayout,\n  Ralph,\n  RalphOptions,\n  TrackedElement,\n  VisitAllLinksOptions,\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 (\n      { ralphOptions, _ralphConfigs, _ralphScreen, playwright },\n      use,\n      testInfo,\n    ) => {\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' || mode === 'deploy') && !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        playwright,\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 (\n        resolveMode(ralphOptions) !== 'off' &&\n        !ralphOptions.ignoreUntaggedCalls\n      ) {\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        // The wait is the test's own step, so it happens unrecorded too.\n        waitForNode: async (page, url, conditions) => {\n          if (conditions !== undefined) {\n            checkOptIn();\n          }\n          await page.waitForURL(url, { waitUntil: 'commit' });\n          return async () => {};\n        },\n        // Flows only label nodes, so a helper shared with untagged tests can\n        // declare them without opting those tests in.\n        startFlow: (name) => ({ name, end: () => {} }),\n        endFlow: () => {},\n        waitForCapture: async () => {},\n        visitAllLinks: (links, options) =>\n          visitAllLinks(links, async () => {}, options),\n        pause: () => {},\n        resume: () => {},\n        observe: async () => {\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    await _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-8iYQZaCa.cjs");
+const require_upload = require("./upload-B7tSC0NA.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let node_fs_promises = require("node:fs/promises");

package/dist/reporter.mjs

@@ -1,4 +1,4 @@
-import { _ as resolveMode, a as prepareArtifactUpload, c as resultLink, d as REPORTER_ENV, l as uploadRawGraph, m as version, n as bundleImagePath, o as registerDeployment, r as bundleSnapshotPath, s as resolveUploadOptions, t as RAW_GRAPH_BUNDLE_INDEX, u as MANIFEST_ATTACHMENT } from "./upload-DKeVoDQ2.mjs";
+import { _ as resolveMode, a as prepareArtifactUpload, c as resultLink, d as REPORTER_ENV, l as uploadRawGraph, m as version, n as bundleImagePath, o as registerDeployment, r as bundleSnapshotPath, s as resolveUploadOptions, t as RAW_GRAPH_BUNDLE_INDEX, u as MANIFEST_ATTACHMENT } from "./upload-C_KLRH9y.mjs";
 import path from "node:path";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { randomUUID } from "node:crypto";

package/dist/{upload-8iYQZaCa.cjs → upload-B7tSC0NA.cjs}

@@ -70,7 +70,7 @@ function snapshot(value) {
 }
 //#endregion
 //#region package.json
-var version = "2.9.0";
+var version = "2.11.0";
 //#endregion
 //#region src/actions.ts
 const BINDING = "__ralphAction";
@@ -689,7 +689,12 @@ async function captureAriaSnapshot(page, { viewport, scroll }, ignore = []) {
 	});
 	const ignoreSelector = ignore.length === 0 ? void 0 : ignore.join(", ");
 	const facts = /* @__PURE__ */ new Map();
-	const normalized = (await Promise.all(visible.map((node) => readTree(page, node, ignoreSelector, facts)))).filter((node) => node !== void 0);
+	const detached = [];
+	const normalized = (await Promise.all(visible.map((node) => readTree(page, node, ignoreSelector, facts, detached)))).filter((node) => node !== void 0);
+	if (detached.length > 0) {
+		const listed = detached.slice(0, 5).map(({ role, name }) => name ? `${role} "${name}"` : role).join(", ");
+		console.warn(`Ralph: ${detached.length} element(s) left ${page.url()} during capture and were dropped from its aria snapshot: ${listed}${detached.length > 5 ? ", ..." : ""}`);
+	}
 	const described = await Promise.all(normalized.map((node) => describe(page, node, {}, false, facts)));
 	const json = Buffer.from(JSON.stringify(fillMissingRefs(described)));
 	return json.byteLength > 4194304 ? void 0 : json;
@@ -904,8 +909,11 @@ function fillMissingRefs(nodes) {
 	return nodes.map(fill);
 }
 async function readElement(page, ref, isImage, ignoreSelector) {
+	const locator = page.locator(`aria-ref=${ref}`);
+	const isDetached = async () => await locator.count().catch(() => 0) === 0;
 	try {
-		return await page.locator(`aria-ref=${ref}`).evaluate((element, { properties, isImage, dynamicAttribute, ignoreSelector }) => {
+		if (await isDetached()) return "detached";
+		return await locator.evaluate((element, { properties, isImage, dynamicAttribute, ignoreSelector }) => {
 			const computed = getComputedStyle(element);
 			const typed = "computedStyleMap" in element ? element.computedStyleMap() : void 0;
 			const style = Object.fromEntries(properties.map((property) => [property, property.startsWith("margin-") && typed?.get(property)?.toString() === "auto" ? "auto" : computed.getPropertyValue(property)]));
@@ -950,7 +958,7 @@ async function readElement(page, ref, isImage, ignoreSelector) {
 			ignoreSelector
 		}, { timeout: ELEMENT_LOOKUP_TIMEOUT_MS });
 	} catch {
-		return;
+		return await isDetached() ? "detached" : void 0;
 	}
 }
 async function hashImage(page, image) {
@@ -969,12 +977,16 @@ function distinctStyle(style, inherited) {
 	});
 	return distinct.length === 0 ? void 0 : Object.fromEntries(distinct);
 }
-async function readTree(page, child, ignoreSelector, factsByRef) {
+async function readTree(page, child, ignoreSelector, factsByRef, detached) {
 	if (typeof child === "string") return child;
 	const facts = child.ref === void 0 ? void 0 : await readElement(page, child.ref, child.role === "img", ignoreSelector);
+	if (facts === "detached") {
+		detached.push(child);
+		return;
+	}
 	if (facts?.ignored) return;
 	if (child.ref !== void 0 && facts !== void 0) factsByRef.set(child.ref, facts);
-	const children = child.children === void 0 ? void 0 : (await Promise.all(child.children.map((grandchild) => readTree(page, grandchild, ignoreSelector, factsByRef)))).filter((grandchild) => grandchild !== void 0);
+	const children = child.children === void 0 ? void 0 : (await Promise.all(child.children.map((grandchild) => readTree(page, grandchild, ignoreSelector, factsByRef, detached)))).filter((grandchild) => grandchild !== void 0);
 	if (children !== void 0) {
 		if (children.length === 0 && (child.ref === void 0 || child.role === "generic" && !child.name && (child.children?.length ?? 0) > 0)) return;
 		const only = loneChild(child, children);
@@ -1229,6 +1241,71 @@ function nodeKey(conditions) {
 	return JSON.stringify([sorted(conditions.visitorTags), sorted(conditions.pageTags)]);
 }
 //#endregion
+//#region src/flows.ts
+const MAX_FLOW_NAME_LENGTH = 64;
+var FlowRuns = class {
+	runs = [];
+	retainedNodeIds = /* @__PURE__ */ new Map();
+	/** `currentNodeId` is the node on screen, the run's first step. */
+	start(name, currentNodeId) {
+		const flowName = flowNameOf(name);
+		if (this.openRun(flowName)) throw new Error(`Ralph flow "${flowName}" is already open.`);
+		const run = {
+			name: flowName,
+			startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+			nodeIds: currentNodeId === void 0 ? [] : [currentNodeId]
+		};
+		this.runs.push(run);
+		return {
+			name: flowName,
+			end: () => {
+				if (run.ended) throw new Error(`This run of Ralph flow "${flowName}" has already ended.`);
+				endRun(run, "endFlow");
+			}
+		};
+	}
+	end(name) {
+		const flowName = flowNameOf(name);
+		const run = this.openRun(flowName);
+		if (!run) throw new Error(`Ralph flow "${flowName}" is not open.`);
+		endRun(run, "endFlow");
+	}
+	nodeRequested(nodeId) {
+		for (const run of this.runs) if (!run.ended) run.nodeIds.push(nodeId);
+	}
+	/** A retake or unchanged condition update kept an existing node's ID. */
+	nodeReused(requestId, retainedNodeId) {
+		this.retainedNodeIds.set(requestId, retainedNodeId);
+	}
+	/** Ends the runs still open, as the test has, and returns every run. */
+	finish() {
+		return this.runs.map((run) => {
+			if (!run.ended) endRun(run, "test-end");
+			return {
+				name: run.name,
+				startedAt: run.startedAt,
+				endedAt: run.ended.at,
+				endedBy: run.ended.by,
+				nodeIds: run.nodeIds.map((nodeId) => this.retainedNodeIds.get(nodeId) ?? nodeId)
+			};
+		});
+	}
+	openRun(name) {
+		return this.runs.find((run) => run.name === name && !run.ended);
+	}
+};
+function endRun(run, by) {
+	run.ended = {
+		at: (/* @__PURE__ */ new Date()).toISOString(),
+		by
+	};
+}
+function flowNameOf(name) {
+	const trimmed = name.trim();
+	if (!trimmed || trimmed.length > MAX_FLOW_NAME_LENGTH) throw new Error(`A Ralph flow name must be 1 to ${MAX_FLOW_NAME_LENGTH} characters.`);
+	return trimmed;
+}
+//#endregion
 //#region src/image.ts
 /**
 * Matches the crawler's full-page screenshots: lossless measured larger than this
@@ -1455,6 +1532,7 @@ var Recorder = class {
 	*/
 	order = 0;
 	requestOrder = /* @__PURE__ */ new Map();
+	flows = new FlowRuns();
 	actions = new ActionLog(() => ++this.order, () => !this.paused && !this.closed, (page) => this.pages.get(page)?.info.pageId, () => [...this.pages.values()].filter((state) => !state.page.isClosed()).map((state) => state.info.pageId));
 	constructor(options, config, testInfo, mode, playwright) {
 		this.options = options;
@@ -1499,9 +1577,26 @@ var Recorder = class {
 		const key = Symbol();
 		state.declared.set(key, declaredConditions(declaration));
 		await this.recordConditionChange(state);
-		return async () => {
-			if (state.declared.delete(key)) await this.recordConditionChange(state);
-		};
+		return this.undoDeclaration(state, key);
+	}
+	async waitForNode(page, url, declaration = {}) {
+		await this.observe(page.context());
+		const state = this.pages.get(page);
+		if (!state) throw new Error("Cannot wait on a closed browser page.");
+		await page.waitForURL(url, { waitUntil: "commit" });
+		this.urlChanged(state);
+		const generation = state.generation;
+		const key = Symbol();
+		state.declared.set(key, declaredConditions(declaration));
+		await state.tail;
+		if (!this.paused && state.generation === generation && !this.retagVisitNode(state)) await this.recordConditionChange(state);
+		return this.undoDeclaration(state, key);
+	}
+	startFlow(name) {
+		return this.flows.start(name, this.lastRequestedNodeId);
+	}
+	endFlow(name) {
+		this.flows.end(name);
 	}
 	/**
 	* Stops requesting nodes, automatic or explicit, until `resume`. Recordings
@@ -1546,7 +1641,7 @@ var Recorder = class {
 		linkPreviousNodes(nodes, (pageId) => this.pageInfo(pageId)?.openerPageId, (nodeId) => this.requestedAtMs.get(nodeId) ?? 0, (pageId) => this.pageState(pageId)?.pauseAnchor);
 		this.attachActions(nodes);
 		const failures = nodes.filter((item) => item.status === "uncaptured" && item.reason === "error");
-		await this.writeRawGraph(this.buildRawGraph(nodes, failures.length));
+		await this.writeRawGraph(this.buildRawGraph(nodes, this.flows.finish(), failures.length));
 		const mismatched = nodes.filter((item) => item.tagMismatches?.length);
 		if (this.options.strictNodeTags && mismatched.length && this.testInfo.status === "passed") throw new Error("Ralph: the app reported tags outside what the test declared, on " + mismatched.map((item) => item.url + " (" + item.tagMismatches.join(", ") + ")").join("; ") + ".");
 		if (failures.length && this.testInfo.status === "passed") throw new Error("Ralph could not record " + failures.length + " page state(s). See the ralph-raw-graph attachment.");
@@ -1590,11 +1685,42 @@ var Recorder = class {
 		state.generation++;
 		state.lastUrl = url;
 		state.declared.clear();
+		state.visitNodeId = void 0;
 		if (!this.paused && isHttpUrl(url)) this.enqueueCreateNodeRequest(state, "url-change").catch(() => void 0);
 	}
 	async recordConditionChange(state) {
 		if (!this.paused && isHttpUrl(state.page.url())) await this.enqueueCreateNodeRequest(state, "condition-change");
 	}
+	undoDeclaration(state, key) {
+		return async () => {
+			if (state.declared.delete(key)) await this.recordConditionChange(state);
+		};
+	}
+	/**
+	* Gives the URL's automatic capture the conditions declared since. They
+	* describe the visit from its start, and declarations change no app state,
+	* so the screenshot already taken stands for the declared node.
+	*/
+	retagVisitNode(state) {
+		const nodeId = state.visitNodeId;
+		if (!nodeId || state.lastRecorded?.nodeId !== nodeId) return false;
+		const index = this.nodes.findIndex((item) => item.nodeId === nodeId);
+		const visit = this.nodes[index];
+		if (visit?.status !== "recorded") return false;
+		const conditions = this.declaredConditions(state);
+		const mismatches = mismatchesOf(conditions, visit.reportedTags);
+		const { conditions: _conditions, tagMismatches: _tagMismatches, ...rest } = visit;
+		this.nodes[index] = {
+			...rest,
+			...withConditions(conditions),
+			...mismatches.length > 0 ? { tagMismatches: mismatches } : {}
+		};
+		state.lastRecorded = {
+			...state.lastRecorded,
+			node: nodeKey(conditions)
+		};
+		return true;
+	}
 	declaredConditions(state) {
 		return mergeConditions([...state.declared.values()]);
 	}
@@ -1619,6 +1745,7 @@ var Recorder = class {
 		this.requestedAtMs.set(request.nodeId, Date.now());
 		this.requestOrder.set(request.nodeId, ++this.order);
 		this.lastRequestedNodeId = request.nodeId;
+		this.flows.nodeRequested(request.nodeId);
 		const generation = state.generation;
 		const task = state.tail.then(() => this.createNode(state, generation, request));
 		state.tail = task.catch(() => void 0);
@@ -1651,7 +1778,10 @@ var Recorder = class {
 			const mismatches = mismatchesOf(conditions, reported);
 			const node = nodeKey(conditions);
 			const sameNode = state.lastRecorded?.url === request.url && state.lastRecorded.node === node;
-			if (sameNode && request.trigger !== "explicit") return;
+			if (sameNode && request.trigger !== "explicit") {
+				this.flows.nodeReused(request.nodeId, state.lastRecorded.nodeId);
+				return;
+			}
 			if (reported === void 0 && compactConditions(conditions) !== void 0 && !warnedNoTracker) {
 				warnedNoTracker = true;
 				console.warn("Ralph: this page runs no tracker, so the node conditions the test declares cannot be checked against the tags the app reports. Production events must carry the same tags, or these nodes will match no visitors.");
@@ -1698,6 +1828,7 @@ var Recorder = class {
 					node,
 					nodeId: request.nodeId
 				};
+				if (request.trigger === "url-change" && state.generation === generation) state.visitNodeId = request.nodeId;
 			} else {
 				const { nodeId, sequence, requestedAt, name, edgeLabel } = this.nodes[retaken];
 				this.nodes[retaken] = {
@@ -1708,6 +1839,7 @@ var Recorder = class {
 					sequence,
 					requestedAt
 				};
+				this.flows.nodeReused(request.nodeId, nodeId);
 			}
 		} catch (error) {
 			this.nodes.push({
@@ -1787,7 +1919,7 @@ var Recorder = class {
 	pageInfo(pageId) {
 		return this.pageState(pageId)?.info;
 	}
-	buildRawGraph(nodes, failureCount) {
+	buildRawGraph(nodes, flowRuns, failureCount) {
 		const { testInfo } = this;
 		const testPassed = testInfo.status === "passed";
 		return {
@@ -1815,6 +1947,7 @@ var Recorder = class {
 				finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
 				pages: [...this.pages.values()].map((state) => state.info),
 				nodes,
+				...flowRuns.length ? { flowRuns } : {},
 				complete: testPassed && nodes.length > 0 && nodes.every((item) => item.status === "recorded" && item.geometryStable)
 			}
 		};
@@ -2214,4 +2347,4 @@ Object.defineProperty(exports, "visitAllLinks", {
 	}
 });
 
-//# sourceMappingURL=upload-8iYQZaCa.cjs.map
+//# sourceMappingURL=upload-B7tSC0NA.cjs.map