Files
Samanyu DasandClaude Opus 5.5 7a8e546e26 fix(mobile): fail toHaveScreenshot with POLICY_DENIED when a secure field can't be masked (#2014)
* test(mobile): expect a screenshot mobile withheld to be refused for masking

On mobile, a screenshot the engine cannot mask is withheld with no sign it
was ever taken, so toHaveScreenshot waits out its timeout and fails with
ASSERTION_FAILED, and the agent is told the engine captures no pixels. These
tests expect the engine to report the regions it masked (none) beside the
missing pixels, toHaveScreenshot to fail at once with POLICY_DENIED, and the
agent to read MASKING_UNPROVEN. A screenshot that was never taken, or one
withheld with every secure field masked, still keeps the matcher waiting.

Refs #1996

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mobile): fail toHaveScreenshot with POLICY_DENIED when a secure field can't be masked

When a secure node on the mobile screen has no bounds, the engine cannot
mask it, so it drops the screenshot and reports nothing else. The session
could not tell that from a screenshot that failed, and the matcher checked
for missing pixels before it checked masking, so it polled until its timeout
and failed with ASSERTION_FAILED and "the engine returned no screenshot". On
the web the same case fails at once with POLICY_DENIED, which is what the
docs and AGENTS.md promise. The agent had the same gap: it was told the
engine captures no pixels (UNSUPPORTED_CAPABILITY) instead of
MASKING_UNPROVEN.

The engine contract now lets an engine withhold a screenshot it could not
mask by reporting maskedRegionCount without pixels. The mobile engine does
so for a secure node without bounds. An image it cannot read or decode is
still no screenshot, so the matcher takes another. When the count falls
short of the secure nodes, the session marks the observation
pixelsWithheld: 'MASKING_UNPROVEN', the token the agent already uses for
unproven pixels. toHaveScreenshot fails with POLICY_DENIED on it, and the
agent passes it on. A screenshot that was never taken (the web engine
mid-navigation, a failed device capture) reports no count, so the matcher
keeps waiting for it as before.

app.screenshot() on the same screen failed with ENGINE_FAILURE (exit 3)
for the same cause. It now fails with POLICY_DENIED too, as AGENTS.md
asks for withheld pixels. An image that cannot be decoded keeps
ENGINE_FAILURE, since there is no screenshot to withhold. Failure evidence
and agent evidence screenshots catch every error, so neither changes.

Fixes #1996

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(core): decide withheld pixels once, in the session

The session now keeps pixels on an observation only when the masked regions
cover every secure node, and marks any screenshot the engine took without
that proof, sent or withheld, as `pixelsWithheld: 'MASKING_UNPROVEN'`.
`toHaveScreenshot` and the agent's `clearPixels` read that one field and no
longer check the masking themselves.

The mobile engine reports a secure node without bounds as unbounded before
it reads the image, since no image makes that screen maskable, and drops
`decodesAsPng`. `redactSecure` returns a tagged result, and the
`ENGINE_FAILURE` message for an image it cannot read says so.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): keep fallback pixels only when their masking is proven

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(core): isolate the unproven fallback pixels case

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(mobile): withhold pixels on an unbounded screen without a screenshot

A secure field without bounds makes the screen unmaskable from the tree
alone, so the mobile engine now checks the bounds before it takes a
device screenshot. `observe` reports no regions masked and
`app.screenshot()` fails with `POLICY_DENIED`, even when the device
screenshot would have failed, and neither pays a device round trip.

Lists `POLICY_DENIED` under `app.screenshot()` in the app reference, and
says `maskedRegionCount` is reported when the harness asks for pixels.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(core): name pixelFallback as a pixels request in the count contract

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): mark pixels withheld only for a pixels request

The session now marks an observation `MASKING_UNPROVEN` only when the
caller asked for pixels, so the engine contract needs no rule about when
an engine reports `maskedRegionCount`. The masking check on fallback
pixels runs after the bare-root check, so a malformed unavailable tree
keeps `INVALID_STATE`. Tests pin the masked count the agent passes on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* docs(core): name pixels: true in the withheld count contract

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* test(mobile): pin the error category of a withheld app.screenshot()

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(core): leave fallback pixels to the engine's own masking proof

An unavailable tree is a bare root, so the session has no secure node to
count, and checking the masked-region count against zero proves nothing.
The engine that sends fallback pixels proves their masking itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-21 13:53:30 +01:00

281 lines
9.8 KiB
Plaintext

