e2e 0.15.2 → 0.17.0

package/docs/reference/expect.mdx

@@ -51,14 +51,18 @@ before passing its result to `expect`.
 | --- | --- |
 | Default timeout | `config.assertionTimeout`, 5000 ms |
 | Override | `{ timeout }` in milliseconds, on every locator and `browser` matcher |
-| Negation grace window | A negated matcher passes after 1000 ms of continuous truth, or after the whole budget when `{ timeout }` is shorter than that |
+| 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 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
@@ -84,21 +88,25 @@ Assert the outcome of the fill, not the field.
 ## Locator matchers
 
 ```ts
+/**
+ * The locator matchers. An option a matcher does not take, or a flag that is
+ * not a boolean, is `INVALID_ARGUMENT` before the first read.
+ */
 export interface AsyncExpectation {
   /** Inverts the matcher. A negated matcher passes after 1000 ms of continuous truth. */
   readonly not: AsyncExpectation;
-  /** Waits for visibility. */
-  toBeVisible(options?: { timeout?: number }): Promise<void>;
+  /** Waits for visibility; `visible: false` waits for hidden or absent state, as `toBeHidden`. */
+  toBeVisible(options?: { visible?: boolean; timeout?: number }): Promise<void>;
   /** Waits for hidden or absent state. */
   toBeHidden(options?: { timeout?: number }): Promise<void>;
-  /** Waits for one match to exist, visible or not. */
-  toBeAttached(options?: { timeout?: number }): Promise<void>;
-  /** Waits for enabled state. */
-  toBeEnabled(options?: { timeout?: number }): Promise<void>;
+  /** Waits for one match to exist, visible or not; `attached: false` waits for none. */
+  toBeAttached(options?: { attached?: boolean; timeout?: number }): Promise<void>;
+  /** Waits for enabled state; `enabled: false` waits for disabled state. */
+  toBeEnabled(options?: { enabled?: boolean; timeout?: number }): Promise<void>;
   /** Waits for disabled state. */
   toBeDisabled(options?: { timeout?: number }): Promise<void>;
-  /** Waits for checked state. */
-  toBeChecked(options?: { timeout?: number }): Promise<void>;
+  /** Waits for checked state; `checked: false` waits for unchecked state. */
+  toBeChecked(options?: { checked?: boolean; timeout?: number }): Promise<void>;
   /** Waits for selected state. */
   toBeSelected(options?: { timeout?: number }): Promise<void>;
   /** Waits for expanded state. */
@@ -106,20 +114,28 @@ export interface AsyncExpectation {
   /** Waits for focused state. */
   toBeFocused(options?: { timeout?: number }): Promise<void>;
   /** Waits for exact normalized text; a list waits for exactly that many matches, each with its entry's text, in order. */
-  toHaveText(expected: TextMatch, options?: { timeout?: number }): Promise<void>;
-  toHaveText(expected: readonly TextMatch[], options?: { timeout?: number }): Promise<void>;
+  toHaveText(expected: TextMatch, options?: TextMatcherOptions): Promise<void>;
+  toHaveText(expected: readonly TextMatch[], options?: TextMatcherOptions): Promise<void>;
   /** Waits for contained normalized text; a list waits for each entry to be contained by a distinct match, in order, extra matches allowed. */
-  toContainText(expected: TextMatch, options?: { timeout?: number }): Promise<void>;
-  toContainText(expected: readonly TextMatch[], options?: { timeout?: number }): Promise<void>;
+  toContainText(expected: TextMatch, options?: TextMatcherOptions): Promise<void>;
+  toContainText(expected: readonly TextMatch[], options?: TextMatcherOptions): Promise<void>;
   /** Waits for a form control's value, compared as it is. */
   toHaveValue(expected: TextMatch, options?: { timeout?: number }): Promise<void>;
   /** Waits for the attribute to be present; with `value`, for it to match. */
   toHaveAttribute(name: string, options?: { timeout?: number }): Promise<void>;
-  toHaveAttribute(name: string, value: TextMatch, options?: { timeout?: number }): Promise<void>;
+  toHaveAttribute(name: string, value: TextMatch, options?: TextMatcherOptions): Promise<void>;
   /** Waits for an exact match count. */
   toHaveCount(expected: number, options?: { timeout?: number }): Promise<void>;
   /** Waits for an accessible name. */
-  toHaveAccessibleName(expected: TextMatch, options?: { timeout?: number }): Promise<void>;
+  toHaveAccessibleName(expected: TextMatch, options?: TextMatcherOptions): Promise<void>;
+}
+
+/** Options of a locator matcher that compares text. */
+export interface TextMatcherOptions {
+  /** Compares a string case-insensitively; on a RegExp, `true` adds the `i` flag and `false` removes it. */
+  ignoreCase?: boolean;
+  /** Assertion budget in milliseconds. */
+  timeout?: number;
 }
 ```
 
