### e2e guide with npm

Source: https://e2e.tester.army/docs/reference/cli

Print the skill that init installs. Without an argument, prints the overview; with a topic, prints that topic.

```bash
npx e2e guide            # the overview
npx e2e guide setup      # one topic

```

--------------------------------

### e2e guide with bun

Source: https://e2e.tester.army/docs/reference/cli

Print the skill that init installs using bun. Without an argument, prints the overview; with a topic, prints that topic.

```bash
bunx e2e guide            # the overview
bunx e2e guide setup      # one topic

```

--------------------------------

### e2e guide with pnpm

Source: https://e2e.tester.army/docs/reference/cli

Print the skill that init installs using pnpm. Without an argument, prints the overview; with a topic, prints that topic.

```bash
pnpm exec e2e guide            # the overview
pnpm exec e2e guide setup      # one topic

```

--------------------------------

### Run the app in the machine with smol app option

Source: https://e2e.tester.army/docs/integrations/smol

Run the app under test in each browser machine with the app option. Each attempt gets its own copy of the running app and its files, including a local database. Set app.url to http://localhost:<port> and declare no app.command; setup and start run on every machine boot before prepare.

```typescript
smol({
  app: {
    source: '.',
    setup: 'npm ci && npm run db:seed',
    start: 'npm start',
    port: 3000,
    env: { DATABASE_URL: 'file:/app/dev.db' },
  },
})

```

--------------------------------

### Device.installApp(path?, options?)

Source: https://e2e.tester.army/docs/reference/mobile

Installs a build (an iOS `.app` bundle or an Android `.apk`, resolved against the project root) on the device; without a path, the target's `app.appPath`. The engine installs nothing on its own, so a suite that runs against a build calls this once per device, in a fixture or a test. `reinstall: true` removes the app first so it starts with no data; a plain install replaces the binary and keeps its data. Resolves to the identity to `openApp` it by, which becomes the app `app.open()` launches when the target's build is installed and no `app.bundleId` is pinned.

```APIDOC
## Device.installApp(path?, options?)

### Description
Installs a build (an iOS `.app` bundle or an Android `.apk`, resolved against the project root) on the device; without a path, the target's `app.appPath`. The engine installs nothing on its own, so a suite that runs against a build calls this once per device, in a fixture or a test. `reinstall: true` removes the app first so it starts with no data; a plain install replaces the binary and keeps its data. Resolves to the identity to `openApp` it by, which becomes the app `app.open()` launches when the target's build is installed and no `app.bundleId` is pinned.

### Method
installApp

### Parameters
- **path** (string) - Optional - Path to the build (`.app` or `.apk`), resolved against the project root. Defaults to the target's `app.appPath`.
- **options** (object) - Optional - Installation options.
  - **reinstall** (boolean) - Optional - If true, removes the app first so it starts with no data.

### Returns
- **Promise<string>** - Resolves to the identity to `openApp` it by.
```

--------------------------------

### Start signed in with npx

Source: https://e2e.tester.army/docs/explore

Runs `e2e explore` with a session name. The explorer runs only that setup test and restores the session, so it knows the app starts signed in and plans no sign-in step. If the setup fills a password, the exploration has no screenshots.

```bash
npx e2e explore --session admin 'Explore the admin settings and find bugs'

```

--------------------------------

### Run e2e example with npx, pnpm, or bun

Source: https://e2e.tester.army/docs/quickstart

Runs the example test. e2e downloads a browser or boots the simulator/emulator, checks that the app opens, and prints the result. The example makes no model calls, so it needs no sign-in or API key.

```bash
npx e2e run

```

```bash
pnpm exec e2e run

```

```bash
bunx e2e run

```

--------------------------------

### Install and sign in for ChatGPT Plus or Pro

Source: https://e2e.tester.army/docs/subscriptions

Install the AI SDK and OpenAI provider, then sign in with `npx e2e login openai`.

```bash
npm install -D ai @ai-sdk/openai
npx e2e login openai

```

```bash
pnpm add -D ai @ai-sdk/openai
pnpm exec e2e login openai

```

```bash
bun add -d ai @ai-sdk/openai
bunx e2e login openai

```

--------------------------------

### Install and sign in for SuperGrok or X Premium+

Source: https://e2e.tester.army/docs/subscriptions

Install the AI SDK and xAI provider, then sign in with `npx e2e login spacexai`.

```bash
npm install -D ai @ai-sdk/xai
npx e2e login spacexai

```

```bash
pnpm add -D ai @ai-sdk/xai
pnpm exec e2e login spacexai

```

```bash
bun add -d ai @ai-sdk/xai
bunx e2e login spacexai

```

--------------------------------

### Install @e2e-dev/github with bun

Source: https://e2e.tester.army/docs/github

Install the reporter as a dev dependency using bun.

```bash
bun add -d @e2e-dev/github

```

--------------------------------

### Install and open an app with device.installApp

Source: https://e2e.tester.army/docs/mobile

