Files
e2e/docs/reference/app.mdx
T
Oskar Kwaśniewski f0f9c8daae fix(security): allow only http(s) and about:blank on explicit navigation (#722)
* fix(security): allow only http(s) navigation, refuse wrapped schemes on device links

view-source:file:// passed the file:/data:/javascript: denylist and loaded local files via app.open, browser.goto, and the navigate verb. resolveNavigationUrl now admits http: and https: only; mobile links also refuse view-source:, blob:, filesystem:.

* fix(security): admit exact about:blank, sync rule text in AGENTS.md and SECURITY.md

* fix(web): refuse about:blank cookie URL, qualify scheme rule text
2026-10-03 13:16:39 +02:00

73 lines
3.2 KiB
Plaintext

---
title: app
description: The portable app lifecycle fixture, available on every platform.
---
`app` controls the app's lifecycle and captures screenshots. Each method
requires the corresponding engine capability; unsupported operations fail
with `UNSUPPORTED_CAPABILITY`.
```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; 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 and takes no path.
*/
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. */
screenshot(label?: string): Promise<string>;
}
```
`app` methods use the configured timeouts below, capped by the remaining test
timeout. They do not accept per-call timeout options.
| Method | Timeout | Throws |
| --- | --- | --- |
| `open(path?)` | `config.timeout`, 120000 ms | `APP_URL_REQUIRED` for a path when the target declares no `app.url`, `POLICY_DENIED` for a URL whose scheme is not `http:` or `https:` (`about:blank` aside), `APP_UNREACHABLE`, `ACTION_FAILED`, `UNSUPPORTED_CAPABILITY` without `session.open` on a target with a URL or without `session.restart` on one without (a device launches its pinned app) |
| `restart()` | `config.timeout`, 120000 ms | `ACTION_FAILED`, `ENGINE_FAILURE`, `UNSUPPORTED_CAPABILITY` without `session.restart` |
| `clearState()` | `config.timeout`, 120000 ms | `ACTION_FAILED`, `ENGINE_FAILURE`, `UNSUPPORTED_CAPABILITY` without `session.reset` |
| `back()` | `config.actionTimeout`, 30000 ms | `APP_NOT_OPEN`, `ACTION_FAILED`, `UNSUPPORTED_CAPABILITY` without `session.back` |
| `screenshot(label?)` | `config.actionTimeout`, 30000 ms | `POLICY_DENIED` after a secret fill, `UNSUPPORTED_CAPABILITY`, `ENGINE_FAILURE` |
`screenshot` registers the file as an attempt artifact and returns its path
relative to the attempt's artifact directory, under `screenshots/`; the report
records the artifact-root-relative path. `label` names the step and joins the
file name.
```ts
await app.open('/settings/billing');
const shot = await app.screenshot('after-checkout');
```
<Warning>
`clearState` inside a serial group destroys the shared state the group
depends on. Use it in `beforeEach` of an ordinary group instead.
</Warning>
Once a `Secret` has been filled, pixels are withheld for the rest of the
session, including later tests in a serial group. `app.screenshot()` then
fails with `POLICY_DENIED` and creates no artifact.
Browser-only operations live on the [`browser`](/reference/web) fixture;
device operations on [`device`](/reference/mobile).