e2e

https://e2e.tester.army/docs
Admin
e2e is an open-source testing framework for web and mobile applications that combines exact locators...
Tokens:276,670
Snippets:1,617
Trust Score:5.4
Update:1 week ago
Show doc for...
Tokens:
Raw
### 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 @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 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

```

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

### 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(),
);

```

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

### 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 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);
```

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

### 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"

```

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

### 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;

```

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

### 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!',
  );
});

```

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

### 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

```

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

### 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)]);
});

```

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

### 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

```

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

### 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)`);
});
```

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

### 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

```

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

### 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 @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

```

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

### 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

```

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

### 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

```

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

### 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.
```

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

### 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

```
Tokens:
Raw