Installs an app from a build path with the reinstall option, then opens it. The returned app object is passed to device.openApp.

```javascript
const { app } = await device.installApp('./build/MyApp.app', { reinstall: true });
await device.openApp(app);
```

--------------------------------

### Install and sign in for GitHub Copilot

Source: https://e2e.tester.army/docs/subscriptions

Install the AI SDK, OpenAI-compatible, and OpenAI providers, then sign in with `npx e2e login github-copilot`.

```bash
npm install -D ai @ai-sdk/openai-compatible @ai-sdk/openai
npx e2e login github-copilot

```

```bash
pnpm add -D ai @ai-sdk/openai-compatible @ai-sdk/openai
pnpm exec e2e login github-copilot

```

```bash
bun add -d ai @ai-sdk/openai-compatible @ai-sdk/openai
bunx e2e login github-copilot

```

--------------------------------

### start_recording

Source: https://e2e.tester.army/docs/reference/mcp

Starts a video of the app. One recording at a time; a second start reports the one running.

```APIDOC
## start_recording

### Description
Starts a video of the app. One recording at a time; a second start reports the one running.

### Method
Tool call

### Endpoint
`start_recording`

### Parameters
- **name** (string) - Optional - Up to 64 letters, digits, `-`, and `_`, starting with a letter or digit.

### Response
- **result** (string) - The result of starting the recording.
```

--------------------------------

### Example browser provider and config

Source: https://e2e.tester.army/docs/browser

Example provider and config for leasing browsers from a service that starts a Chromium per session. The provider sends three requests: create a session, poll it until it has a DevTools endpoint, and stop it. The config registers the provider with the web engine and sets workers to 2.

```typescript
import type { BrowserProvider } from '@e2e-dev/web';

/**
 * Leases browsers from a service that starts a Chromium per session and
 * exposes its DevTools endpoint. Replace the three requests with your
 * service's API.
 */
export function hostedBrowsers(options: { serviceUrl: string; scope?: 'worker' | 'attempt' }): BrowserProvider {
  return {
    name: 'hosted-browsers',
    scope: options.scope ?? 'worker',
    async acquire(request) {
      const token = request.env['BROWSER_SERVICE_TOKEN'];
      if (token === undefined || token === '') throw new Error('BROWSER_SERVICE_TOKEN is not set');
      const headers = { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' };
      // 1. Ask for a browser; name the session after the run so it can be found later.
      const created = await fetch(`${options.serviceUrl}/sessions`, {
        method: 'POST',
        headers,
        body: JSON.stringify({
          name: `e2e ${request.runId} ${request.targetName} ${request.attemptId ?? `slot ${request.slot + 1} of ${request.slots}`}`,
        }),
        signal: request.signal,
      });
      if (!created.ok) throw new Error(`browser service: HTTP ${created.status}`);
      const { id } = (await created.json()) as { id: string };
      // 2. Wait until the session exposes its DevTools endpoint.
      for (;;) {
        const response = await fetch(`${options.serviceUrl}/sessions/${id}`, { headers, signal: request.signal });
        const session = (await response.json()) as { status: string; cdpUrl?: string; viewerUrl?: string };
        if (session.status === 'ready' && session.cdpUrl !== undefined) {
          if (session.viewerUrl !== undefined) request.log(`watch at ${session.viewerUrl}`);
          return { id, cdpEndpoint: session.cdpUrl };
        }
        if (session.status !== 'starting') throw new Error(`browser service: session ${id} is ${session.status}`);
        await new Promise((resolve) => setTimeout(resolve, 2_000));
      }
    },
    async release(lease, context) {
      // 3. Stop the session; the run waits for this within cleanupTimeout.
      const token = context.env['BROWSER_SERVICE_TOKEN'] ?? '';
      await fetch(`${options.serviceUrl}/sessions/${lease.id}/stop`, {
        method: 'POST',
        headers: { Authorization: `Bearer ${token}` },
        signal: context.signal,
      });
    },
  };
}

```

```typescript
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { hostedBrowsers } from './browser-provider.ts';

export default {
  targets: [
    {
      name: 'hosted',
      engine: web({
        browser: hostedBrowsers({ serviceUrl: 'https://browsers.example.com' }),
      }),
      app: { url: 'https://staging.example.com' },
    },
  ],
  workers: 2,
} satisfies E2EConfig;

```

--------------------------------

### Install and sign in for OpenCode Console

Source: https://e2e.tester.army/docs/subscriptions

Install the AI SDK, OpenAI-compatible, OpenAI, Anthropic, and Google providers, then sign in with `npx e2e login opencode-console`.

```bash
npm install -D ai @ai-sdk/openai-compatible @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
npx e2e login opencode-console

```

```bash
pnpm add -D ai @ai-sdk/openai-compatible @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
pnpm exec e2e login opencode-console

```

```bash
bun add -d ai @ai-sdk/openai-compatible @ai-sdk/openai @ai-sdk/anthropic @ai-sdk/google
bunx e2e login opencode-console

```

