> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e2b.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# e2e with E2B

> Run e2e end-to-end tests on Android and in Chromium, with one E2B sandbox for each test worker.

[e2e](https://github.com/e2e-inc/e2e) is an open-source runner for end-to-end tests. A test can use scripted steps, agent steps where a model works toward a goal, or both. The [`@e2e-dev/e2b`](https://www.npmjs.com/package/@e2e-dev/e2b) package runs the app under test in E2B sandboxes:

* `e2b()` gives each test worker an Android 16 sandbox from the [`android-16`](https://docs.e2b.dev/use-cases/android) template, with your `.apk` installed.
* `e2bBrowsers()` gives each test worker a Chromium sandbox.

Your tests stay the same as on a local device or browser, and the runner deletes the sandboxes when the run ends.

## Install

e2e needs Node.js 22 (22.22.3 or later) or Node.js 24.8.0 or later. Install the runner, the E2B package, and the engine for your target: `@e2e-dev/mobile` for Android, `@e2e-dev/web` for the browser.

```bash theme={"theme":"css-variables"}
npm install --save-dev e2e @e2e-dev/e2b e2b @e2e-dev/mobile @e2e-dev/web
```

Set `E2B_API_KEY` ([get one](https://e2b.dev/dashboard?tab=keys)) in the environment that starts e2e.

```bash theme={"theme":"css-variables"}
export E2B_API_KEY=e2b_...
```

## Run Android tests

You do not need the Android SDK, an emulator, or `adb` on your machine. Set the `device` of the mobile engine to `e2b()` and point `appPath` at your `.apk`.

```typescript e2e.config.ts theme={"theme":"css-variables"}
import type { E2EConfig } from 'e2e'
import { mobile } from '@e2e-dev/mobile'
import { e2b } from '@e2e-dev/e2b'

export default {
  targets: [
    {
      name: 'android',
      engine: mobile({ platform: 'android', device: e2b() }),
      app: { appPath: 'build/app-debug.apk' },
    },
  ],
  workers: 4,
} satisfies E2EConfig
```

Write a test.

```typescript tests/login.e2e.ts theme={"theme":"css-variables"}
import { expect } from 'e2e'
import { test } from '@e2e-dev/mobile'

test('signs in', async ({ app, screen }) => {
  await app.open()
  await screen.getByRole('button', 'Sign in').click()
  await expect(screen.getByText('Welcome')).toBeVisible()
})
```

Run it.

```bash theme={"theme":"css-variables"}
npx e2e run
```

Each worker gets its own Android sandbox, ready with your app installed in about 15 to 45 seconds. `workers` is the upper limit: a run with one test file uses one worker.

## Run web tests

The browser provider needs a sandbox template with Chromium. Build it one time for each E2B team, from the Playwright image. Use the image tag of the Playwright version that your `@e2e-dev/web` uses.

```typescript build-template.ts theme={"theme":"css-variables"}
import { Template, defaultBuildLogger } from 'e2b'

const template = Template().fromImage('mcr.microsoft.com/playwright:v1.65.0-noble')

await Template.build(template, 'e2e-chromium', {
  cpuCount: 4,
  memoryMB: 4096,
  onBuildLogs: defaultBuildLogger(),
})
```

```bash theme={"theme":"css-variables"}
node build-template.ts
```

Set the `browser` of the web engine to `e2bBrowsers()`.

```typescript e2e.config.ts theme={"theme":"css-variables"}
import type { E2EConfig } from 'e2e'
import { web } from '@e2e-dev/web'
import { e2bBrowsers } from '@e2e-dev/e2b/web'

export default {
  targets: [
    {
      name: 'web',
      engine: web({ browser: e2bBrowsers() }),
      app: { url: 'https://staging.example.com' },
    },
  ],
  workers: 4,
} satisfies E2EConfig
```

Run it.

```bash theme={"theme":"css-variables"}
npx e2e run
```

> [!NOTE]
>
> The browser runs in E2B's cloud, so `app.url` must be reachable from the internet. A server on `localhost` on your machine is not.

## Add agent steps

An agent step gives a model a goal instead of a script. The model works on the app in the sandbox, and a scripted assertion can check the result. Install the [AI SDK](https://ai-sdk.dev) and a model provider, and set the provider's API key.

```bash theme={"theme":"css-variables"}
npm install --save-dev ai @ai-sdk/anthropic
export ANTHROPIC_API_KEY=sk-ant-...
```

Add `agents` to your config. Keep your `targets`.

```typescript e2e.config.ts theme={"theme":"css-variables"}
import type { E2EConfig } from 'e2e'
import { anthropic } from '@ai-sdk/anthropic'

export default {
  // targets: [...]
  agents: { default: { model: anthropic('claude-haiku-5-5') } },
} satisfies E2EConfig
```

Use the `agent` fixture in a test. This test needs a web target with `url: 'https://en.wikipedia.org'`.

```typescript tests/search.e2e.ts theme={"theme":"css-variables"}
import { expect, test } from 'e2e'

test('finds an article', async ({ agent, app, screen }) => {
  await app.open()
  await agent.act('Search for "Firecracker (software)" and open that article.')
  await expect(screen.getByRole('heading', { name: 'Firecracker (software)', level: 1 })).toBeVisible()
})
```

## Options

Both providers accept these options.

| Option | Default | What it does |
| - | - | - |
| `template` | `'android-16'` for `e2b()`, `'e2e-chromium'` for `e2bBrowsers()` | The sandbox template. |
| `timeoutMs` | `3600000` (1 hour) | The sandbox lifetime. E2B kills the sandbox after it, even when the run still uses it. |

`e2bBrowsers()` also accepts `scope`. The default, `'worker'`, keeps one sandbox per worker for the run. `'attempt'` creates a new sandbox for every test attempt.

For a dedicated E2B cluster, set `E2B_DOMAIN`.

## How it works

1. **One sandbox per worker**: when the run starts, the provider creates a sandbox for each worker and target. On Android, it installs your `.apk`. On the web, it starts Chromium.
2. **Private by default**: the provider creates each sandbox with public traffic turned off. The runner reaches it through a tunnel on `127.0.0.1` that adds the E2B access token, so the device and the browser are not open to the internet.
3. **Cleanup**: the runner deletes the sandboxes when the run ends. If the runner is killed first, E2B deletes them when `timeoutMs` ends.

## Limitations

* E2B has no iOS sandboxes, so `e2b()` refuses an iOS target.
* Android on E2B is x86\_64 only, has no Google Play Services, and renders in software. Apps with native libraries need x86\_64 builds.
* The provider installs an `.apk`, not an `.aab`.
* A sandbox is billed while it runs. Android sandboxes and worker-scope browser sandboxes run from the start of the run to its end.

## Related guides

> [card] [Android and Chromium example](https://github.com/e2b-dev/e2b-cookbook/tree/main/examples/e2e-android-web-tests-js)
>
> The game 2048 on Android and Wikipedia in Chromium, with scripted tests and agent tests

> [card] [Run Android](https://docs.e2b.dev/use-cases/android.md)
>
> What is in the `android-16` template and how to drive it with `adb`

> [card] [Templates](https://docs.e2b.dev/template/quickstart.md)
>
> Build your own sandbox templates

> [card] [e2e integration guide](https://e2e.com/docs/integrations/e2b)
>
> All options of `e2b()` and `e2bBrowsers()` in the e2e documentation
