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

# Introduction

> End-to-end tests in plain TypeScript, with agent steps you can bound and inspect.

e2e runs end-to-end tests written in TypeScript. A test mixes two kinds of
calls. Deterministic calls (`screen`, `app`, `expect`) do exactly what they
say and cost no model tokens. Agent calls (`agent.act`, `agent.assert`) hand
one goal or one question to a model under a deadline and a call budget.

```ts title="tests/checkout.e2e.ts" theme={"theme":"catppuccin-mocha"}
import { test, expect } from '@e2edev/e2e';

test('a member upgrades to Pro', async ({ app, agent, screen }) => {
  await app.open('/settings/billing');

  await agent.act('upgrade the workspace to the Pro plan');
  await agent.assert('the invoice preview shows a prorated amount');

  await expect(screen.getByRole('status')).toContainText('Pro');
});
```

The runner owns everything around the model: what it sees, what it may do,
how many calls it gets, and what ends up in the report. You choose the model
and can replace the agent outright.

```ts title="e2e.config.ts" theme={"theme":"catppuccin-mocha"}
import type { E2EConfig } from '@e2edev/e2e';
import { createAgent } from '@e2edev/e2e/agent';
import { playwright } from '@e2edev/playwright';
import { gateway } from 'ai';

export default {
  targets: [{ engine: playwright({ url: 'http://localhost:3000' }) }],
  agents: { default: createAgent({ model: gateway('openai/gpt-5.6-luna') }) },
} satisfies E2EConfig;
```

## What you get

* **Bounded agent steps.** Every `agent.*` call has a deadline and a model-call
  budget, and ends in a verdict: passed, failed, or blocked.
* **Secrets the model never sees.** A password is an opaque handle. The model
  gets its name; the runner fills the field.
* **Replay instead of re-thinking.** In read-write cache mode, an `agent.act`
  followed by a recorded verification can save its actions. Later runs replay
  them with no model call until the app diverges.
* **One contract, any surface.** `@e2edev/playwright` drives browsers and
  `@e2edev/agent-device` drives iOS simulators and Android emulators. Tests
  share the agent and locator APIs; setup follows the platform. A browser
  test opens a URL, while a device attempt starts in its configured app.
* **A report for every run.** `.e2e/report.json` carries results, steps, model
  usage, and the artifacts the selected engine captured. Playwright can add
  traces; device targets provide screenshots and optional video.

## Where to go

<CardGroup cols={2}>
  <Card title="Quickstart" href="/quickstart">
    Scaffold a project, run a browser test, add an agent step.
  </Card>

  <Card title="Writing tests" href="/writing-tests">
    Goals, checks, extraction, and the deterministic APIs.
  </Card>

  <Card title="Web" href="/starting-your-app">
    Start your dev server from the config, mock APIs, reach protected previews.
  </Card>

  <Card title="Mobile" href="/mobile">
    iOS simulators and Android emulators, the `device` fixture, what differs.
  </Card>
</CardGroup>

The **Guides** cover what every project needs after that: a model, signing
in, agents and personas, caching, debugging, CI. **Extend** is for changing
what the agent is or adding a new platform. The **Reference** tab has every
function, option, flag, and error code.