--------------------------------

### Install Kernel provider and SDK with npm

Source: https://e2e.tester.army/docs/integrations/kernel

Install the @e2e-dev/kernel provider and @onkernel/sdk as dev dependencies using npm.

```bash
npm install --save-dev @e2e-dev/kernel @onkernel/sdk

```

--------------------------------

### Install Kernel provider and SDK with bun

Source: https://e2e.tester.army/docs/integrations/kernel

Install the @e2e-dev/kernel provider and @onkernel/sdk as dev dependencies using bun.

```bash
bun add -d @e2e-dev/kernel @onkernel/sdk

```

--------------------------------

### bunx @e2e-dev/web install webkit --with-deps

Source: https://e2e.tester.army/docs/browser

Installs an extra browser using bun.

```APIDOC
## bunx @e2e-dev/web install webkit --with-deps

### Description
Installs the specified browser with dependencies using bun.

### Method
CLI command

### Parameters
- **browser** (string) - Required - The browser name to install (e.g., 'webkit').
- **--with-deps** (flag) - Optional - Installs system dependencies.

### Request Example
```bash
bunx @e2e-dev/web install webkit --with-deps
```

### Response
No response; command output.
```

--------------------------------

### Install @e2e-dev/github with pnpm

Source: https://e2e.tester.army/docs/github

Install the reporter as a dev dependency using pnpm.

```bash
pnpm add -D @e2e-dev/github

```

--------------------------------

### Install @e2e-dev/smol and smolmachines

Source: https://e2e.tester.army/docs/integrations/smol

Install the smol browser provider and the smol machines SDK. The first boot pulls the Playwright Ubuntu image, so it takes longer.

```bash
npm install --save-dev @e2e-dev/smol smolmachines

```

```bash
pnpm add -D @e2e-dev/smol smolmachines

```

```bash
bun add -d @e2e-dev/smol smolmachines

```

--------------------------------

### device.installApp

Source: https://e2e.tester.army/docs/mobile

Installs an app on the device, supporting upgrades and fresh installs. Returns an app handle for further operations.

```APIDOC
## device.installApp

### Description
Installs an app from a build path, with an option to reinstall (fresh install). Returns an app object that can be used with other device methods.

### Method
installApp

### Parameters
- **path** (string) - Required - Path to the app build (e.g., './build/MyApp.app').
- **options** (object) - Optional - Installation options.
  - **reinstall** (boolean) - Optional - If true, performs a fresh install (upgrade or reinstall).

### Request Example
```
const { app } = await device.installApp('./build/MyApp.app', { reinstall: true });
await device.openApp(app);
```

### Response
Returns an object containing an `app` handle that can be used with `device.openApp`.
```

--------------------------------

### Install Kernel provider and SDK with pnpm

Source: https://e2e.tester.army/docs/integrations/kernel

Install the @e2e-dev/kernel provider and @onkernel/sdk as dev dependencies using pnpm.

```bash
pnpm add -D @e2e-dev/kernel @onkernel/sdk

```

--------------------------------

### Install packages for Claude Max or Team

Source: https://e2e.tester.army/docs/subscriptions

Install the AI SDK and Anthropic provider. Claude plans require an API key, not sign-in.

```bash
npm install -D ai @ai-sdk/anthropic

```

```bash
pnpm add -D ai @ai-sdk/anthropic

```

```bash
bun add -d ai @ai-sdk/anthropic

```

--------------------------------

### Install @e2e-dev/github with npm

Source: https://e2e.tester.army/docs/github

Install the reporter as a dev dependency using npm.

```bash
npm install --save-dev @e2e-dev/github

```

--------------------------------

### Install WebKit browser in CI

Source: https://e2e.tester.army/docs/browser

Installs the extra browser in CI. The install command is shown for npm, pnpm, and bun package managers.

```bash
npx @e2e-dev/web install webkit --with-deps

```

```bash
pnpm exec e2e-web install webkit --with-deps

```

```bash
bunx @e2e-dev/web install webkit --with-deps

```

--------------------------------

### Install @e2e-dev/limrun with npm, pnpm, or bun

Source: https://e2e.tester.army/docs/integrations/limrun

Install the integration alongside the mobile engine and its peers using npm, pnpm, or bun. The package manager alternatives are shown as separate commands.

```bash
npm install --save-dev e2e @e2e-dev/mobile @e2e-dev/limrun @limrun/api

```

```bash
pnpm add -D e2e @e2e-dev/mobile @e2e-dev/limrun @limrun/api

```

```bash
bun add -d e2e @e2e-dev/mobile @e2e-dev/limrun @limrun/api

```

--------------------------------

### Install the e2e skill with bun

Source: https://e2e.tester.army/docs/bug-bash

Install the e2e skill without using e2e init. Use this command in a bun project.

```bash
bunx skills add tester-army/e2e

```

--------------------------------

### e2e feedback examples (npm)

Source: https://e2e.tester.army/docs/reference/cli

