mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-21 03:05:26 +08:00
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
280 lines
9.7 KiB
Plaintext
280 lines
9.7 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. |
|
|
| `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).
|