mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 07:55:36 +08:00
* 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
73 lines
3.2 KiB
Plaintext
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).
|