Three example invocations using npm: a bug report, a docs report, and a feature request with --dry-run.

```bash
npx e2e feedback --type bug -m "list ignores --grep" --command "e2e list --grep checkout"
npx e2e feedback --type docs -m "The mcp topic never says how to close a session"
npx e2e feedback --type feature -m "Need a way to set the viewport per test" --dry-run

```

--------------------------------

### Install @ai-sdk/openai with bun

Source: https://e2e.tester.army/docs/decision-models

Install the OpenAI SDK package for using gpt-6-luna. Requires @ai-sdk/openai 4.0.90 or later and OPENAI_API_KEY.

```bash
bun add -d @ai-sdk/openai

```

--------------------------------

### Install and run e2e on iOS and Android (bun)

Source: https://e2e.tester.army/docs/ci

Commands to install the build on a booted simulator/emulator and run the e2e suite for both platforms. Assumes targets named 'ios' and 'android'.

```bash
# iOS
xcrun simctl install booted path/to/MyApp.app
bunx e2e run --target ios --reporter list,junit

# Android
adb install -r path/to/app.apk
bunx e2e run --target android --reporter list,junit

```

--------------------------------

### Install and run e2e on iOS and Android (npm)

Source: https://e2e.tester.army/docs/ci

Commands to install the build on a booted simulator/emulator and run the e2e suite for both platforms. Assumes targets named 'ios' and 'android'.

```bash
# iOS
xcrun simctl install booted path/to/MyApp.app
npx e2e run --target ios --reporter list,junit

# Android
adb install -r path/to/app.apk
npx e2e run --target android --reporter list,junit

```

--------------------------------

### Install @ai-sdk/openai with pnpm

Source: https://e2e.tester.army/docs/decision-models

Install the OpenAI SDK package for using gpt-6-luna. Requires @ai-sdk/openai 4.0.90 or later and OPENAI_API_KEY.

```bash
pnpm add -D @ai-sdk/openai

```

--------------------------------

### e2e feedback examples (bun)

Source: https://e2e.tester.army/docs/reference/cli

Three example invocations using bun: a bug report, a docs report, and a feature request with --dry-run.

```bash
bunx e2e feedback --type bug -m "list ignores --grep" --command "e2e list --grep checkout"
bunx e2e feedback --type docs -m "The mcp topic never says how to close a session"
bunx e2e feedback --type feature -m "Need a way to set the viewport per test" --dry-run

```

--------------------------------

### Install e2e skill with npm

Source: https://e2e.tester.army/docs/coding-agents

Run this command to install the e2e skill using npm. It copies SKILL.md and topic references to the skill directory.

```bash
npx e2e init

```

--------------------------------

### Install the e2e skill with npm

Source: https://e2e.tester.army/docs/bug-bash

Install the e2e skill without using e2e init. Use this command in an npm project.

```bash
npx skills add tester-army/e2e

```

--------------------------------

### Install and run e2e on iOS and Android (pnpm)

Source: https://e2e.tester.army/docs/ci

Commands to install the build on a booted simulator/emulator and run the e2e suite for both platforms. Assumes targets named 'ios' and 'android'.

```bash
# iOS
xcrun simctl install booted path/to/MyApp.app
pnpm exec e2e run --target ios --reporter list,junit

# Android
adb install -r path/to/app.apk
pnpm exec e2e run --target android --reporter list,junit

```

--------------------------------

### e2e feedback examples (pnpm)

Source: https://e2e.tester.army/docs/reference/cli

Three example invocations using pnpm: a bug report, a docs report, and a feature request with --dry-run.

```bash
pnpm exec e2e feedback --type bug -m "list ignores --grep" --command "e2e list --grep checkout"
pnpm exec e2e feedback --type docs -m "The mcp topic never says how to close a session"
pnpm exec e2e feedback --type feature -m "Need a way to set the viewport per test" --dry-run

```

--------------------------------

### Install e2e skill with pnpm

Source: https://e2e.tester.army/docs/coding-agents

Run this command to install the e2e skill using pnpm. It copies SKILL.md and topic references to the skill directory.

```bash
pnpm dlx e2e init

```

--------------------------------

### Dialog handling and download waiting example

Source: https://e2e.tester.army/docs/reference/web

Shows how to handle a dialog with onDialog and wait for a download with waitForDownload. The download trigger is a function that starts the download; if no download starts, an error is thrown.

```typescript
const off = await browser.onDialog('accept');
await screen.getByRole('button', 'Delete').tap();
await off();

const file = await browser.waitForDownload(() =>
  screen.getByRole('link', 'Export CSV').tap(),
);

```

--------------------------------

### Maestro flow example

Source: https://e2e.tester.army/docs/migrate/maestro

A Maestro flow that launches the app with clearState, taps through the UI, inputs an email, and asserts visibility. This is the starting point for migration.