@@ -140,6 +156,22 @@ password input, `toHaveAttribute` throws `POLICY_DENIED` like
 `toBeAttached` passes once one match exists, hidden or shown, where
 `toBeVisible` needs a shown one. Negated, it passes once nothing matches.
 
+The boolean options Playwright gives these matchers work the same way:
+`toBeChecked({ checked: false })` waits for an unchecked node,
+`toBeEnabled({ enabled: false })` for a disabled one,
+`toBeVisible({ visible: false })` for a hidden or absent one, as
+`toBeHidden` does, and `toBeAttached({ attached: false })` for no match.
+`ignoreCase: true` on `toHaveText`, `toContainText`, `toHaveAccessibleName`,
+and the value form of `toHaveAttribute` compares a string case-insensitively
+and adds the `i` flag to a `RegExp`; `ignoreCase: false` removes it.
+
+A matcher refuses any other option key, and a flag that is not a boolean, with
+`INVALID_ARGUMENT` before it reads the screen. Types catch these in
+TypeScript, but `e2e run` does not type-check, so the check runs for a
+JavaScript test or a computed option object too. Playwright options e2e does
+not implement, such as `indeterminate` on `toBeChecked` or `useInnerText` on
+`toHaveText`, fail this way instead of passing on the default.
+
 `toHaveText([...])` and `toContainText([...])` check a list, with no
 exactly-one rule; the failure message lists every text observed.
 `toHaveText([...])` needs the match count to equal the list length and the
@@ -153,6 +185,8 @@ holds. Negated, it fails as soon as that ordered subsequence exists, so
 
 ```ts
 await expect(screen.getByRole('status')).toHaveText('Saved');
+await expect(screen.getByRole('alert')).not.toContainText('error', { ignoreCase: true });
+await expect(screen.getByLabel('Subscribe')).toBeChecked({ checked: false });
 await expect(screen.getByTestId('todo')).toHaveCount(3);
 await expect(screen.getByTestId('todo')).toHaveText(['Write spec', /^Ship/, 'Release']);
 await expect(screen.getByTestId('todo')).toContainText(['spec', 'runner', 'Release']);
@@ -170,8 +204,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. */
@@ -181,7 +215,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`.
+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
@@ -293,8 +330,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
 
@@ -422,11 +462,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.
@@ -511,3 +555,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

@@ -53,6 +53,9 @@ For clients that use a `mcpServers` config, add:
 }
 ```
 
+The server needs no model: a project without the optional `ai` package
+opens sessions and drives the app with the deterministic tools.
+
 Start the server in the project directory. Config discovery works like
 `e2e run`. Set `--config` for another location, or pass `config` to
 `open_session` for one session.

package/docs/reference/mobile.mdx

@@ -3,7 +3,8 @@ title: Mobile
 description: Mobile engine options and the device fixture for iOS and Android.
 ---
 
-`@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 +80,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 +280,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 +291,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 +428,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 +449,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 +461,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

@@ -171,7 +171,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 +180,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

@@ -107,7 +107,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.
 
@@ -292,8 +299,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 +393,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 +414,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 +542,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. */
@@ -623,8 +644,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

package/docs/reference/test.mdx

@@ -97,16 +97,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