Files
e2e/docs/quickstart.mdx
T

272 lines
8.4 KiB
Plaintext

---
title: Quickstart
description: Set up e2e with one prompt to your coding agent, or step by step.
---
import { ModelProvider } from './snippets/model-provider.jsx';
import { SetupPrompt } from './snippets/setup-prompt-card.jsx';
export const setupPrompt = `Set up e2e end-to-end tests in this project. Docs: \`https://e2e.tester.army/docs/quickstart.md\`
1. Run \`npx e2e init --yes\` (or the pnpm or bun equivalent for this project). It writes a web config using Vercel AI Gateway, an example test, the e2e skill, and MCP config. It installs nothing yet.
2. Read the e2e skill (\`npx e2e guide\` prints it, \`npx e2e guide <topic>\` prints a topic) and follow it for every step below.
3. Point the target at this app. For a web app, set its URL and the command that starts its dev server. For an iOS or Android app, replace @e2e-dev/web with @e2e-dev/mobile and rewrite the example test for the mobile engine.
4. Ask me which model to use for agent steps: a ChatGPT, GitHub Copilot, OpenCode Console, or SuperGrok subscription, an API key, or a local model. Configure it with its provider package. If it needs a sign-in, give me the \`npx e2e login\` command and wait until I confirm.
5. Install dependencies, run the example test, and fix setup errors until it passes.
6. Write one test for the most important user flow in this app, run it, and iterate until it passes.`;
## Set up with your coding agent
Open Claude Code, Codex, Cursor, or another coding agent in your app's
directory and paste this prompt:
<SetupPrompt>
<Prompt description={setupPrompt} children={setupPrompt} actions={["copy", "cursor"]} />
</SetupPrompt>
The agent installs the [e2e skill](/coding-agents), so later prompts like
"add a test for checkout" or "why did this run fail" work without more setup.
<Note>
Use Node.js 24.8 or newer (22.22.3 or newer on Node.js 22). On Windows, run inside WSL. Mobile tests also
need Xcode with an iOS simulator runtime, or the Android SDK with an emulator.
</Note>
## Set up manually
### Run your first test
<Steps>
<Step title="Create the test project">
In your app's directory:
<CodeGroup>
```bash npm
npx e2e init
```
```bash pnpm
pnpm dlx e2e init
```
```bash bun
bunx e2e init
```
</CodeGroup>
Choose **Web (Playwright)** or **Mobile (iOS/Android)**, then a
subscription or model provider, or **None** for tests without AI. The
wizard writes a config and an example test, adds dependencies, and offers
to set up your coding agent. Existing files stay intact.
<Tabs>
<Tab title="Web">
Start your app's dev server at `http://localhost:3000`, or set its address
in `e2e.config.ts`. You can also [let e2e start it](/starting-your-app).
<Accordion title="Example web config and test">
This config uses Vercel AI Gateway. The wizard configures the provider you chose.
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { gateway } from 'ai';
export default {
agents: { default: { model: gateway('openai/gpt-6-luna-fast') } },
targets: [{ engine: web(), app: { url: 'http://localhost:3000' } }],
} satisfies E2EConfig;
```
```ts title="tests/example.e2e.ts"
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';
test('app opens', async ({ app, browser }) => {
await app.open('/');
await expect(browser.locator('body')).toBeVisible();
});
```
</Accordion>
</Tab>
<Tab title="Mobile">
Run `npx agent-device doctor` to check your setup. The example opens
Settings so you can try it before installing your own app. The wizard
chooses iOS on macOS and Android elsewhere.
<Accordion title="Example iOS config and test">
This config uses Vercel AI Gateway. For Android, the wizard sets
`platform: 'android'` and `app: { bundleId: 'com.android.settings' }`.
```ts title="e2e.config.ts"
import type { E2EConfig } from 'e2e';
import { mobile } from '@e2e-dev/mobile';
import { gateway } from 'ai';
export default {
agents: { default: { model: gateway('openai/gpt-6-luna-fast') } },
targets: [{ name: 'ios', engine: mobile({ platform: 'ios' }), app: { bundleId: 'Settings' } }],
workers: 1,
} satisfies E2EConfig;
```
```ts title="tests/example.e2e.ts"
import { test } from '@e2e-dev/mobile';
import { expect } from 'e2e';
test('Settings opens', async ({ app, screen }) => {
await app.open();
await expect(screen.getByRole('button', 'General')).toBeVisible();
});
```
</Accordion>
See [Testing iOS and Android](/mobile) to use your own app.
</Tab>
</Tabs>
</Step>
<Step title="Run the example">
<CodeGroup>
```bash npm
npx e2e run
```
```bash pnpm
pnpm exec e2e run
```
```bash bun
bunx e2e run
```
</CodeGroup>
e2e downloads a browser or boots the simulator or emulator, checks that
the app opens, and writes `.e2e/report.json`. No model calls yet, so no
sign-in or API key needed.
</Step>
</Steps>
### Use a subscription or API key
Connect the provider you chose in the wizard.
<Tabs>
<Tab title="Subscription">
Sign in to your existing plan. No API key needed.
| Subscription | Command |
| --- | --- |
| ChatGPT Plus or Pro | `npx e2e login openai` |
| GitHub Copilot | `npx e2e login github-copilot` |
| OpenCode Console (OpenCode Zen and OpenCode Go) | `npx e2e login opencode-console` |
| SuperGrok or X Premium+ | `npx e2e login spacexai` |
Copilot reuses your GitHub CLI login if available. See
[Subscriptions](/subscriptions) for details.
</Tab>
<Tab title="API key">
Select your provider. Install its package and set the variables it reads,
if any, in the terminal where you run e2e.
<ModelProvider show="select" />
<ModelProvider show="install" />
<ModelProvider show="env" />
Vercel AI Gateway reads `AI_GATEWAY_API_KEY`, or a
[Vercel OIDC token](/models#vercel-oidc-instead-of-a-key) in a project
linked with `vercel link`. OpenRouter reads `OPENROUTER_API_KEY`.
The wizard writes the config for Vercel AI Gateway, OpenRouter, and
OpenAI-compatible endpoints. For another provider, replace the model import
and `model` value in `e2e.config.ts`, and use `agent` as `agents.default`:
<ModelProvider show="model" />
See [Models](/models) for local models and more options.
</Tab>
</Tabs>
### Add an agent step
Give `agent.act` one goal per call, then check the result. Adapt the
example to a flow in your app:
<Tabs>
<Tab title="Web">
```ts title="tests/agent.e2e.ts"
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';
test('a visitor signs up for a trial', async ({ app, agent, screen }) => {
await app.open('/');
await agent.act('sign up for a free trial as {name} with email {email}', {
params: { name: 'Ada Lovelace', email: 'ada@example.test' },
});
await agent.assert('the welcome screen greets Ada by name');
await expect(screen.getByRole('status')).toContainText('trial');
});
```
</Tab>
<Tab title="Mobile (iOS)">
```ts title="tests/agent.e2e.ts"
import { test } from '@e2e-dev/mobile';
import { expect } from 'e2e';
test('the agent opens General', async ({ agent, app, device }) => {
await app.open();
await agent.act('open {section} settings', { params: { section: 'General' } });
await agent.assert('the General settings screen is showing');
await expect(device.locator('role=NavigationBar id=General')).toBeVisible();
});
```
`app.open()` launches the configured app fresh; without it, a test starts
where the previous one left the device. `device.locator` uses
[agent-device selectors](/mobile#the-device-fixture).
</Tab>
</Tabs>
`params` fill the goal's placeholders. `agent.assert` judges the screen;
`expect` checks an exact value.
<CodeGroup>
```bash npm
npx e2e run tests/agent.e2e.ts
```
```bash pnpm
pnpm exec e2e run tests/agent.e2e.ts
```
```bash bun
bunx e2e run tests/agent.e2e.ts
```
</CodeGroup>
Chose **None** in the wizard? [Add a model](/models) first. Add `--headed`
to watch a web test, `--no-cache` to skip replaying cached actions.
## Next
<CardGroup cols={2}>
<Card title="Goals" icon="pen-to-square" href="/goals">
Write test steps as goals in natural language.
</Card>
<Card title="Signing in" icon="key" href="/authentication">
Reuse an app login and keep passwords out of model input.
</Card>
<Card title="Debugging" icon="bug" href="/debugging">
Read failures, screenshots, and traces.
</Card>
<Card title="Continuous integration" icon="code-branch" href="/ci">
Run your tests in CI.
</Card>
</CardGroup>