```yaml
appId: com.example.app
---
- launchApp:
    clearState: true
- tapOn: "Get started"
- tapOn:
    id: "email"
- inputText: "ada@example.test"
- tapOn: "Continue"
- assertVisible: "Check your inbox"
- scrollUntilVisible:
    element: "Resend"
- assertVisible:
    id: "resend"

```

--------------------------------

### test.setup(title, options, fn)

Source: https://e2e.tester.army/docs/reference/test

Registers one setup test with statically declared session outputs.

```APIDOC
## test.setup(title, options, fn)

### Description
Registers one setup test with statically declared session outputs.

### Method
Function call

### Signature
`test.setup(title: string, options: SetupOptions, fn: SetupFn<Fixtures>): TestCase`

### Parameters
- **title** (string) - Required - The test title.
- **options** (SetupOptions) - Required - Setup options.
- **fn** (SetupFn<Fixtures>) - Required - The setup function.

### Returns
- **TestCase** - The registered test case.

### Errors
- Throws `COLLECTION_ERROR` if called outside module evaluation.
- Throws `COLLECTION_ERROR` if title is not 1-512 UTF-8 bytes after NFC normalization, or contains a NUL character.
- Throws `COLLECTION_ERROR` if two tests in one file have the same title path.
```

--------------------------------

### Restore saved session in a test

Source: https://e2e.tester.army/docs/authentication

Use the session option to start the test already signed in as admin. The runner runs the required setup test even when only this test is selected.

```TypeScript
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';

test('the dashboard opens directly', { session: 'admin' }, async ({ app, screen, browser }) => {
  await app.open('/dashboard');

  await expect(browser).toHaveURL('/dashboard');
  await expect(screen.getByRole('status', 'Greeting')).toHaveText(
    'Welcome back, admin!',
  );
});

```

--------------------------------

### Scaffold e2e project with npx

Source: https://e2e.tester.army/docs/reference/cli

Run `npx e2e init --yes` to scaffold a project non-interactively using the Web engine and Vercel AI Gateway, installing skill and MCP config in both locations and skipping dependency installation.

```bash
npx e2e init --yes

```

--------------------------------

### Basic API test with fetch and toMatchSchema

Source: https://e2e.tester.army/docs/api-testing

Example test that calls GET /api/users and validates the response status, content-type, and body schema. Uses Zod for schema validation and expects three users with specific names.

```TypeScript
import { test, expect } from 'e2e';
import { z } from 'zod';

const User = z.object({ id: z.number(), name: z.string() });

test('GET /api/users returns the seeded users', async ({ app }) => {
  const response = await fetch(new URL('/api/users', app.baseUrl));
  expect(response.status).toBe(200);
  expect(response.headers.get('content-type')).toContain('application/json');
  const users = expect(await response.json()).toMatchSchema(z.array(User));
  expect(users).toHaveLength(3);
  expect(users.map((user) => user.name)).toEqual(['Ada', 'Grace', expect.any(String)]);
});

```

--------------------------------

### Configure hosted devices with hostedDevices

Source: https://e2e.tester.army/docs/mobile

Sets the `device` option to a `DeviceProvider` from a service like EAS Simulators. The provider leases one device per worker slot at run start and releases it at run end. The example uses `hostedDevices` with a service URL and image.

```typescript
mobile({
  platform: 'ios',
  device: hostedDevices({ serviceUrl: 'https://devices.example.com', image: 'ios-18-iphone-17' }),
})

```

--------------------------------

### e2e.config.ts: defining agents with models, system, context, and executor

Source: https://e2e.tester.army/docs/reference/config

Example e2e.config.ts that defines multiple agents: default, ux, thorough, buyer, and house (with a custom executor). Each agent starts from built-in defaults and does not inherit from others. With executor, system and tools are INVALID_CONFIG; model, judge, context, and budgets still apply.

```typescript
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { gateway } from 'ai';
import { houseBrain } from './house-brain.ts';

export default {
  targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
  agents: {
    default: { model: gateway('openai/gpt-6-luna-fast') },
    ux: { model: gateway('openai/gpt-6-luna-fast'), system: 'Check labels, contrast, and keyboard access.' },
    thorough: { model: gateway('anthropic/claude-opus-5'), context: 'Verify every claim on screen.' },
    buyer: {
      model: gateway('openai/gpt-6-luna-fast'),
      system: 'You are a first-time buyer.',
      context: 'Plans are called tiers. Billing lives under Settings.',
      maxSteps: 40,
    },
    house: { executor: houseBrain, model: gateway('openai/gpt-6-luna-fast'), maxModelCalls: 10 },
  },
} satisfies E2EConfig;

```

--------------------------------

### Scaffold e2e project with bunx

Source: https://e2e.tester.army/docs/reference/cli

Run `bunx e2e init --yes` to scaffold a project using bun's package runner.

```bash
bunx e2e init --yes

```

--------------------------------

### Define a custom fixture with test.extend and use it in a test

Source: https://e2e.tester.army/docs/reference/test

