e2e 0.16.0 → 0.18.0

package/docs/reference/errors.mdx

@@ -1,6 +1,7 @@
 ---
 title: Errors
 description: Every code you can see, its class, and its exit code.
+icon: "triangle-exclamation"
 ---
 
 Every error carries a class. The class determines the exit code; the code
@@ -56,8 +57,8 @@ try {
 | `TEST_SETUP_FAILED` | Test prerequisites outside the product failed to arrange (blocked: test_setup). Also a `test.extend()` fixture that broke its contract: returned without calling `use()`, called it twice, or redefined a fixture the target's engine contributes | configuration | 2 |
 | `AUTOMATION_UNSUPPORTED` | The step needs an interaction the available toolset cannot perform, e.g. drag-and-drop (blocked: automation) | test | 1 |
 | `MODEL_UNAVAILABLE` | No model configured: the built-in agent's `agents.<name>.model` holds no AI SDK model instance; the message names the agent that was selected. Checked once per run when the `agent` fixture is first acquired; recorded as one run-level error that stops the run. `e2e explore` checks before anything starts, a custom executor's entry included, since explore runs the built-in agent. A custom executor without a model is not checked: its `act` and `assert` steps run, and `waitFor` or `extract` fails with this code on its first call. Evicts no [recording](/cache). | configuration | 2 |
-| `POLICY_DENIED` | A denied destination (`file:`, `data:`, `javascript:`, a malformed URL), a forbidden fill (an undeclared secret, a non-editable sink, a password into a field that is not a password field), or pixel evidence after a secret fill (`vision: 'only'` with pixels withheld). Also reading a value, text, or attribute from a secure field, the getters and the `toHaveValue`, `toHaveText`, `toContainText`, and `toHaveAttribute` matchers alike. An unknown tool or an undeclared field is refused to the model as the call's result and is not this code | configuration | 2 |
-| `APP_UNREACHABLE` | The app URL could not be reached, or an app command exited early or exceeded `startupTimeout`. The startup error includes recent log output with `command.env` values redacted, and suggests adding a `log` if none is configured. Under the agent, also any engine fault with no more specific code: on a device, an iOS automation runner that is busy or wedged reports here with a message that names the runner, the session and device, and the recovery; see [Testing iOS and Android](/mobile#troubleshooting) | infrastructure | 3 |
+| `POLICY_DENIED` | A denied destination (a navigation scheme other than `http:` or `https:`, `about:blank` aside, a malformed URL), a forbidden fill (an undeclared secret, a non-editable sink, a password into a field that is not a password field), or pixel evidence after a secret fill (`vision: 'only'` with pixels withheld, or an `act` or `vision: true` step whose semantic capture timed out before the step did). Also reading a value, text, or attribute from a secure field, the getters and the `toHaveValue`, `toHaveText`, `toContainText`, and `toHaveAttribute` matchers alike. An unknown tool or an undeclared field is refused to the model as the call's result and is not this code | configuration | 2 |
+| `APP_UNREACHABLE` | The app URL could not be reached, or an app command exited early or exceeded `startupTimeout`. The startup error includes recent log output with `command.env` values redacted, and suggests adding a `log` if none is configured. Under the agent, also any engine fault with no more specific code: on a device, an iOS automation runner that is busy or wedged reports here with a message that names the runner, the session and device, and the recovery; see [Mobile](/mobile#troubleshooting) | infrastructure | 3 |
 | `APP_ALREADY_RUNNING` | `readyUrl` already answered before the target's `app.command` was spawned and `reuseExisting` was not in effect; stop that process or set `reuseExisting: true` locally | infrastructure | 3 |
 | `MODEL_PROVIDER_FAILED` | Provider transport failure (network error, 5xx, rate limit, or a request with no response within 120 s) after the adapter's transport retries (up to 5 per model call, honoring `retry-after`, bounded by the remaining step timeout). A request that stalls is aborted at 120 s and sent again, and an `agent.act` step's `--debug` transcript notes it. The bound covers the whole request, so a model that needs longer than 120 s for one answer fails here too. Evicts no [recording](/cache) | infrastructure | 3 |
 | `CANCELLED` | The runner cancelled the operation, without a process signal: an `e2e mcp` `open_session` whose request the client cancelled or whose connection closed, or that the server's shutdown cut short, after stopping what it had started | infrastructure | 3 |
@@ -73,7 +74,7 @@ try {
 | `ASSERTION_INCONCLUSIVE` | `agent.assert` could not judge: the screen did not show enough to decide either way (the relevant part is not on screen, still loading, or unreadable). `agent.extract` raises it when the model answers that the screen does not show the requested data, instead of returning a placeholder. A failure, never a pass; the explanation says what was missing. Judged from the tree alone with `vision` off, the message adds `pass vision: true when the answer is in pixels`, as a condition (`if the engine captures pixels, ...`) until a step of the attempt has received pixels; no hint when the engine declares no screenshot capture, a secret was filled, or an earlier step's pixel request was degraded | test | 1 |
 | `AUTHENTICATION_FAILED` | The executor concluded that signing in failed inside the app: a product verdict. `AUTH_CREDENTIAL_INVALID` is the blocked counterpart for a configured credential the app rejects | test | 1 |
 | `STEP_NO_CONCLUSION` | The executor used every turn without calling `complete_step`; the step fails with the agent's last summary | test | 1 |
-| `REPLAY_STALE` | Under `cache.strict` or `--strict-cache`, the step's recording exists but no longer replays (`step.cache.reason` is one of `invalid-entry`, `wrong-context`, `target-not-found`, `target-ambiguous`, `viewport-changed`, `action-failed`, `action-uncertain`, `end-mismatch`), so the step fails with no model call instead of handing off to the agent. Not retried: a retry never replays and would pass live. Re-record with a read-write run without the flag, and with `cache.strict` off when the config set it, then commit the changed entry; the message names the knob that turned strict on and the configured cache directory (or `cache.store`) | configuration | 2 |
+| `REPLAY_STALE` | Under `cache.strict` or `--strict-cache`, the step's recording exists but no longer replays (`step.cache.reason` is one of `invalid-entry`, `wrong-context`, `target-not-found`, `target-ambiguous`, `viewport-changed`, `action-failed`, `action-uncertain`, `end-mismatch`, or `no-entry` while the cache directory, not a custom `cache.store`, holds a recording of the step under another key, which the message names), so the step fails with no model call instead of handing off to the agent. Not retried: a retry never replays and would pass live. Re-record with a read-write run without the flag, and with `cache.strict` off when the config set it, then commit the changed entry; the message names the knob that turned strict on and the configured cache directory (or `cache.store`) | configuration | 2 |
 
 ## Runner codes
 
@@ -83,8 +84,8 @@ These appear in terminal output and in the report as plain string codes.
 | --- | --- | --- | ---: |
 | `CONFIG_NOT_FOUND` | `--config <path>` names a file that does not exist, or no `e2e.config.ts` or `e2e.config.mts` exists from the working directory up to the repository root | configuration | 2 |
 | `CONFIG_AMBIGUOUS` | Both `e2e.config.ts` and `e2e.config.mts` in one directory | configuration | 2 |
-| `CONFIG_LOAD_FAILED` | The config module failed to import: a package that is declared but not installed, an undeclared package, a wrong subpath, a removed export, or any other throw while it evaluates. The message names the fix. A config error raised while it evaluates keeps its own code: an option a factory the config calls (`web()`, `mobile()`, `defineEngine()`) refuses, or a `secrets.get()` handle turned into a string, is `INVALID_CONFIG` | configuration | 2 |
-| `INVALID_CONFIG` | A factory the config module calls (`web()`, `mobile()`, `defineEngine()`) refused its options, with the factory's own message; or an unknown key, out-of-range value, invalid enum, missing `targets`, a target key outside `{ name, platform, engine, app, trace, video }`, a target `app` key that is unknown or malformed, `app` on a target without an engine, a `web()` target without `app.url` or with a device field, a `mobile()` target without `app.bundleId` or `app.appPath`, with `app.url` (not supported yet), a link in `bundleId`, or an unknown permission name or state (the message names the nearest name), an unknown key in a `web()` or `mobile()` option, including `web({ connect })` and `web({ basicAuth })` (the message names the nearest one), a `trace` or `video` that is not a recording mode, the removed artifact kinds list (`artifacts: [...]` or `artifacts.kinds`) and `artifacts.trace` block (the message names the `trace` mode they meant), the removed `artifacts.video` block or `video` artifact kind (the message names the `video` option), the removed `specVersion` key, a `secrets.get()` in an engine option that names no `secrets` entry (a credential's password is not one), a `secrets.get()` reference turned into a string while the config evaluates (a template literal, `String()`) or given where a string is needed (an `app.command` `args` entry or `env` value; only an engine option that declares secrets takes one), an `app.command` `args` entry or `env` value that is not a string (an `undefined` `env` value is dropped instead), an unknown key in `app.command` (the message names the nearest one), an `engine` that is not a `defineEngine` handle, `json` reporter combined with `list`, duplicate or malformed target name, a secret or credential password shorter than 6 characters (code points), oversized `agents.<name>.context`, an `expect.poll` `timeout` or `interval` that is not a finite number of milliseconds, a `tests` value that is not a glob or a list of globs, a `tests` list of only `!` exclusions, the removed top-level `limits` key, an agents entry that is a bare `StepExecutor` (the message names `{ executor }`) or a model instance (the message names `{ model }`), an unknown agent key (the message names the nearest one), the removed agent keys `timeout` and `maxTurns` (the message names `judgmentTimeout` and `maxModelCalls`), `system` or `tools` beside `executor`, a `tools` entry `defineTool` did not build or that takes a built-in tool name (a grammar verb, `complete_step`, `locate`, `start_recording`, `stop_recording`, or `report_finding`), `createToolLoopExecutor({ maxTurns })`, `reuseExisting` on an app whose `app.url` asks for a free port, or a port-0 `app.url` with no `app.command` to serve it | configuration | 2 |
+| `CONFIG_LOAD_FAILED` | The config module failed to import: a package that is declared but not installed, an undeclared package, a wrong subpath, a removed export, or any other throw while it evaluates. The message names the fix. A config error raised while it evaluates keeps its own code: an option a factory the config calls (`web()`, `mobile()`, `defineEngine()`, `decisionExecutor()`) refuses, or a `secrets.get()` handle turned into a string, is `INVALID_CONFIG` | configuration | 2 |
+| `INVALID_CONFIG` | A factory the config module calls (`web()`, `mobile()`, `defineEngine()`, `decisionExecutor()`) refused its options, with the factory's own message; or an unknown key, out-of-range value, invalid enum, missing `targets`, a target key outside `{ name, platform, engine, app, trace, video }`, a target `app` key that is unknown or malformed, `app` on a target without an engine, a `web()` target without `app.url` or with a device field, a `mobile()` target without `app.bundleId` or `app.appPath`, with `app.url` (not supported yet), a link in `bundleId`, or an unknown permission name or state (the message names the nearest name), an unknown key in a `web()` or `mobile()` option, including `web({ connect })` and `web({ basicAuth })` (the message names the nearest one), a `trace` or `video` that is not a recording mode, the removed artifact kinds list (`artifacts: [...]` or `artifacts.kinds`) and `artifacts.trace` block (the message names the `trace` mode they meant), the removed `artifacts.video` block or `video` artifact kind (the message names the `video` option), the removed `specVersion` key, a `secrets.get()` in an engine option that names no `secrets` entry (a credential's password is not one), a `secrets.get()` reference turned into a string while the config evaluates (a template literal, `String()`) or given where a string is needed (an `app.command` `args` entry or `env` value; only an engine option that declares secrets takes one), an `app.command` `args` entry or `env` value that is not a string (an `undefined` `env` value is dropped instead), an unknown key in `app.command` (the message names the nearest one), an `engine` that is not a `defineEngine` handle, `json` reporter combined with `list`, duplicate or malformed target name, a secret or credential password shorter than 6 characters (code points), two credentials or two secrets whose names map to one `E2E_USER_*` or `E2E_SECRET_*` override variable (`api-key` and `api_key`), oversized `agents.<name>.context`, an `expect.poll` `timeout` or `interval` that is not a finite number of milliseconds, a `tests` value that is not a glob or a list of globs, a `tests` list of only `!` exclusions, the removed top-level `limits` key, an agents entry that is a bare `StepExecutor` (the message names `{ executor }`) or a model instance (the message names `{ model }`), an unknown agent key (the message names the nearest one), the removed agent keys `timeout` and `maxTurns` (the message names `judgmentTimeout` and `maxModelCalls`), `system` or `tools` beside `executor`, a `tools` entry `defineTool` did not build or that takes a built-in tool name (a grammar verb, `complete_step`, `locate`, `start_recording`, `stop_recording`, or `report_finding`), `createToolLoopExecutor({ maxTurns })`, `reuseExisting` on an app whose `app.url` asks for a free port, or a port-0 `app.url` with no `app.command` to serve it | configuration | 2 |
 | `CONFIG_NOT_DETERMINISTIC` | A worker re-resolved the config module and got a different digest than the runner | configuration | 2 |
 | `APP_URL_REQUIRED` | A navigation or relative URL on a target that declares no `app.url`, or an `app.command` with no `app.url` or `app.readyUrl` to poll | configuration | 2 |
 | `INVALID_APP_URL` | Base URL with userinfo, a query, a fragment, a non-HTTP scheme, plain HTTP on a non-loopback host, port 0 on a host other than a literal loopback address (`127.0.0.1`, `[::1]`), a loopback address the run could not bind a free port on, or unparseable | configuration | 2 |
@@ -104,24 +105,26 @@ These appear in terminal output and in the report as plain string codes.
 | `NO_LAST_RUN` | `--last-failed` found no `report.json` where the run writes it, or a file there that is not a `report-1` document. Run once without the flag first. | configuration | 2 |
 | `ONLY_IN_CI` | A focused test reached a CI run | configuration | 2 |
 | `COLLECTION_ERROR` | Registration outside collection, an invalid title, a non-function body, an async `describe` body, nested serial groups, an option forbidden inside a serial group, a setup test inside `describe`, an invalid session name, a malformed test option such as `tags` that is not a list of distinct names, a test or `describe` option key the call does not take (the message names the nearest one), a test file that fails to import (in a run with no positionals, or a file the positionals selected), a session that a selected test consumes or `e2e explore --session` names but no collected setup test produces (the message lists the declared sessions), a consumed session on a target whose engine has no `state` capability to save it, or a positional path outside the project root | configuration | 2 |
-| `POLICY_DENIED` | A denied destination (`file:`, `data:`, `javascript:`, a malformed URL), a forbidden fill (an undeclared secret, a non-editable sink, a mismatched purpose, a `Secret` reaching a JSON sink), or tainted pixels (`app.screenshot()` after a secret fill, `vision: 'only'` with pixels withheld); see the [security model](/security). An unknown tool or an undeclared field goes back to the model as the call's result, never this code | configuration | 2 |
+| `POLICY_DENIED` | A denied destination (a navigation scheme other than `http:` or `https:`, `about:blank` aside, a malformed URL), a forbidden fill (an undeclared secret, a non-editable sink, a mismatched purpose, a `Secret` reaching a JSON sink), or tainted pixels (`app.screenshot()` after a secret fill, `vision: 'only'` with pixels withheld, an `act` or `vision: true` step whose semantic capture timed out before the step did); see the [security model](/security). An unknown tool or an undeclared field goes back to the model as the call's result, never this code | configuration | 2 |
 | `SESSION_MISMATCH` | A stored session does not match the current run, target, engine, platform, or app identity | configuration | 2 |
 | `SESSION_EXPIRED` | A stored session is past its expiry at restore time (configuration, exit 2), or a setup test saved state whose expiry is not after its creation (test, exit 1) | configuration or test | 2 or 1 |
 | `SESSION_INVALID` | A stored session failed authentication. Tampered or corrupt. | configuration | 2 |
 | `SESSION_UNAVAILABLE` | A test requires a session no selected setup test produced | configuration | 2 |
 | `SESSION_CONTRACT` | A setup test saved a session twice, saved an undeclared name, or finished without saving a declared one | test | 1 |
-| `TEST_TIMEOUT` | The attempt exceeded the resolved test `timeout`. The body is not stopped: the harness operation it is in is cancelled and its fixtures die with the attempt, so it cannot reach the next test | test | 1 |
-| `STEP_NOT_AWAITED` | The test body settled while a step it started was still running: a step call without `await`. The step is failed at the line of the call and cancelled; the attempt fails with this code when the body returned, or keeps the body's own error and records this one under `secondaryErrors` when the body threw | test | 1 |
+| `TEST_TIMEOUT` | The attempt exceeded the resolved test `timeout`. The body is not stopped: the harness operation it is in is cancelled and its fixtures die with the attempt, so it cannot reach the next test. A test that blocks the event loop gets its worker killed once `cleanupTimeout` (at least 5 s) passes after the timeout; see [Hooks](/reference/test#hooks) | test | 1 |
+| `STEP_NOT_AWAITED` | The test body settled while a step it started was still running: a step call without `await`. The step is failed at the line of the call and cancelled; the attempt fails with this code when the body returned, or keeps the body's own error and records this one under `secondaryErrors` when the body threw. An `expect.poll` matcher left running when the body, an `afterEach` hook, or a fixture teardown returned fails that phase the same way at the line of the call, and is cancelled; one left by a `beforeAll` or `afterAll` hook fails the hook with `HOOK_FAILED` | test | 1 |
 | `UNHANDLED_REJECTION` | A promise rejected with no test running. An unhandled rejection is charged to the test running when it surfaces, since Node cannot say which test created the promise; between tests it is this run error, naming the last test that finished in the worker as the likely source. Before any test has finished in the worker it ends the worker instead: the rejection is the run error and the test on its way fails with `WORKER_CRASH`. The body that left it keeps running like one past `TEST_TIMEOUT` | test | 1 |
 | `HOOK_FAILED` | `beforeAll` or `afterAll` threw. Skips the suite's tests. | test | 1 |
 | `LAUNCH_TIMEOUT` | Engine init or attempt start exceeded `config.launchTimeout` | infrastructure | 3 |
 | `CLEANUP_TIMEOUT` | Engine attempt end exceeded `config.cleanupTimeout`, or a route or dialog handler the engine ran for the test was still running when the attempt settled | infrastructure | 3 |
-| `TRACE_WITHHELD` | A trace from an attempt a secret reached (filled, or held by the engine) could not be rewritten, so it was deleted. Recorded in the attempt's `secondaryErrors`; never fails the attempt. | infrastructure | 3 |
+| `TRACE_WITHHELD` | A trace from a session that knows a secret value could not be rewritten, so it was deleted, or the engine returned an archive path outside the attempt's artifact directory, so nothing was registered. Recorded in the attempt's `secondaryErrors`; never fails the attempt. | infrastructure | 3 |
 | `BROWSER_INSTALL_FAILED` | Browser provisioning failed | infrastructure | 3 |
 | `WORKER_INIT_FAILED` | A worker process never became ready | infrastructure | 3 |
-| `WORKER_EXIT` | A worker exited unexpectedly while running a file: the test in flight fails with `WORKER_CRASH` and the file's other tests are skipped. An unhandled rejection is charged to the test running when it surfaces, or recorded as `UNHANDLED_REJECTION` between tests; before any test has finished there it ends the worker, and the rejection itself is the run error, not this one | infrastructure | 3 |
+| `WORKER_EXIT` | A worker exited unexpectedly while running a file: the test in flight fails with `WORKER_CRASH` and the file's other tests are skipped. Attempts that finished before the exit stay in the report, a retry's earlier attempts and a serial group's finished members included, and the crash is recorded as the attempt after them, or on the last attempt when it came after it (an `afterAll`). An unhandled rejection is charged to the test running when it surfaces, or recorded as `UNHANDLED_REJECTION` between tests; before any test has finished there it ends the worker, and the rejection itself is the run error, not this one | infrastructure | 3 |
 | `WORKER_CRASH` | A worker exited during a specific test | infrastructure | 3 |
 | `WORKER_ENTRY_MISSING` | The worker entry module could not be resolved. Packaging fault. | infrastructure | 3 |
+| `NODE_UNSUPPORTED` | The runtime cannot run e2e's TypeScript loader: a Node.js outside `^22.22.3 \|\| >=24.8.0`, Bun (no `module.registerHooks`), or Deno. The CLI checks this before it starts and exits 2 with the same sentence; the loader checks it again where it registers its hooks, for a host that runs e2e's runner without the CLI | infrastructure | 3 |
+| `TYPESCRIPT_COMPILER_UNAVAILABLE` | oxc, which compiles e2e's TypeScript, could not be loaded; the message gives the cause. Most often its native bindings for this platform (`@oxc-transform/binding-<platform>-<arch>`, `@oxc-parser/binding-<platform>-<arch>`) are not installed. npm leaves it out with `--omit=optional`, or when `package-lock.json` was written on another platform (npm/cli#4828): install again without `--omit=optional`, or delete `package-lock.json` and `node_modules` and run `npm install` | infrastructure | 3 |
 | `ENGINE_FAILURE` | Any engine fault with no more specific mapping | infrastructure | 3 |
 | `WORKER_PROTOCOL` | A worker reported a unit other than the one it was running, or started an attempt while another was still running | infrastructure | 3 |
 | `SESSION_KEY_INVALID` | A worker received a session key that is not 32 bytes. Packaging or IPC fault. | infrastructure | 3 |

package/docs/reference/expect.mdx

@@ -1,6 +1,7 @@
 ---
 title: expect
 description: "Locator assertions, fixture assertions, and plain value matchers."
+icon: "circle-check"
 ---
 
 Use `expect(locator)` to wait for an app condition and `expect(value)` to
@@ -52,14 +53,17 @@ before passing its result to `expect`.
 | Default timeout | `config.assertionTimeout`, 5000 ms |
 | Override | `{ timeout }` in milliseconds, on every locator and `browser` matcher |
 | Unknown option | `INVALID_ARGUMENT` before the first read, from JavaScript too |
-| Negation grace window | A negated matcher passes after 1000 ms of continuous truth, or after the whole budget when `{ timeout }` is shorter than that |
+| Negation grace window | A negated matcher passes after 1000 ms of continuous truth, or at the deadline when `{ timeout }` is shorter than that and the negation held for the whole budget. The window counts from the moment the first read that saw the negation started, so a slow read counts toward it |
 | Failure code | `ASSERTION_FAILED`, exit code 1 |
 
 Locator strictness: except for `toHaveCount` and the list form of
 `toHaveText` and `toContainText`, a positive matcher requires exactly one
 match; zero matches keep polling until the timeout, and multiple matches fail
-immediately with `LOCATOR_AMBIGUOUS`. `toBeHidden`, negated visibility, and
-negated `toBeAttached` accept zero matches.
+immediately with `LOCATOR_AMBIGUOUS`. `toBeHidden`, `toBeVisible({ visible:
+false })`, `toBeAttached({ attached: false })`, negated visibility, and
+negated `toBeAttached` accept zero matches; for them, and for
+`waitFor({ state: 'detached' })` and `'hidden'`, a locator under a frame that
+is not in the document is zero matches rather than a wait for the frame.
 
 Text comparison is normalized: leading and trailing whitespace is trimmed and
 each run of whitespace collapses to one space. `toHaveText` and
@@ -201,8 +205,8 @@ Every matcher call is a recorded `expect.<matcher>` assertion step.
 export interface BrowserExpectation {
   /** Inverts the matcher. */
   readonly not: BrowserExpectation;
-  /** Waits for the current URL to match. */
-  toHaveURL(expected: string | RegExp, options?: { timeout?: number }): Promise<void>;
+  /** Waits for the current URL to match; `ignoreCase` compares a string case-insensitively and adds the `i` flag to a RegExp, `false` removes it. */
+  toHaveURL(expected: string | RegExp, options?: { ignoreCase?: boolean; timeout?: number }): Promise<void>;
   /** Waits for the current title to match. */
   toHaveTitle(expected: TextMatch, options?: { timeout?: number }): Promise<void>;
   /** Waits for the target's `class` attribute to match: a string is the whole normalized class list, a RegExp is tested against it. */
@@ -212,9 +216,10 @@ export interface BrowserExpectation {
 
 A relative `toHaveURL` string resolves against the base URL and matches
 exactly after normalization; a `RegExp` tests the full URL. Anything else,
-such as a predicate function, is `INVALID_ARGUMENT`. Each `browser` matcher takes
-`timeout` only; any other key, such as Playwright's `ignoreCase` on
-`toHaveURL`, is `INVALID_ARGUMENT`.
+such as a predicate function, is `INVALID_ARGUMENT`. `toHaveURL` also takes
+Playwright's `ignoreCase`, with the locator matchers' semantics. Otherwise each
+`browser` matcher takes `timeout` only; any other key, such as `ignoreCase` on
+`toHaveTitle`, which Playwright does not take either, is `INVALID_ARGUMENT`.
 
 `toHaveClass` polls for the node too: a target that matches nothing yet is one
 more poll, not a failure, until the assertion timeout runs out. An ambiguous
@@ -326,8 +331,11 @@ side is refused.
 `toHaveProperty` walks a dotted path or an array of keys. Use the array form
 when a key contains a dot, or to index an array by number
 (`['lines', 0, 'sku']`). Inherited properties count; a property holding
-`undefined` exists. With a second argument the value at the path must equal it
-by `toEqual` rules.
+`undefined` exists. A string, number, or boolean on the path is read through
+its wrapper object, as in Jest, so `toHaveProperty('label.length', 3)` and
+`toHaveProperty(['label', 0], 'a')` reach into a string; `null` and
+`undefined` have no properties. With a second argument the value at the path
+must equal it by `toEqual` rules.
 
 ### Matching a schema
 
@@ -363,7 +371,7 @@ The unit-runner matchers (`toThrow`, `toBeInstanceOf`, `toBeNaN`,
 `toStrictEqual`, `resolves`, `rejects`, `expect.extend`) are not part of
 `expect`. An end-to-end test checks what the app shows and what its API
 returns; the value matchers cover that, see
-[Testing APIs](/api-testing). Code-level
+[API](/api-testing). Code-level
 checks belong in the unit runner.
 
 Pass a second argument to describe the check in its failure message:
@@ -455,11 +463,15 @@ ASSERTION_FAILED: 2 soft assertions failed
 A soft locator or `browser` matcher is still a recorded `expect.<matcher>` step,
 marked failed, so the report shows where in the flow it landed. A soft value
 matcher is not a step, the same as a hard one; its failure appears in the
-final error only.
+attempt's error records.
 
 When the body throws on its own, or times out, that error stays the
 attempt's verdict and the soft failures are recorded beside it under
-`secondaryErrors`. A body that skips itself with `test.skip(...)` drops them.
+`secondaryErrors`. A body that skips itself with `test.skip(...)` keeps them
+there too. The CLI shows `Skipped After Failure`; set
+[`failOnSkippedFailure: true`](/reference/config) to make that run fail with
+exit code 1. Without that option, the test stays skipped and does not affect
+the exit code.
 
 A soft `toMatchSchema` returns the schema's output when the value matches
 and `undefined` after a kept failure, and its type says so.
@@ -544,3 +556,14 @@ await expect.poll(() => readStatus(), { message: 'the batch never finished' }).n
 
 `expect.poll` is not recorded as a report step; a timeout surfaces only as
 the test's failure.
+
+Await every poll. A poll belongs to the phase that started it: the test body
+(with its fixtures and `beforeEach` hooks), one `afterEach` hook or fixture
+teardown, or one `beforeAll` or `afterAll` hook. When that phase returns while
+the poll still runs, the poll is cancelled and the phase fails with
+`STEP_NOT_AWAITED` at the line of the call, whether or not the poll would
+have passed. It never fails a later test: a poll started by work its phase
+left running, such as a body past its timeout, is cancelled before its first
+read. A body that threw keeps its own
+error and records this one under `secondaryErrors`, and a suite hook reports
+it as `HOOK_FAILED`.

package/docs/reference/mcp.mdx

@@ -1,19 +1,20 @@
 ---
 title: MCP server (e2e mcp)
 description: Let a coding agent inspect and interact with your app over MCP.
+icon: "plug"
 ---
 
 <CodeGroup>
 ```bash npm
-npx e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+npx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
 ```
 
 ```bash pnpm
-pnpm exec e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+pnpm exec e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
 ```
 
 ```bash bun
-bunx e2e mcp [--config <path>] [--target <name>] [--headless] [--max-sessions <n>]
+bunx e2e mcp [--config <path>] [--target <name>] [--headed] [--max-sessions <n>]
 ```
 </CodeGroup>
 
@@ -64,21 +65,32 @@ Start the server in the project directory. Config discovery works like
 | --- | --- |
 | `--config <path>` | The config every session loads unless `open_session` names one. Configs are reloaded on every `open_session`, with every file they import by path. |
 | `--target <name>` | The target every session opens on. Otherwise `open_session` names one, or the only target is used; several targets and no name is `TARGET_REQUIRED`. |
-| `--headless` | Hide the browser or simulator. Sessions are headed by default outside CI. |
+| `--headed` | Show the browser or simulator, when the engine supports it, in every session whose `open_session` does not set `headed`. Sessions are headless by default, as in `e2e run`. |
 | `--max-sessions <n>` | How many sessions may be open at once, 1 through 16; default 4. Each session is its own browser or device. |
 
 Operator output goes to stderr, prefixed `e2e mcp:`. Stdout carries only the
-protocol; anything a config module writes to stdout is redirected.
+protocol. What your code writes through `console`, `process.stdout`, or
+`process.stderr` (the config's top-level code, project tools) goes to stderr
+with secret values redacted. Output printed while a config loads appears once
+it has loaded; if the load fails, that output is withheld, since the config's
+secrets are unknown. An error nobody caught is logged redacted and shuts the
+server down. A child process that inherits the server's stdio writes past
+this.
 
 ## Tools
 
 | Tool | Arguments | Result |
 | --- | --- | --- |
-| `open_session` | `target` (optional), `config` (optional path) | Loads the config, starts the target's app command, boots the engine, starts one attempt, opens the app URL when the engine can navigate. Returns the session id, the catalog, and the first observation. |
+| `open_session` | `target` (optional), `config` (optional path), `headed` (optional boolean) | Loads the config, starts the target's app command, boots the engine, starts one attempt, opens the app URL when the engine can navigate. Returns the session id, the catalog, and the first observation. `headed: true` shows this session's browser or simulator, `false` hides it; without it the session follows `--headed`. |
 | `tools` | `tool` (optional), `session` (required while several are open) | The catalog, one line per tool. With `tool`, its full description and argument schema. |
 | `call` | `tool`, `args` (optional), `session` (required while several are open) | Runs one catalog tool. Arguments are validated against the tool's closed schema first: a wrong type or an argument the tool does not declare is `INVALID_ARGUMENT`, and nothing runs. An action that fails is an error result that still carries the screen it re-observed, and leads with the tool, its target, and the code: `navigate file:///etc/passwd failed: POLICY_DENIED: forbidden URL scheme: file:`. |
 | `close_session` | `session` (required while several are open) | Saves a recording still running, ends the attempt, disposes the engine, stops the app processes the session started once no other session uses them. |
 
+Project tools honor their AI SDK `toModelOutput` renderer, including when
+`execute` returns a string. Rendered `error-text` and `error-json` outputs
+are MCP error results (`isError: true`) so the coding agent can distinguish
+a failed tool call from a successful one.
+
 ## Several sessions
 
 Several sessions can be open at once, up to `--max-sessions`, each on its
@@ -183,8 +195,9 @@ Sessions enforce what tests enforce. Node ids are valid only against the
 newest observation. A secret fills only through `type_secret`; once one has
 been filled, `screenshot` and the point tools (`tap_at`, `hover_at`,
 `type_at`, `press_at`, `select_at`) stay in the catalog but answer
-`PIXEL_TAINTED` for the rest of the session. Every text a `call` returns, a node `locate` found,
-an action's result, or an error, passes the attempt's secret ledger. Nothing a
+`PIXEL_TAINTED` for the rest of the session. Every text a tool returns, a node `locate` found,
+an action's result, an `open_session` or `close_session` failure, or a cleanup line, has the
+config's secret values redacted once the config has loaded, as do the server's own log lines. Nothing a
 session does is recorded as a test result or into the replay cache; its
 artifacts land under `<output>/artifacts/<target>/sessions/`, its videos under
 `<output>/videos/`. A later `e2e run` clears `<output>/artifacts`; the

package/docs/reference/mobile.mdx

@@ -1,9 +1,11 @@
 ---
 title: Mobile
 description: Mobile engine options and the device fixture for iOS and Android.
+icon: "mobile-screen"
 ---
 
-`@e2e-dev/mobile` drives iOS simulators and Android emulators through
+`@e2e-dev/mobile` drives iOS simulators, Android emulators, and connected
+phones through
 [agent-device](https://github.com/callstack/agent-device). `agent`, `app`,
 `screen`, and `expect` work as they do everywhere; this page covers what is
 specific to a device target. Import `test` from the package to have `device`
@@ -79,8 +81,9 @@ export interface MobileOptions {
   /** Platform the target's device runs. */
   readonly platform: MobilePlatform;
   /**
-   * Simulator or emulator to use, by name, simulator UDID, or emulator
-   * serial (`emulator-5554`). A list is a pool: the
+   * Device to use: a simulator or emulator by name, simulator UDID, or
+   * emulator serial (`emulator-5554`), or a connected phone by name. A list
+   * is a pool: the
    * engine declares one worker per entry and worker slot `n` drives the
    * `n`th, so `workers` at or above the pool size runs the target's files
    * across every device at once. Omitted, the pool is every booted device of
@@ -278,8 +281,8 @@ export interface Device {
    * `relaunch` restarts it fresh. `launchArguments` and `permissions` apply
    * to this launch alone; the target's configured ones apply to a `relaunch`
    * of the pinned app, and to no foreground-only open. A link is
-   * `INVALID_ARGUMENT` (`file:`, `data:`, and `javascript:` are
-   * `POLICY_DENIED`): `openLink` opens one.
+   * `INVALID_ARGUMENT` (`file:`, `data:`, `javascript:`, `view-source:`,
+   * `blob:`, and `filesystem:` are `POLICY_DENIED`): `openLink` opens one.
    */
   openApp(app: string, options?: OpenAppOptions): Promise<void>;
   /**
@@ -289,8 +292,8 @@ export interface Device {
    * a web link the app does not claim goes to Safari, and the next
    * observation brings the app back. Android starts the link on that
    * package. Without an app, Android lets the OS route the link; iOS needs
-   * one (`INVALID_ARGUMENT` without). `file:`, `data:`, and `javascript:`
-   * links are `POLICY_DENIED`.
+   * one (`INVALID_ARGUMENT` without). `file:`, `data:`, `javascript:`,
+   * `view-source:`, `blob:`, and `filesystem:` links are `POLICY_DENIED`.
    */
   openLink(url: string, options?: { app?: string }): Promise<void>;
   /**
@@ -426,7 +429,10 @@ session opened. Android reads the device's foreground activity.
 `installApp` installs a build from inside a test or a fixture: the run's build once per device (no path installs `app.appPath`), or another build for an upgrade path. A plain
 install keeps the app's data; `reinstall: true` removes the app named by
 `app` (default: the pinned app) first. It resolves to the id to `openApp`
-the build by.
+the build by: the bundle id or package agent-device read from the build, else
+the `app` passed in. With no reported id and no `app`, the install is
+`ENGINE_FAILURE` instead of a file path posing as an id; see
+[Troubleshooting](/mobile#troubleshooting).
 
 ```ts
 const { app } = await device.installApp('./build/MyApp.app', { reinstall: true });
@@ -444,9 +450,9 @@ name (`Settings`); `relaunch: true` restarts it fresh, and `launchArguments`
 and `permissions` apply to that launch alone (the target's own apply to a
 `relaunch` of the pinned app). It takes no link:
 agent-device opens any `scheme:rest` string as a URL, so a link is refused
-before the device sees it. A `file:`, `data:`, or `javascript:` link is
-`POLICY_DENIED`, the rule every navigation follows; any other link is
-`INVALID_ARGUMENT` pointing at `openLink`.
+before the device sees it. A `file:`, `data:`, `javascript:`,
+`view-source:`, `blob:`, or `filesystem:` link is `POLICY_DENIED`; any other
+link is `INVALID_ARGUMENT` pointing at `openLink`.
 
 `openLink` opens a deep link or a web link into `app` (default: the pinned
 app), for magic-link sign-in and deep-link routes, and the session observes
@@ -456,8 +462,13 @@ observation brings the app back. Android starts the link on that package.
 Without an app, Android lets the OS route the link, to a verified app link
 owner or the browser, and the session follows the package that took it. iOS
 needs an app: an open bound to none leaves no app session to observe, so it
-is `INVALID_ARGUMENT`. `file:`, `data:`, and `javascript:` links are
-`POLICY_DENIED`, as on the web. The report shows the link cut before its
+is `INVALID_ARGUMENT`. `file:`, `data:`, `javascript:`, `view-source:`,
+`blob:`, and `filesystem:` links are `POLICY_DENIED`. A device link may use
+any app's custom scheme, so the rule refuses these schemes rather than
+admitting http(s) alone as the web does. A string that does not parse as an
+absolute URL is `INVALID_ARGUMENT` too, and its message names no part of the
+input, which may carry a magic-link token in its query, path, or userinfo.
+The report shows the link cut before its
 query and fragment, where a magic link carries its token. The replay cache
 anchors on the location the link lands on: a step recorded after `openLink`
 replays when the link lands on the same screen again.

package/docs/reference/reporters.mdx

@@ -1,6 +1,7 @@
 ---
 title: Reporters
 description: Receive run events and publish results with a custom reporter.
+icon: "file-lines"
 ---
 
 Add reporter objects to `reporters` in `e2e.config.ts`, alongside the
@@ -171,7 +172,7 @@ prints. All reporters run concurrently, each with a one-minute deadline.
 A timeout, exception, or invalid return value is reported on stderr without
 changing the run's status, exit code, or report.
 
-One Ctrl-C still lets reporters finish. A second Ctrl-C stops waiting for them.
+One Ctrl-C still lets reporters finish. A second Ctrl-C stops waiting for them, except the built-in `junit` and `markdown`, which still write their files so none of the previous run's is left beside the new report.
 
 The second argument is an `AbortSignal` that aborts when the budget runs out
 or the run is forced to stop. Hand it to every request and timer, or an
@@ -180,7 +181,13 @@ abandoned reporter keeps the CLI alive after the run has ended.
 With `--last-failed`, `lastRun` is the report the rerun selected from. The
 rerun's own report lists the tests it left out as unselected, so a reporter
 that keeps one place current, the way `@e2e-dev/github` keeps a pull request
-comment, folds the rerun into `lastRun` to show both runs as one.
+comment, folds the rerun into `lastRun` to show both runs as one. A test the
+rerun owed but another filter left out is in the rerun's `run.carried`: its
+last result, the serial group its attempts live on, and the `beforeAll` or
+`afterAll` failure whose scope holds it, from whichever earlier run reported
+them. A fold shows the carried result in place of the unselected one and
+counts a carried failure or hook error against the outcome. The artifacts
+both reports name are on disk under `artifactsRoot`.
 
 The rows a reporter resolves with print under the `list` summary in the same
 layout as `Report`; the `json` reporter does not carry them:

package/docs/reference/screen.mdx

@@ -1,6 +1,7 @@
 ---
 title: screen and Locator
 description: Queries, refinement, actions, and reads.
+icon: "display"
 ---
 
 A `Locator` stores a query and resolves it when an action, read, or assertion
@@ -107,7 +108,14 @@ await screen.getByTestId('memory-list', { visible: true }).getByRole('listitem')
 ```
 
 `visible` uses the same visibility check as `toBeVisible()`, `isVisible()`,
-and `waitFor()`. It works with scopes, `filter`, `first`, `last`, and `nth`:
+and `waitFor()`: what renders, as Playwright reads it. `display: none`,
+`visibility: hidden`, a box with no size, a closed `<details>` body, and
+content under `content-visibility: hidden` are hidden; `aria-hidden` is not,
+since a decorative spinner marked with it still paints, so
+`toBeHidden()` on one waits until it leaves. A child that sets
+`visibility: visible` under a hidden parent is visible. On the web, text
+directly under a `display: contents` element with `visibility: hidden` is
+hidden, where Playwright calls it visible. It works with scopes, `filter`, `first`, `last`, and `nth`:
 `getByText('Save', { visible: true }).first()` is the first visible match.
 Prefer it over `browser.locator('p:visible')`, which ties the test to CSS.
 
@@ -171,14 +179,15 @@ not the finger: `'down'` reveals what is below. `momentum` is its fling
 strength, `'none'` by default: `'none'` a plain drag of half the surface,
 `'slow'` a short fling, `'fast'` a long one. How far each carries is the
 engine's.
-`{ from, to }` is a swipe along a path between two viewport points: a touch
-swipe on a device, a pointer drag on a document platform, which is what
-reveals a row action, dismisses a sheet, or drags a card between columns.
-Uses `config.actionTimeout`. Throws
-`ACTION_FAILED` when the gesture is rejected, `INVALID_ARGUMENT` for a mix
-of the two shapes or a coordinate off the plane, and `UNSUPPORTED_CAPABILITY`
-when the engine does not list `swipe` in its actions (a direction) or
-`swipeTo` in its pointer actions (a path).
+`{ from, to, duration? }` is a swipe along a path between two viewport points:
+a touch swipe on a device, a pointer drag on a document platform, which is
+what reveals a row action, dismisses a sheet, or drags a card between
+columns. `duration` sets how long the gesture takes in milliseconds; omitted
+leaves the duration to the engine's default. Uses `config.actionTimeout`.
+Throws `ACTION_FAILED` when the gesture is rejected, `INVALID_ARGUMENT` for
+a mix of the two shapes, an out-of-range duration, or a coordinate off the
+plane, and `UNSUPPORTED_CAPABILITY` when the engine does not list `swipe` in
+its actions (a direction) or `swipeTo` in its pointer actions (a path).
 
 ```ts
 await screen.swipe({ direction: 'up', momentum: 'fast' });
@@ -187,6 +196,7 @@ const row = await screen.getByText('Design review').boundingBox();
 await screen.swipe({
   from: { x: row.x + row.width - 10, y: row.y + row.height / 2 },
   to: { x: row.x + 10, y: row.y + row.height / 2 },
+  duration: 300,
 });
 ```
 
@@ -292,8 +302,12 @@ export interface Locator extends Screen {
   all(): Promise<Locator[]>;
   /** Reads the normalized text of every current match, without auto-waiting; empty when nothing matches. */
   allTextContents(): Promise<string[]>;
-  /** Waits for the requested locator state. */
-  waitFor(options?: { state?: 'visible' | 'hidden'; timeout?: number }): Promise<void>;
+  /**
+   * Waits for the requested locator state, `visible` by default: `attached`
+   * for one match, visible or not; `detached` for none; `hidden` for none or
+   * a hidden one.
+   */
+  waitFor(options?: { state?: 'attached' | 'detached' | 'visible' | 'hidden'; timeout?: number }): Promise<void>;
   /** Adds deterministic locator filters. */
   filter(options: { hasText?: TextMatch; has?: Locator }): Locator;
   /** Selects the first current match. */
@@ -382,7 +396,11 @@ await screen.getByLabel('City').pressSequentially('War', { delay: 50 });
 ## Locator reads
 
 `waitFor` defaults `state` to `'visible'` and `timeout` to
-`config.actionTimeout`, and throws `LOCATOR_NOT_FOUND` on timeout.
+`config.actionTimeout`, and throws `LOCATOR_NOT_FOUND` on timeout. `'attached'`
+waits for one match, hidden or shown, `'detached'` for none, and `'hidden'` for
+a hidden match or none. Several matches are `LOCATOR_AMBIGUOUS` in every
+state. Any other state, or an option key besides `state` and `timeout`, is
+`INVALID_ARGUMENT` before anything is resolved.
 
 `textContent` and `allTextContents` return the node's rendered text with
 whitespace collapsed to single spaces. On the web that is what `innerText`
@@ -399,6 +417,12 @@ a heading; it does not throw.
 `toHaveText`, `toContainText`, and `toHaveAttribute`.
 `isEnabled`, `isDisabled`, `isChecked`, and `boundingBox` are allowed there.
 
+`boundingBox()` is `null` for a node that lays out no box (`display: none`
+on it or an ancestor), and a box for one `visibility: hidden` keeps.
+`inputValue()` and `toHaveValue` on a checkbox or radio read its value
+attribute, `on` when it has none, whatever its checked state; `isChecked()`
+reads the state.
+
 `isHidden` is `!isVisible()` and `isDisabled` is `!isEnabled()`, with the
 same strictness: `isHidden` is `true` for zero matches, `isDisabled` is
 `LOCATOR_NOT_FOUND` there, and both are `LOCATOR_AMBIGUOUS` on several.
@@ -521,7 +545,7 @@ export interface TextMatchOptions {
 /**
  * Role query options. A role query never matches a node hidden from the
  * accessibility tree, on every engine; `visible` (inherited) is the one knob
- * that narrows the other query kinds the same way.
+ * that narrows the other query kinds, to the nodes `toBeVisible()` accepts.
  */
 export interface RoleOptions extends TextMatchOptions {
   /** Accessible name filter. */
@@ -564,6 +588,7 @@ export interface SwipeOptions {
   momentum?: Momentum;
   from?: never;
   to?: never;
+  duration?: never;
 }
 
 /** A swipe along a path between two viewport points: a touch swipe on a device, a pointer drag on a document platform. */
@@ -572,6 +597,8 @@ export interface SwipePathOptions {
   from: Point;
   /** Where it lifts. */
   to: Point;
+  /** Gesture duration in milliseconds; omitted = the engine's default. */
+  duration?: number;
   direction?: never;
   momentum?: never;
 }
@@ -623,8 +650,10 @@ export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
 export type Momentum = 'none' | 'slow' | 'fast';
 ```
 
-A role query never matches a node hidden from the accessibility tree.
-`visible` applies the same rule to the other query kinds. See
+A role query never matches a node hidden from the accessibility tree: one
+that does not render, or one under `aria-hidden`. `visible` narrows the
+other query kinds to the nodes that render, the check `toBeVisible()` makes,
+so an `aria-hidden` node that still paints counts as visible there. See
 [Hidden duplicates](#hidden-duplicates).
 
 `img` is an alias, not a role: `getByRole('img', { name })` builds the same
@@ -640,7 +669,11 @@ and `<details>` are `group`, `<input type="number">` is `spinbutton`,
 `<select size="3">` is a `listbox` like a `multiple` one, an `<input list>`
 naming a `<datalist>` is a `combobox`, a `<td>` of a `role="grid"` table is a
 `gridcell`,
-`<thead>` and `<tbody>` are `rowgroup`, `<th scope="row">` is `rowheader`,
+`<thead>` and `<tbody>` are `rowgroup`, `<th scope="row">` is `rowheader`.
+A scope-less `<th>` beside a data cell with text or children is also a
+`rowheader`; header-only rows keep `columnheader`. A lone scope-less header in a one-row
+table has no header role, while `scope="col"` and `scope="colgroup"` explicitly
+keep `columnheader`.
 `<figure>` is `figure`, `<article>` is `article`, `<header>` and `<footer>` are
 `banner` and `contentinfo` only outside sectioning content or an element with
 a sectioning role (`article`, `complementary`, `main`, `navigation`, `region`),

package/docs/reference/test.mdx

@@ -1,6 +1,7 @@
 ---
 title: test
 description: Tests, setup tests, groups, hooks, options, and fixtures.
+icon: "flask-vial"
 ---
 
 Declare tests, groups, and hooks synchronously while the test file is
@@ -97,16 +98,23 @@ group titles and then the test's own, are a `COLLECTION_ERROR`.
 
 ## Members
 
-A skipped test never affects the exit code. With `test.only`, other tests
+A skipped test does not affect the exit code by default. With `test.only`, other tests
 are reported as `filtered`, and a CI run fails with `ONLY_IN_CI`.
 
 Call `test.skip(condition, reason)` inside a test for conditions you learn at
 runtime, such as a disabled feature flag. When the condition is true, the call
 throws: the body stops at that line, as Playwright's does, and the test is
 reported `skipped` with `reason`, with no retry. Nothing after the call runs.
-Steps before it stay in the report as they ran, but they do not decide the
-status: a failed `expect.soft` before the call is dropped. Hooks and fixtures still run their teardown. When the condition is
-a precondition, call it first, before any step.
+Steps before it stay in the report as they ran. Soft failures before the call
+remain in the attempt's `secondaryErrors`, and the CLI lists the test under
+`Skipped After Failure`. A failed attempt followed by a skip on retry appears
+there too, with its original error. Hooks and fixtures still run their teardown.
+When the condition is a precondition, call it first, before any step.
+
+Set [`failOnSkippedFailure: true`](/reference/config) to fail the run with exit
+code 1 when a runtime skip follows a failure in that test. The test remains
+`skipped` with its reason, and the skip does not trigger another retry. Clean
+skips and retries that pass are unaffected. The default is `false`.
 
 A setup test cannot skip because other tests depend on its sessions; the
 call fails with `INVALID_ARGUMENT`. Outside a test body, the conditional
@@ -185,6 +193,19 @@ for every scope whose `beforeAll` started.
 its own `cleanupTimeout` budget with working fixtures, so teardown can still
 drive the app after the body timed out.
 
+A test that blocks its worker's event loop (`while (true) {}` in a fixture,
+`beforeEach`, the body, or `afterEach`) stops every timer in that worker, so
+the worker cannot time it out. A `beforeAll` or `afterAll` that blocks still
+hangs the run. When the worker has not responded `cleanupTimeout` (at least 5 s) after
+the test timeout, the runner kills it. That attempt is reported `timed-out`
+with `TEST_TIMEOUT` and no artifacts, after the attempts before it, and is
+not retried. The rest of its file runs on a new worker. In a serial group,
+the members after it are skipped. A worker with a debugger attached when the
+test starts (an editor's auto-attach, or `NODE_OPTIONS=--inspect=0`) is
+never killed this way, so a breakpoint can stay paused. A programmatic run with an inline
+config or in-memory tests runs in the runner's own process and has no worker
+to kill: a blocked event loop hangs it.
+
 A throw inside `beforeAll` or `afterAll` is `HOOK_FAILED` and skips the
 suite's tests with cause `hook-failed`. Inside a serial group it skips every
 remaining member and fails the group without a retry.
@@ -295,7 +316,13 @@ group's attempt. A retry starts fresh. Inside it, `retries`, `trace`,
 `video`, `session`, `platforms`, `requires`, `skip`, `only`, and a nested
 `serial` on a member are collection errors. Set them on the group. The group
 records one trace and one video per group attempt, from the `trace` and
-`video` on the serial `describe` or a group around it.
+`video` on the serial `describe` or a group around it. A group attempt that
+cannot start, because its file fails to load or its session fails to launch,
+fails the first member with that error and skips the rest with cause
+`serial-predecessor-failed`. When the run is interrupted during the launch,
+every member skips instead. On a retry, the members keep the verdicts of
+the attempt before it. The exit code follows the error's category, as for any
+other test.
 
 ## Fixtures