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

# Notte browsers

> Run web targets in Notte's cloud browsers with the notte() browser provider from @e2e-dev/notte.

`notte()` from `@e2e-dev/notte` is a
[browser provider](https://e2e.com/docs/browser#hosted-browsers) for [Notte](https://notte.cc).
Each test attempt gets its own cloud browser session. Tests stay the same.
Only the target's `browser` changes.

## Setup

Install the provider and the Notte SDK:

<CodeGroup>
```bash npm
npm install --save-dev @e2e-dev/notte notte-sdk
```

```bash pnpm
pnpm add -D @e2e-dev/notte notte-sdk
```

```bash bun
bun add -d @e2e-dev/notte notte-sdk
```
</CodeGroup>

Set the target's `browser` to `notte()`:

```ts title="e2e.config.ts"

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

Set `NOTTE_API_KEY` in the environment that `e2e run` starts in, such as a
CI secret. Copy the key from the [Notte console](https://console.notte.cc/apikeys).
`workers` sets how many sessions run at the same time. The app must be
reachable from the cloud browser, so point `app.url` at a deployed or
tunneled URL, not `localhost`.

Without the key, or on a Notte error, the attempt fails with that message.

## Options

`notte(options)` takes Notte's start-session body as it is:
`solve_captchas`, `proxies`, `browser_type`, `idle_timeout_minutes`,
`max_duration_minutes`, `viewport_width` and `viewport_height`, `profile`,
`user_agent`, `extra_http_headers`, `block_ads`, and the rest of
`ApiSessionStartRequest` in your `notte-sdk`:

```ts
web({
  browser: notte({ solve_captchas: true, proxies: true, idle_timeout_minutes: 5 }),
})
```

`cdp_url` and the managed authentication fields (`auth_ids`, `auth_retry`,
`wait_for_authentication`) are left out: the first names a browser from
another provider, and the others return a session before it can be
attached to.

## One session per attempt

The provider leases in `attempt` scope only. A Notte session owns its one
browser context and refuses new ones, which `worker` scope needs to keep
tests apart. Each attempt, retries included, runs in a fresh session's
default context, on its first tab. Each test pays for a session start,
and the [limits of a per-attempt lease](https://e2e.com/docs/browser#hosted-browsers) apply,
sessions included.

## Watch and clean up sessions

The reporter logs `session <id>, watch at <console URL>` for each new
session. The link opens the session in the Notte console, live while the
test runs and as a replay after it ends. It needs a console sign-in, so it
is safe in public CI logs. With `NOTTE_API_URL` set, the reporter logs
`session <id>` alone, since the provider can't tell which console serves
that API.

When an attempt ends, on every exit path, the provider stops its session.
When the run ends, it stops the session of any worker that died before it
could. If the run itself dies, Notte closes each session after
`idle_timeout_minutes` without activity, 3 by default. Notte also ends every
session after `max_duration_minutes`, 15 by default, so raise it for a test
that runs longer.

## Downloads

`browser.waitForDownload` works as it does locally. Notte keeps each file
the browser downloads in the session's file storage, under the name the site
suggested, and the provider copies the file of that name into the attempt's
artifacts.

## Differences from a local browser

- Notte answers JavaScript dialogs itself: `confirm` returns `false` and
  `prompt` returns `null` before a test's dialog handler can accept them.
- The browser takes Windows key combinations. `ControlOrMeta` follows the
  runner's system, so on a Mac it sends `Meta`, which the browser ignores:
  write `Control+A` for a test that also runs from a Mac.
- `setInputFiles` uploads files up to 50 MB, and no folders.
- The app must be reachable from Notte's cloud, so `localhost` addresses
  don't load. Point `app.url` at a deployed or tunneled URL.
- `app.clearState()` and saved [sessions](https://e2e.com/docs/authentication) are unavailable,
  as in any per-attempt lease. Every attempt already starts on a fresh
  session.

## Next

<CardGroup cols={2}>
  <Card title="Hosted browsers" icon="globe" href="/browser#hosted-browsers">
    How a browser provider leases browsers, and the limits of `'attempt'` scope.
  </Card>
  <Card title="Continuous integration" icon="rotate" href="/ci">
    Run the suite on GitHub Actions or another CI service.
  </Card>
</CardGroup>
