Files
e2e/docs/reference/app.mdx

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).