---
title: app
description: The portable app lifecycle fixture, available on every platform.
"og:image": "https://e2e.com/docs/images/og/reference/app.png?v=0b63e99aab"
"twitter:image": "https://e2e.com/docs/images/og/reference/app.png?v=0b63e99aab"
---
The `app` fixture opens, restarts, and resets the app under test, and takes
screenshots and recordings. It is on every target. A method the engine can't perform fails
with `UNSUPPORTED_CAPABILITY`.
```ts title="tests/billing.e2e.ts"
import { expect, test } from 'e2e';
test('billing page', async ({ app, screen }) => {
await app.open('/settings/billing');
await expect(screen.getByRole('heading', { name: 'Billing' })).toBeVisible();
await app.screenshot('billing');
});
```
## Reference
| Member | Returns |
| --- | --- |
| [`baseUrl`](#baseurl) | `string \| undefined` |
| [`open`](#open) | `Promise<void>` |
| [`restart`](#restart) | `Promise<void>` |
| [`clearState`](#clearstate) | `Promise<void>` |
| [`back`](#back) | `Promise<void>` |
| [`screenshot`](#screenshot) | `Promise<string>` |
| [`startRecording`](#startrecording) | `Promise<void>` |
| [`stopRecording`](#stoprecording) | `Promise<[RecordedVideo, ...RecordedVideo[]]>` |
`open`, `restart`, and `clearState` are bounded by `timeout`. The others
are bounded by `actionTimeout`. Both come from the
[config](/reference/config): `timeout` defaults to 120000 ms and
`actionTimeout` to 30000 ms. The remaining test timeout caps both. `app`
methods take no per-call timeout option.
### `baseUrl`
The resolved base URL of the target's app.
```ts
const health = await fetch(`${app.baseUrl}/api/health`);
```
- It has no trailing slash, so `${app.baseUrl}/path` joins with one slash.
- When `app.url` declares port `0`, `baseUrl` carries the port the run
allocated.
- On a target that declares no `app.url`, it is `undefined`. With `test`
from `@e2e-dev/web` it is typed `string`: a `web()` target always declares
`app.url`.
### `open`
Opens the app: the declared URL, a path relative to it, or any absolute
`http(s)` URL.
```ts
await app.open(); // the target's app.url
await app.open('/settings/billing'); // a path relative to app.url
await app.open('https://example.com/login'); // any http(s) URL
```
On a device target, which has no URL, `open()` launches the pinned app fresh.
A path opens as a link in the app when the target declares
[`app.linkBase`](/reference/config#linkbase), and is `APP_URL_REQUIRED`
without it. With a link base, an absolute link opens as given, custom app
schemes included.
| Throws | When |
| --- | --- |
| `APP_URL_REQUIRED` | A path, on a target that declares no `app.url` (or, on a device, no `app.linkBase`). |
| `POLICY_DENIED` | A URL whose scheme is not `http:` or `https:`. `about:blank` is allowed. On a device with `app.linkBase`, a link whose scheme is `file:`, `data:`, `javascript:`, `view-source:`, `blob:`, or `filesystem:`. |
| `APP_UNREACHABLE` | The app URL could not be reached. |
| `ACTION_FAILED` | The operation failed or timed out. |
| `UNSUPPORTED_CAPABILITY` | No `session.open` on a target with a URL, or no `session.restart` on one without. On a device with no `app.bundleId`, also the target's build not installed yet ([mobile](/reference/mobile#the-app-under-test)). |
### `restart`
Recreates the execution context and keeps persisted state. Then it reopens
the app at its base URL when the target declares one.
```ts
await app.restart();
```
| Throws | When |
| --- | --- |
| `ACTION_FAILED`, `ENGINE_FAILURE` | The operation or the engine failed. |
| `UNSUPPORTED_CAPABILITY` | No `session.restart`, or on a device with no `app.bundleId`, the build not installed yet. |
### `clearState`
Clears persisted client state and recreates the execution context. Then it
reopens the app at its base URL when the target declares one.
```ts
test.beforeEach(async ({ app }) => {
await app.clearState();
});
```
| Throws | When |
| --- | --- |
| `ACTION_FAILED`, `ENGINE_FAILURE` | The operation or the engine failed. |
| `UNSUPPORTED_CAPABILITY` | No `session.reset`, or on a device with no `app.bundleId`, the build not installed yet. |
<Warning>
`clearState` inside a serial group destroys the shared state the group
depends on. Use it in `beforeEach` of an ordinary group instead.
</Warning>
### `back`
Navigates back once.
```ts
await app.back();
```
| Throws | When |
| --- | --- |
| `APP_NOT_OPEN` | `app.open()` has not run, or the engine reported invalid state. |
| `ACTION_FAILED` | The operation failed or timed out. |
| `UNSUPPORTED_CAPABILITY` | No `session.back`. |
### `screenshot`
Captures a redacted evidence screenshot and returns its path.
```ts
const shot = await app.screenshot('after-checkout');
```
- The file is an attempt artifact under `screenshots/`. The returned path is
absolute. The report records the path relative to the artifact root.
- The `list` reporter's summary names up to 10 files in a `Screenshots` row,
then counts the rest.
- `label` names the step and joins the file name.
- A screenshot taken while the page navigates captures the document showing.
| Throws | When |
| --- | --- |
| `UNSUPPORTED_CAPABILITY` | The engine takes no screenshots. |
| `POLICY_DENIED` | On iOS and Android, a secure field on screen has no bounds to mask. |
| `ENGINE_FAILURE` | The capture failed. |
<Note>
The screenshot masks secure fields only, after a `Secret` fill too. A secret
the app shows anywhere else is in the image. See
[screenshots after a secret fill](/reference/security#screenshots-after-a-secret-fill).
</Note>
### `startRecording`
Starts recording the screen, until `stopRecording`.
```ts
test('the dialog slides in', { video: 'off' }, async ({ app, screen }) => {
await app.open();
await app.startRecording({ name: 'dialog' });
await screen.getByRole('button', 'Open').tap();
await expect(screen.getByRole('dialog')).toBeVisible();
const [video] = await app.stopRecording();
});
```
- One recording at a time. The engine has one recorder, so set
`video: 'off'` on the test: a start fails while the test's
[video](/reference/config#video) records. That includes `--video`,
`retain-on-failure`, and the retries `on-first-retry` records.
- A recording still running when the test ends is stopped and kept.
- Like the test's video, a recording masks nothing.
| Throws | When |
| --- | --- |
| `UNSUPPORTED_CAPABILITY` | The test's video records, or the engine records no video. |
| `INVALID_ARGUMENT` | Another recording is running. |
### `stopRecording`
Stops the recording and returns its videos, in play order.
```ts
const [video] = await app.stopRecording();
if ('path' in video) console.log(video.path);
```
- A video is a file (`path`, absolute) under the attempt's `recordings/`,
named `001-<name>.<ext>`, or a `url` when a hosted browser or device
keeps the recording.
- There is one video, except on the web when the page was replaced while
it recorded (`app.restart()`, `app.clearState()`): then one per page.
- The step links each video in the trace.
| Throws | When |
| --- | --- |
| `INVALID_ARGUMENT` | No recording is running. |
| `ENGINE_FAILURE` | The engine wrote no video. |
## Types
```ts
export interface App {
/**
* The resolved base URL of the target's app, with the port the run
* allocated when `app.url` declared port 0 and no trailing slash, so
* `${app.baseUrl}/api/users` joins with one slash; undefined for a target
* that declares no `app.url`.
*/
readonly baseUrl: string | undefined;
/**
* Opens the app: the declared URL, a path relative to it, or any absolute
* http(s) URL. On a device target, which has no URL, it launches the pinned
* app fresh; a path opens as a link in it when the target declares
* `app.linkBase`.
*/
open(path?: string): Promise<void>;
/**
* Recreates the execution context while preserving persisted state, then
* reopens the app at its base URL when the target declares one.
*/
restart(): Promise<void>;
/**
* Clears persisted client state, recreates the execution context, then
* reopens the app at its base URL when the target declares one.
*/
clearState(): Promise<void>;
/** Navigates back once. */
back(): Promise<void>;
/** Captures a redacted evidence screenshot and returns its absolute path. */
screenshot(label?: string): Promise<string>;
/**
* Starts recording the screen, until `stopRecording`. One recording at a
* time, and none while the test's `video` records: set `{ video: 'off' }`
* on the test.
*/
startRecording(options?: RecordingOptions): Promise<void>;
/**
* Stops the recording and returns its videos in play order: one, or on the
* web one per page when the page was replaced while it recorded.
*/
stopRecording(): Promise<readonly [RecordedVideo, ...RecordedVideo[]]>;
}
/** How `app.startRecording` names its file. */
export interface RecordingOptions {
/** File name stem, `recordings/001-<name>.<ext>`; defaults to `recording`. */
readonly name?: string;
}
/** One video `app.stopRecording` returns: a file, or a link to a recording a hosted service keeps. */
export type RecordedVideo = RecordedVideoFile | RecordedVideoLink;
/** A video file under the attempt's `recordings/` directory. */
export interface RecordedVideoFile {
/** Absolute path of the file. */
readonly path: string;
/** When it started recording, as an ISO timestamp. */
readonly startedAt: string;
}
/** A recording a hosted browser or device service keeps, by URL. */
export interface RecordedVideoLink {
/** `http(s)` URL of the recording. */
readonly url: string;
/** Media type of what the URL serves: `video/mp4`, or `text/html` for a player page. */
readonly mediaType: string;
/** When it started recording, as an ISO timestamp. */
readonly startedAt: string;
}
```
## Related
Browser-only operations live on the [`browser`](/reference/web) fixture, and
device operations on [`device`](/reference/mobile).