@ralphralphai/playwright 2.8.0 → 2.9.0

package/README.md

@@ -3,19 +3,26 @@
 Turn your Playwright tests into a map of your app for
 [Ralph](https://ralphralph.ai).
 
-Tag a test with `@ralph` and every page it visits is recorded: a full-page
-screenshot, the URL, and the position of every element with a `data-track-id`.
+Every page an `@ralph`-tagged test visits becomes a **node** in a graph: a
+full-page screenshot, the URL, and the position of every element with a
+`data-track-id`. The actions the test takes between two pages (clicks, fills,
+navigation) become the **edge** between them. Ralph matches your production
+tracker events against this graph.
+
 Untagged tests are untouched, and recording is off unless you turn it on.
 
 ## Install
 
-Requires Node.js 20.19+ and Playwright Test 1.63+ (major version 1).
+Requires Node.js 20.19+ and Playwright Test 1.63+.
 
 ```sh
 pnpm add -D @ralphralphai/playwright @playwright/test
 pnpm exec playwright install chromium
 ```
 
+**IMPORTANT** It is currently only tested on chromium. The Firefox support will
+be added soon.
+
 ## Quick start
 
 **1. Add a `ralph.jsonc`** next to `playwright.config.ts`:
@@ -30,7 +37,15 @@ pnpm exec playwright install chromium
 See [`@ralphralphai/config`](https://www.npmjs.com/package/@ralphralphai/config)
 for all fields.
 
-**2. Import `test` from this package and tag tests with `@ralph`:**
+**2. Tag your elements** with `data-track-id`, using the same ids as your
+[`@ralphralphai/tracker`](https://www.npmjs.com/package/@ralphralphai/tracker)
+setup:
+
+```html
+<button data-track-id="add-to-cart">Add to cart</button>
+```
+
+**3. Import `test` from this package and tag tests with `@ralph`:**
 
 ```ts
 import { test, expect } from "@ralphralphai/playwright";
@@ -42,7 +57,7 @@ test("checkout", { tag: "@ralph" }, async ({ page }) => {
 });
 ```
 
-**3. Add the Ralph reporter** in `playwright.config.ts`:
+**4. Add the Ralph reporter** in `playwright.config.ts`:
 
 ```ts
 export default defineConfig({
@@ -50,25 +65,92 @@ export default defineConfig({
 });
 ```
 
-**4. Run with your upload key** (see [Uploading to Ralph](#uploading-to-ralph)):
+**5. Run with an upload key.** Create one in the project dashboard, then:
 
 ```sh
 RALPH_UPLOAD_KEY=… RALPH_APP_ID=… pnpm exec playwright test
 ```
 
-## Tag your elements
+This runs in `upload` mode, the default whenever `RALPH_UPLOAD_KEY` is set. The
+reporter sends the recorded run to Ralph, which builds the graph from it. An
+upload is a preview: it isn't tied to any release, so production tracker
+events aren't matched against it. Use it to check the graph while you write
+tests, then [deploy](#deploying-a-release) once it looks right.
 
-Add `data-track-id` to elements, using the same ids as your
-[`@ralphralphai/tracker`](https://www.npmjs.com/package/@ralphralphai/tracker)
-setup:
+The reporter prints a link before the upload starts. Open it to watch the run
+upload, get processed, and then browse the graph:
 
-```html
-<button data-track-id="add-to-cart">Add to cart</button>
 ```
+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-…
+```
+
+`RALPH_UPLOAD_KEY` must be an environment variable. `RALPH_APP_ID` can be
+set as the reporter's `appId` option.
+
+## Deploying a release
+
+Once the previewed graph looks right, upload it as the graph of the build you
+deploy. Ralph then matches that build's tracker events to it. Set
+`RALPH_MODE=deploy` and `RALPH_BUILD_ID`, usually the commit SHA:
+
+```sh
+RALPH_MODE=deploy RALPH_BUILD_ID="$COMMIT_SHA" \
+  RALPH_UPLOAD_KEY=… RALPH_APP_ID=… pnpm exec playwright test
+```
+
+If the build goes live before the test run finishes, register it first so the
+tracker picks up its config right away:
+
+```sh
+curl --fail-with-body -X POST https://api.ralphralph.ai/api/upload/deployment/register \
+  -H "Authorization: Bearer $RALPH_UPLOAD_KEY" -H 'content-type: application/json' \
+  -d "{\"externalAppId\":\"$RALPH_APP_ID\",\"buildId\":\"$COMMIT_SHA\",
+       \"reserveArtifact\":false,\"config\":$(cat ralph.json)}"
+```
+
+`ralph.json` is your `ralph.jsonc` as plain JSON, without comments or trailing
+commas. The test run that follows registers the same build again and uploads
+into it.
+
+## Diffing deployments
+
+Along with the screenshot, each node records an ARIA snapshot of the page: the
+accessibility tree, each element's box, its distinctive styles (fonts, colors,
+spacing, borders), and a hash of each image. Ralph diffs a node's snapshot
+against the same node in the previous deployment to show what changed.
+
+Hidden elements, elements clipped by an ancestor's overflow, and tiny iframes
+such as tracking pixels are left out, so they never show up as changes.
+
+Two tools keep content that changes on its own from showing up as a change:
 
-## Recording pages
+- **`data-ralph-dynamic`** marks a subtree whose content the server generates
+  on every request, such as a blog listing or a price quote. The diff compares
+  only its structure and styles, not its text, links, or images:
 
-### Automatically
+  ```html
+  <div>
+    <article>
+      <p data-ralph-dynamic>Posted 3 days ago</p>
+    </article>
+  </div>
+  ```
+
+- **`ignoreInDiff`** removes a subtree from the snapshot entirely, for parts
+  that aren't yours to diff, such as ads, chat widgets, or live counters.
+  Matched elements still appear in the screenshot:
+
+  ```ts
+  ralphOptions: {
+    ignoreInDiff: ['.ad-slot', '#intercom-container', 'live-clock'],
+  },
+  ```
+
+Use `data-ralph-dynamic` when you still want layout and style changes in that
+area reported, and `ignoreInDiff` when you don't.
+
+## How recording works
 
 A page is recorded whenever the URL changes in any tab of the test: page loads,
 redirects (the final page), SPA route changes, query and hash changes, and new
@@ -86,56 +168,25 @@ ralphOptions: {
 },
 ```
 
-Screenshots are WebP. A page taller or wider than 16,383 px, the most WebP can
-hold, is recorded up to that size, and what lies beyond it has no screenshot.
+Recordings run in the background. A page the test leaves before its screenshot
+is done stays in the graph as `uncaptured`, with no screenshot. See
+[`waitForCapture`](#waiting-for-capture).
 
-CSS animations and transitions are frozen for the screenshot. For animations
-driven from JavaScript, set `reduceMotion` if your app honors
-`prefers-reduced-motion`.
+Each action between two nodes is stored on the edge with the element it landed
+on (role, name, `data-track-id`) and where that element was on the earlier
+screenshot. Ralph shows it as, e.g., `Click button "Checkout"`. Recorded
+actions are clicks, hovers, fills, key presses, selects, uploads, drags, and
+`goto` / back / forward / reload. Text typed into password or one-time-code
+fields is never recorded.
 
-To hold timers and animations at the same position across the screenshot,
-tracked-element geometry, and ARIA snapshot, enable:
+## Test API
 
-```ts
-ralphOptions: {
-  freezeDuringCapture: true,
-},
-```
+The `ralph` fixture controls recording from inside a test.
 
-Ralph installs Playwright's clock before the app loads. Before capture it
-finishes running finite CSS transitions, CSS animations, and Web Animations,
-and watches DOM changes in the page, its frames, and open shadow roots. Timers
-and animation frames keep running while it waits for 150 ms without changes,
-so JavaScript-driven animations can finish without adding callbacks or markers
-to your app. Animations started by completion callbacks are checked again.
+### Recording once the page is ready
 
-This extra settling wait is capped at 1.5 seconds, or half the remaining
-`recordTimeoutMs` budget, whichever is smaller. Looping browser animations are
-temporarily paused while settling. Then timers and all remaining browser
-animations pause during capture and resume afterward, including on failure.
-Animations already paused by the app stay paused; finished animations stay
-finished.
-
-The DOM quiet check is a heuristic, not a guarantee that every animation has
-ended. Long-running JavaScript animations can be captured midway when the
-budget expires. Future delayed work and drawing inside canvas or WebGL aren't
-detected by this check.
-
-This option defaults to `false`. The clock replaces the native timer APIs for
-the lifetime of the context, so don't combine it with manual `page.clock` or
-`context.clock` control. Playwright requires a future pause time: Ralph uses
-the page's current time plus 100 ms, which advances the clock and can fire due
-callbacks once before freezing. Time resumes from there without catching up
-through the capture duration. All tabs in a context share the clock, so their
-timers pause together and their captures run one at a time. Network responses,
-workers, and media playback are not frozen, so unrelated updates can still
-change the page.
-
-### Explicitly, once the page is ready
-
-A capture taken when the URL or the declared conditions change can catch the
-page mid-transition. Call `ralph.recordNode` after your assertions to retake
-the screenshot of the node just recorded:
+An automatic capture can catch the page mid-transition. Call `ralph.recordNode`
+after your assertions to retake the screenshot of the current node:
 
 ```ts
 test("cart", { tag: "@ralph" }, async ({ page, ralph }) => {
@@ -146,19 +197,18 @@ test("cart", { tag: "@ralph" }, async ({ page, ralph }) => {
 });
 ```
 
-Pass a `name` to label the node in the graph, e.g.
-`ralph.recordNode(page, { name: 'Cart' })`. A later call without one keeps it.
+Each call replaces the screenshot, so the last one wins. Options:
 
-Each call replaces the screenshot, so the last one wins. A dialog at the same
-URL is the same node, so recording it would replace the page's screenshot: give
-it its own node by declaring a page tag for it (below), since that is what
-production events carry.
+- `name` labels the node in the graph: `ralph.recordNode(page, { name: 'Cart' })`.
+- `edgeLabel` describes the step into it in your own words:
+  `ralph.recordNode(page, { name: 'Done', edgeLabel: 'Sign in' })`.
+
+A later call without either one keeps the earlier value.
 
-### Node conditions, for pages that render differently at one URL
+### One URL, several renderings
 
 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:
+page state (an open dialog), declare what each screenshot stands for:
 
 ```ts
 await page.goto("https://example.com/checkout");
@@ -169,18 +219,13 @@ const undo = await ralph.setNodeConditions(page, {
 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.
+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.
 
 ### Waiting for capture
 
-Recordings run in the background. If the test leaves a page before its
-screenshot is done, the page is `uncaptured`: it's in the graph without a
-screenshot. To make sure a page is captured before leaving it:
+To make sure a page is captured before leaving it:
 
 ```ts
 await page.goto("https://example.com/pricing");
@@ -204,9 +249,7 @@ await ralph.visitAllLinks(page.locator("a.article:visible"), {
 ```
 
 Each link opens in its own tab, is recorded, and closes before the next one
-opens. The edge into each target carries the click. Every match must be a link
-(`<a href>`): a button that navigates by script can't open in a new tab, so the
-call throws before opening any.
+opens. Every match must be an `<a href>`, or the call throws before opening any.
 
 ### Pausing capture
 
@@ -221,8 +264,8 @@ ralph.resume();
 await page.goto("https://example.com/d"); // recorded, linked from /a
 ```
 
-This works across tabs. While paused, `recordNode` does nothing. `resume` does
-not record the current page.
+This works across tabs. While paused, `recordNode` does nothing and actions are
+left off the edge. `resume` does not record the current page.
 
 ### Browser contexts you create yourself
 
@@ -234,131 +277,36 @@ await ralph.waitForCapture();
 await context.close();
 ```
 
-With `freezeDuringCapture`, await `ralph.observe(context)` before creating or
-navigating any pages, so no app scripts schedule native timers first. A context
-with an already navigated page cannot be enrolled with this option enabled.
-
-### What happened between two nodes
-
-The Playwright actions a test takes on the way from one node to the next are
-recorded on the edge between them: clicks, hovers, fills, key presses,
-selects, uploads, drags, and `goto` / back / forward / reload. Each one keeps
-the element it landed on (its role, name, and `data-track-id`) and where that
-element was on the earlier node's screenshot, which Ralph shows as, e.g.,
-`Click button "Checkout"`.
-
-What was typed into a password or one-time-code field is never recorded.
-Actions taken while recording is paused are left out.
-
-Pass an `edgeLabel` to describe the step in your own words, e.g.
-`ralph.recordNode(page, { name: 'Done', edgeLabel: 'Sign in' })`. A later call
-without one keeps it.
+## Stable captures
 
-### Excluding elements from snapshots
+For apps with animations or live content:
 
-For parts of the page that change on their own, such as ads, chat widgets or
-live counters, list CSS selectors in `ignoreInDiff`:
-
-```ts
-ralphOptions: {
-  ignoreInDiff: ['.ad-slot', '#intercom-container', 'live-clock'],
-},
-```
-
-Matched elements and their descendants, including content in open shadow roots
-and slots, are left out of the ARIA snapshot used for diffing. They still appear
-in the screenshot, and the space they take up still moves the elements around
-them. Text that sits inline in a larger element, like a bare `<span>` in a
-paragraph, belongs to that element's text and is not removed. Wrap it in an
-element with a role, or match the whole paragraph.
-
-### When recording fails
-
-- A failed `recordNode` call rejects.
-- A failed automatic recording fails the test at the end.
-- Pages left before capture, and pages whose layout moved during the
-  screenshot, don't fail the test.
+- `reduceMotion: true` emulates `prefers-reduced-motion: reduce`. CSS
+  animations and transitions are always frozen for the screenshot.
+- `freezeDuringCapture: true` lets the page settle, then freezes timers and
+  animations so the screenshot, element positions, and ARIA snapshot match.
+  See [Troubleshooting](#freezeduringcapture-in-detail) before enabling it.
+- `data-ralph-dynamic` and `ignoreInDiff` keep content that changes on its own
+  out of the diff. See [Diffing deployments](#diffing-deployments).
 
 ## Modes
 
 Set with `RALPH_MODE` or the `mode` option:
 
-| 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. |
+| 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 as a preview graph not tied to a release. Default when `RALPH_UPLOAD_KEY` is set. |
+| `deploy` | Like `upload`, but the run is uploaded as its build's graph. See [Deploying a release](#deploying-a-release).                                   |
 
-Untagged tests are never recorded. In `upload` mode, calling
+The reporter uploads the run when any test ran in `upload` or `deploy` mode,
+and as its build's graph when any ran in `deploy` mode.
+
+Untagged tests are never recorded. In `upload` and `deploy` modes, calling
 `ralph.recordNode`, `ralph.setNodeConditions`, or `ralph.observe` in an
 untagged test throws. Set `ignoreUntaggedCalls` to make them do nothing
 instead, for helpers shared between tagged and untagged tests.
 
-## Uploading to Ralph
-
-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_APP_ID`     | The app the recordings belong to. |
-
-3. Run:
-
-   ```sh
-   RALPH_MODE=upload pnpm exec playwright test
-   ```
-
-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: 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-…
-```
-
-### Sharded runs
-
-Use the `blob` reporter on each shard, then merge with the Ralph reporter:
-
-```sh
-# Each shard (no upload credentials needed):
-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_APP_ID=… \
-  pnpm exec playwright merge-reports --reporter @ralphralphai/playwright/reporter ./all-blob-reports
-```
-
-### Deployments
-
-When you deploy, upload the run as the graph of the deployed build. Ralph then
-matches tracker events from that build to it.
-
-Set `RALPH_DEPLOY=1` and `RALPH_BUILD_ID` to the build's id, usually the commit
-SHA:
-
-```sh
-RALPH_MODE=upload RALPH_DEPLOY=1 RALPH_BUILD_ID="$COMMIT_SHA" \
-  RALPH_UPLOAD_KEY=… RALPH_APP_ID=… pnpm exec playwright test
-```
-
-If the build goes live before the test run finishes, register it first so the
-tracker picks up its config right away:
-
-```sh
-curl --fail-with-body -X POST https://api.ralphralph.ai/api/upload/deployment/register \
-  -H "Authorization: Bearer $RALPH_UPLOAD_KEY" -H 'content-type: application/json' \
-  -d "{\"externalAppId\":\"$RALPH_APP_ID\",\"buildId\":\"$COMMIT_SHA\",
-       \"reserveArtifact\":false,\"config\":$(cat ralph.json)}"
-```
-
-`ralph.json` here is your `ralph.jsonc` as plain JSON, without comments or
-trailing commas. The test run that follows registers the same build again and
-uploads into it.
-
 ## Screen sizes
 
 Use `ralphProjects` to create one project per entry in `screenSizes`:
@@ -404,9 +352,21 @@ test.describe("desktop layouts", { tag: "@ralph-screen:1280x720" }, () => {
 });
 ```
 
-A size missing from `screenSizes` fails the test.
+A size missing from `screenSizes` fails the test. To run one size:
+`playwright test --project "chromium 375x812"`.
+
+## Sharded runs
 
-To run one size: `playwright test --project "chromium 375x812"`.
+Use the `blob` reporter on each shard, then merge with the Ralph reporter:
+
+```sh
+# Each shard (no upload credentials needed):
+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_APP_ID=… \
+  pnpm exec playwright merge-reports --reporter @ralphralphai/playwright/reporter ./all-blob-reports
+```
 
 ## Options
 
@@ -420,37 +380,114 @@ export default defineConfig<RalphFixtures>({
 });
 ```
 
-| Option                | Default                  | What it does                                                                                         |
-| --------------------- | ------------------------ | ---------------------------------------------------------------------------------------------------- |
-| `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.                                          |
-| `runId`               | `RALPH_RUN_ID`           | Identifies the CI run.                                                                               |
-| `settleMs`            | 150                      | Wait after the DOM loads before an automatic recording.                                              |
-| `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.          |
-| `freezeDuringCapture` | `false`                  | Finishes finite browser animations, allows JS-driven DOM changes to settle within a bounded wait, then freezes timers and animations across capture. |
-| `ignoreInDiff`        |                          | CSS selectors for subtrees to omit from the ARIA snapshot. See [Excluding elements from snapshots](#excluding-elements-from-snapshots). |
-| `strictNodeTags`      | `false`                  | Fails the test when the app reports a tag outside what `ralph.setNodeConditions` declared.           |
-| `ignoreUntaggedCalls` | `false`                  | Makes `recordNode`, `setNodeConditions`, and `observe` no-ops in untagged tests instead of throwing. |
-
-## Reporter options
+| Option                | Default                  | What it does                                                                                                                    |
+| --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `mode`                | `RALPH_MODE`, else `off` | `off`, `upload`, or `deploy`. 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.                                                                     |
+| `runId`               | `RALPH_RUN_ID`           | Identifies the CI run.                                                                                                          |
+| `settleMs`            | 150                      | Wait after the DOM loads before an automatic recording.                                                                         |
+| `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.                                     |
+| `freezeDuringCapture` | `false`                  | Lets the page settle, then freezes timers and animations across capture. See [Troubleshooting](#freezeduringcapture-in-detail). |
+| `ignoreInDiff`        |                          | CSS selectors for subtrees to omit from the ARIA snapshot.                                                                      |
+| `strictNodeTags`      | `false`                  | Fails the test when the app reports a tag outside what `ralph.setNodeConditions` declared.                                      |
+| `ignoreUntaggedCalls` | `false`                  | Makes `recordNode`, `setNodeConditions`, and `observe` no-ops in untagged tests instead of throwing.                            |
+
+### Reporter options
 
 ```ts
 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.                                        |
-| `appId`           | `RALPH_APP_ID`                                    | The app the recordings belong to.                                |
-| `uploadTimeoutMs` | 120000                                            | Upload timeout.                                                  |
-| `deploy`          | `RALPH_DEPLOY` is `1`                             | Uploads the run as its build's. See [Deployments](#deployments). |
-| `outputDir`       | `ralph/` in the first project's output directory  | Where the merged graph is written.                               |
+| Option            | Default                                           | What it does                                                  |
+| ----------------- | ------------------------------------------------- | ------------------------------------------------------------- |
+| `mode`            | `RALPH_MODE`, else `upload` if `RALPH_UPLOAD_KEY` | `upload` uploads the run. `deploy` uploads it as its build's. |
+| `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.                            |
+
+## Troubleshooting
+
+### A test failed because of recording
+
+- A failed `recordNode` call rejects.
+- A failed automatic recording fails the test at the end.
+- Pages left before capture, and pages whose layout moved during the
+  screenshot, don't fail the test.
+
+### A page has no screenshot
+
+The test left the page before capture finished, so it's `uncaptured`. Call
+`ralph.waitForCapture()` before navigating away.
 
-The run is also uploaded when any test ran in `upload` mode.
+### Part of a very large page is missing
+
+Screenshots are WebP, which holds at most 16,383 px per side. A taller or wider
+page is recorded up to that size, and what lies beyond it has no screenshot.
+
+### A dialog replaced the page's screenshot
+
+A dialog at the same URL is the same node. Give it its own node with a page tag
+via `ralph.setNodeConditions` (see
+[One URL, several renderings](#one-url-several-renderings)), since that is what
+production events carry.
+
+### The upload page shows `tagMismatches`
+
+If your app tags visitors and pages with `@ralphralphai/tracker`, each
+recording checks the declared node conditions against those tags. Where the app
+reports a value outside the declaration, the node lists it in `tagMismatches`,
+because that node would match no production traffic. Fix the declaration, or set
+`strictNodeTags` to fail the test instead.
+
+### `visitAllLinks` throws
+
+Every match must be a link (`<a href>`). A button that navigates by script
+can't open in a new tab, so the call throws before opening any.
+
+### An ignored element's text still shows in the diff
+
+`ignoreInDiff` removes matched elements and their descendants, including
+content in open shadow roots and slots. Text that sits inline in a larger
+element, like a bare `<span>` in a paragraph, belongs to that element's text
+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.
+
+### `freezeDuringCapture` in detail
+
+Ralph installs Playwright's clock before the app loads. Before capture it
+finishes running finite CSS transitions, CSS animations, and Web Animations,
+and watches DOM changes in the page, its frames, and open shadow roots. Timers
+and animation frames keep running until the DOM has been quiet for 150 ms, so
+JavaScript-driven animations can finish without changes to your app.
+Animations started by completion callbacks are checked again.
+
+This settling wait is capped at 1.5 seconds or half the remaining
+`recordTimeoutMs` budget, whichever is smaller. Looping browser animations are
+paused while settling. Then timers and all remaining browser animations pause
+during capture and resume afterward, including on failure. Animations the app
+already paused stay paused, and finished animations stay finished.
+
+Limits:
+
+- The quiet check is a heuristic. Long JavaScript animations can be captured
+  midway when the budget runs out, and future delayed work and canvas or WebGL
+  drawing aren't detected.
+- The clock replaces native timer APIs for the lifetime of the context, so
+  don't combine it with manual `page.clock` or `context.clock` control.
+- Playwright requires a future pause time. Ralph uses the page's current time
+  plus 100 ms, which advances the clock and can fire due callbacks once before
+  freezing. Time resumes from there without catching up through the capture.
+- All tabs in a context share the clock, so their timers pause together and
+  their captures run one at a time.
+- Network responses, workers, and media playback are not frozen.
+- With contexts you create yourself, await `ralph.observe(context)` before
+  creating or navigating any pages. A context with an already navigated page
+  can't be enrolled with this option on.
 
 ## Limits
 
@@ -458,6 +495,9 @@ Per run: 5,000 screenshots, 256 MiB of screenshots, 16 MiB of other recorded
 data, 256 MiB compressed, 20,000 recorded pages, and 5,000 recorded pages per
 test.
 
+Per page: an ARIA snapshot over 4 MiB or nested deeper than the server
+allows is left out. The page still uploads, but it can't be diffed.
+
 ## License
 
 Apache-2.0

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_upload = require("./upload-KEwXpYxG.cjs");
+const require_upload = require("./upload-8iYQZaCa.cjs");
 let node_path = require("node:path");
 node_path = require_upload.__toESM(node_path, 1);
 let _playwright_test = require("@playwright/test");
@@ -70,7 +70,7 @@ const test = _playwright_test.test.extend({
 			return;
 		}
 		const reported = process.env["RALPH_PLAYWRIGHT_REPORTER"] || testInfo.config.reporter.some(([name]) => name === "blob");
-		if (mode === "upload" && !reported) throw new Error("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.");
+		if ((mode === "upload" || mode === "deploy") && !reported) throw new Error("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.");
 		const root = testInfo.config.configFile ? node_path.default.dirname(testInfo.config.configFile) : process.cwd();
 		const key = JSON.stringify({
 			root,