Defines a custom `workspace` fixture with `test.extend(fixtures)` from '@e2e-dev/web'. Setup runs before `await use(value)`, the test body runs while `use` is pending, and teardown runs after the body even on failure. The example also shows a test using the fixture and the `screen` fixture.

```typescript
import { test as base } from '@e2e-dev/web';

export const test = base.extend<{ workspace: Workspace }>({
  workspace: async ({ browser }, use) => {
    const workspace = await createWorkspace();
    await signIn(browser, workspace);
    await use(workspace); // the hooks and the body run here
    await workspace.cleanup(); // teardown, after the body even when it failed
  },
});

test('renames the workspace', async ({ workspace, screen }) => {
  await screen.getByLabel('Name').fill(`${workspace.name} (renamed)`);
});
```

--------------------------------

### bunx e2e run examples

Source: https://e2e.tester.army/docs/reference/cli

Shows the same e2e run commands but using bunx instead of pnpm, demonstrating the CLI is package-manager agnostic.

```bash
bunx e2e run
bunx e2e run tests/signup.e2e.ts --tag smoke
bunx e2e run tests/signup.e2e.ts:12
bunx e2e run tests/agent
bunx e2e run 'tests/**/*.smoke.e2e.ts'
bunx e2e run --target web,webkit --tag smoke,billing --tag-mode all
bunx e2e run --tag smoke --exclude-tag slow
bunx e2e run --grep checkout --grep-invert '/refund/i'
bunx e2e run --last-failed
bunx e2e run --shard 2/3
bunx e2e run --reporter json --workers 4 --retries 2
bunx e2e run --max-failures 3
bunx e2e run --repeat-each 5 --no-cache tests/checkout.e2e.ts
bunx e2e run --reporter list,junit
```

--------------------------------

### Install browsers with npx @e2e-dev/web install chromium --with-deps

Source: https://e2e.tester.army/docs/reference/web

Installs the Chromium browser with system dependencies for the pinned Playwright version. Use in CI or container images. Name any of chromium, firefox, or webkit; with none named it installs chromium. --with-deps also installs Linux system libraries. Exits with the installer's exit code.

```Shell
npx @e2e-dev/web install chromium --with-deps

```

--------------------------------

### Install browsers with bunx @e2e-dev/web install chromium --with-deps

Source: https://e2e.tester.army/docs/reference/web

Installs the Chromium browser with system dependencies using bun. Same behavior as the npx command: installs chromium by default, --with-deps adds Linux system libraries, and exits with the installer's exit code.

```Shell
bunx @e2e-dev/web install chromium --with-deps

```

--------------------------------

### Install browsers with pnpm exec e2e-web install chromium --with-deps

Source: https://e2e.tester.army/docs/reference/web

Installs the Chromium browser with system dependencies using pnpm. Same behavior as the npx command: installs chromium by default, --with-deps adds Linux system libraries, and exits with the installer's exit code.

```Shell
pnpm exec e2e-web install chromium --with-deps

```

--------------------------------

### SetupOptions

Source: https://e2e.tester.army/docs/reference/test

Options for defining a setup test, extending TestOptions but omitting 'session', 'only', 'skip', and 'agent', and requiring 'sessions'.

```APIDOC
## SetupOptions

### Description
Options for defining a setup test. Extends TestOptions but omits `session`, `only`, `skip`, and `agent`, and requires `sessions`.

### Fields
- **sessions** (readonly string[]) - Required - Session names this setup test MUST save.
- **agent** (string) - Optional - A setup test runs once per target, so it pins at most one agent.
- All other fields from TestOptions except `session`, `only`, `skip`, and `agent`.

### Validation Rules
- `test.setup` requires `sessions` to be a static, non-empty array of unique names.
```

--------------------------------

### Web e2e GitHub Actions workflow (.github/workflows/e2e.yml)

Source: https://e2e.tester.army/docs/ci/github-actions

Runs deterministic and agent tests in one job on ubuntu-latest. Assumes a config command starts the app and uses AI Gateway for model calls. The model key and user credentials come from repository secrets. The workflow installs browsers, runs tests with npx e2e, and uploads report and artifacts.

```yaml
name: e2e

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - uses: pnpm/action-setup@9fd676a19091d4595eefd76e4bd31c97133911f1 # v4.2.0
      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: 26
          cache: pnpm
      - run: pnpm install --frozen-lockfile

      - name: Install browsers
        run: pnpm exec e2e-web install chromium --with-deps

      - name: Run e2e
        run: npx e2e run --reporter list,junit
        env:
          APP_URL: http://127.0.0.1:3000
          AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
          E2E_USER_ADMIN_USERNAME: ${{ secrets.E2E_USER_ADMIN_USERNAME }}
          E2E_USER_ADMIN_PASSWORD: ${{ secrets.E2E_USER_ADMIN_PASSWORD }}

      - name: Upload report
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: e2e-report
          path: |
            .e2e/report.json
            .e2e/junit.xml
          if-no-files-found: warn

      - name: Upload artifacts
        if: ${{ !cancelled() }}
        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
        with:
          name: e2e-artifacts
          path: .e2e/results
          if-no-files-found: warn
          retention-days: 7

```

--------------------------------

### test.beforeAll(fn)

Source: https://e2e.tester.army/docs/reference/test

Registers a suite-instance setup hook.

```APIDOC
## test.beforeAll(fn)

### Description
Registers a suite-instance setup hook.

### Method
Function call

### Signature
`test.beforeAll(fn: SuiteHookFn): void`

### Parameters
- **fn** (SuiteHookFn) - Required - The hook function.

### Returns
- **void** - No return value.

### Errors
- Throws `COLLECTION_ERROR` if called outside module evaluation.
```

--------------------------------

### Start signed in with bun

Source: https://e2e.tester.army/docs/explore

Runs `e2e explore` with a session name using bun. Same behavior as the npx version.

```bash
bunx e2e explore --session admin 'Explore the admin settings and find bugs'

```

--------------------------------

### e2e login examples (npm)

Source: https://e2e.tester.army/docs/reference/cli

Shows the e2e login command using npx for various providers and options. Use --device for ChatGPT device code, --from-gh to reuse GitHub CLI login, and --client-id with optional --enterprise-url for GitHub Copilot.

```bash
npx e2e login openai              # ChatGPT, browser sign-in
npx e2e login openai --device     # sign in with a device code
npx e2e login github-copilot --from-gh  # use your GitHub CLI login
npx e2e login github-copilot --client-id <id> [--enterprise-url <host>]
npx e2e login opencode-console    # OpenCode Console, device code
npx e2e login spacexai            # SuperGrok, device code
npx e2e login                     # choose a provider
```

--------------------------------

### openHost

Source: https://e2e.tester.army/docs/reference/runner

Prepares e2e for a test runner by initializing the target engine, starting app processes, and returning an E2EHost instance. Accepts optional OpenHostOptions and returns a Promise<E2EHost<Fixtures>>.

```APIDOC
## openHost

### Description
Prepares e2e for Playwright Test, Vitest, Jest, or a custom harness. Initializes the target's engine, starts app processes, and returns an E2EHost instance. The host is worker-scoped and manages the engine lifecycle.

### Method
openHost

### Endpoint
openHost<Fixtures>(options?: OpenHostOptions): Promise<E2EHost<Fixtures>>

### Parameters
#### Options
- **config** (string | E2EConfig) - Optional - Config file path relative to cwd, or an E2EConfig value. Defaults to nearest e2e.config.ts or e2e.config.mts.
- **cwd** (string) - Optional - Directory for config discovery and project root of a config value. Defaults to process.cwd().
- **target** (string) - Optional - Target name; required when the config declares several targets. Defaults to the only target.
- **env** (NodeJS.ProcessEnv) - Optional - Environment the config, engines, and providers read. Defaults to process.env.
- **signal** (AbortSignal) - Optional - Cancels host provisioning, a pending session open, or live fixture calls.
- **headed** (boolean) - Optional - Runs a browser engine headed. Defaults to false.
- **onNotice** (function) - Optional - Progress outside a step, such as provisioning or an app process.

### Request Example
```typescript
const host = await openHost<Fixtures>({ target: 'android' });
```

### Response
#### Success Response
Returns a Promise that resolves to an E2EHost<Fixtures> instance.

#### Response Example
```typescript
const host: E2EHost<Fixtures> = await openHost<Fixtures>({ target: 'android' });
```

### Error Handling
If opening fails, e2e tears down what started before throwing the error.
```

--------------------------------

### pnpm exec e2e-web install webkit --with-deps

Source: https://e2e.tester.army/docs/browser

Installs an extra browser using pnpm.

```APIDOC
## pnpm exec e2e-web install webkit --with-deps

### Description
Installs the specified browser with dependencies using pnpm.

### Method
CLI command

### Parameters
- **browser** (string) - Required - The browser name to install (e.g., 'webkit').
- **--with-deps** (flag) - Optional - Installs system dependencies.

### Request Example
```bash
pnpm exec e2e-web install webkit --with-deps
```

### Response
No response; command output.
```

--------------------------------

### test.setup(name, options, fn)

Source: https://e2e.tester.army/docs/reference/test

Declares a setup test that saves sessions for use by other tests. Must be top-level and save each declared session exactly once.

```APIDOC
## test.setup(name, options, fn)

### Description
Declares a setup test that saves sessions for use by other tests. Must be top-level and save each declared session exactly once.

### Method
N/A (SDK function)

### Endpoint
N/A

### Parameters
- **name** (string) - Required - The name of the setup test.
- **options** (object) - Required - Options for the setup test.
  - **sessions** (string[]) - Required - The names of sessions to save.
- **fn** (function) - Required - The test body, receives an object with `app`, `screen`, `session`.

### Request Example
```js
import { credentials } from 'e2e';

test.setup('authenticate', { sessions: ['member'] }, async ({ app, screen, session }) => {
  await app.open('/login');
  await screen.getByLabel('Email').fill(credentials.user('member').username);
  await screen.getByLabel('Password').fill(credentials.user('member').password);
  await screen.getByRole('button', 'Sign in').tap();
  await session.save('member');
});
```

### Response
No return value.
```

--------------------------------

### Start a bug bash

Source: https://e2e.tester.army/docs/bug-bash

Give this prompt to your coding agent to start a bug bash on the current branch.

```text
Bug bash the checkout and account settings on this branch.

```

--------------------------------

### npx @e2e-dev/web install webkit --with-deps

Source: https://e2e.tester.army/docs/browser

Installs an extra browser (e.g., webkit) in CI environments.

```APIDOC
## npx @e2e-dev/web install webkit --with-deps

### Description
Installs the specified browser with dependencies for CI usage.

### Method
CLI command

### Parameters
- **browser** (string) - Required - The browser name to install (e.g., 'webkit').
- **--with-deps** (flag) - Optional - Installs system dependencies.

### Request Example
```bash
npx @e2e-dev/web install webkit --with-deps
```

### Response
No response; command output.
```

--------------------------------

### e2e login examples (bun)

Source: https://e2e.tester.army/docs/reference/cli

Shows the e2e login command using bunx for various providers and options. Use --device for ChatGPT device code, --from-gh to reuse GitHub CLI login, and --client-id with optional --enterprise-url for GitHub Copilot.

```bash
bunx e2e login openai              # ChatGPT, browser sign-in
bunx e2e login openai --device     # sign in with a device code
bunx e2e login github-copilot --from-gh  # use your GitHub CLI login
bunx e2e login github-copilot --client-id <id> [--enterprise-url <host>]
bunx e2e login opencode-console    # OpenCode Console, device code
bunx e2e login spacexai            # SuperGrok, device code
bunx e2e login                     # choose a provider
```

--------------------------------

### Initialize e2e project with npx, pnpm, or bun

Source: https://e2e.tester.army/docs/quickstart

Initializes a new e2e test project. The wizard asks a few questions, then shows every change before writing anything. It keeps existing files.

```bash
npx e2e init

```

```bash
pnpm dlx e2e init

```

```bash
bunx e2e init

```

--------------------------------

### Install @e2e-dev/eas with bun

Source: https://e2e.tester.army/docs/integrations/eas

Installs the EAS Simulators provider as a dev dependency using bun. No SDK is required.

```bash
bun add -d @e2e-dev/eas

```

--------------------------------

### Sign in once in a setup test and save session

Source: https://e2e.tester.army/docs/authentication

Use test.setup with the sessions option to authenticate as admin and save the session. The runner executes this setup when needed. Assert the URL and a signed-in element before calling session.save() because session.save() does not verify sign-in success.

```TypeScript
import { test } from '@e2e-dev/web';
import { expect, credentials } from 'e2e';

test.setup('authenticate as admin', { sessions: ['admin'] }, async ({ app, screen, session, browser }) => {
  const admin = credentials.user('admin');

  await app.open('/login');
  await screen.getByLabel('Username').fill(admin.username);
  await screen.getByLabel('Password').fill(admin.password);
  await screen.getByRole('button', 'Sign in').tap();

  await expect(browser).toHaveURL('/dashboard');
  await expect(screen.getByRole('status', 'Greeting')).toContainText('admin');

  await session.save('admin');
});

```

--------------------------------

### Install @e2e-dev/eas with pnpm

Source: https://e2e.tester.army/docs/integrations/eas

Installs the EAS Simulators provider as a dev dependency using pnpm. No SDK is required.

```bash
pnpm add -D @e2e-dev/eas

```

--------------------------------

### Install @e2e-dev/eas with npm

Source: https://e2e.tester.army/docs/integrations/eas

Installs the EAS Simulators provider as a dev dependency using npm. No SDK is required.

```bash
npm install --save-dev @e2e-dev/eas

```

--------------------------------

### e2e explore usage examples (npm)

Source: https://e2e.tester.army/docs/reference/cli

Run exploratory tests with the e2e CLI via npx. The first command runs with defaults; the second adds a prompt; the third specifies target, max steps, and headed mode; the fourth uses a thorough agent and video recording.

```bash
npx e2e explore
npx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'
npx e2e explore --target web --max-steps 4 --headed
npx e2e explore 'Hunt for broken forms and dead links' --agent thorough --video

```

--------------------------------

### Install @ai-sdk/openai with npm

Source: https://e2e.tester.army/docs/decision-models

Install the OpenAI SDK package for using gpt-6-luna. Requires @ai-sdk/openai 4.0.90 or later and OPENAI_API_KEY.

```bash
npm install -D @ai-sdk/openai

```

--------------------------------

### agent.extract usage example

Source: https://e2e.tester.army/docs/reference/agent

Example call to extract that retrieves the workspace name and plan, using a zod schema for validation.

```javascript
const summary = await agent.extract('the workspace name and plan', {
  schema: z.object({ name: z.string(), plan: z.string() }),
});

```