mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-21 03:05:26 +08:00
Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
329 lines
11 KiB
Plaintext
329 lines
11 KiB
Plaintext
---
|
|
title: Quickstart
|
|
description: Set up e2e with one prompt to your coding agent, or step by step.
|
|
"og:image": "https://e2e.com/docs/images/og/quickstart.png?v=4a3569d569"
|
|
"twitter:image": "https://e2e.com/docs/images/og/quickstart.png?v=4a3569d569"
|
|
---
|
|
|
|
import { ModelProvider } from './snippets/model-provider.jsx';
|
|
import { SetupPrompt } from './snippets/setup-prompt-card.jsx';
|
|
import { Video } from './snippets/video.jsx';
|
|
import { VideoCard } from './snippets/video-card.jsx';
|
|
|
|
export const setupPrompt = `Set up e2e end-to-end tests in this project. Docs: \`https://e2e.com/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.`;
|
|
|
|
<VideoCard
|
|
id="4_9z6QWShLc"
|
|
title="Getting Started with Agentic e2e in 4 Minutes"
|
|
subtitle="In this video, Kacper takes a simple Next.js app from zero to a working agentic test suite."
|
|
/>
|
|
|
|
## Set up with your coding agent
|
|
|
|
Paste this prompt into Claude Code, Codex, Cursor, or another coding agent
|
|
in your app's directory:
|
|
|
|
<SetupPrompt>
|
|
|
|
<Prompt description={setupPrompt} children={setupPrompt} actions={["copy", "cursor"]} />
|
|
|
|
</SetupPrompt>
|
|
|
|
The agent installs the [e2e skill](/coding-agents), so later prompts such as
|
|
"add a test for checkout" need no more setup.
|
|
|
|
<Note>
|
|
Use Node.js 24.8 or newer (22.22.3 or newer on Node.js 22), or [Bun](/reference/cli#bun) 1.4.3 or newer for web tests. 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, a 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. It keeps existing files.
|
|
|
|
<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](/web#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 e2e doctor` to check your setup. The wizard picks iOS on macOS
|
|
and Android elsewhere. The example opens the Settings app.
|
|
|
|
<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 [Mobile](/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 prints the result. The example makes no model calls,
|
|
so it needs no sign-in or API key.
|
|
</Step>
|
|
</Steps>
|
|
|
|
<Video>
|
|
<video src="/images/init.mp4" aria-label="npx e2e init asks for an engine, a model gateway, and coding agent setup, then lists the files it will write." muted loop playsInline controls />
|
|
|
|
`npx e2e init` asks a few questions, then shows every change before it writes anything.
|
|
</Video>
|
|
|
|
### Use a subscription or API key
|
|
|
|
<Tabs>
|
|
<Tab title="Subscription">
|
|
| Plan | How to connect |
|
|
| --- | --- |
|
|
| 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 spacexsi` |
|
|
| Claude Max or Team (Claude Code) | API key from the plan's monthly API credits. See [Claude Max or Team](/subscriptions#claude-max-or-team). |
|
|
|
|
Copilot uses your GitHub CLI login if you have one. See
|
|
[Subscriptions](/subscriptions).
|
|
</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" />
|
|
|
|
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 [atomic goal](/core-concepts#goals) 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=navigation-bar id=General')).toBeVisible();
|
|
});
|
|
```
|
|
|
|
`app.open()` launches the app fresh. Without it, a test starts where the
|
|
previous one left the device. `device.locator` takes
|
|
[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>
|
|
|
|
If you chose **None** in the wizard, [add a model](/models) first. Add
|
|
`--headed` to watch a web test. Add `--no-cache` to call the model instead of
|
|
replaying cached actions.
|
|
|
|
### Configure the project
|
|
|
|
`e2e.config.ts` holds the options. These are the ones most projects change
|
|
after `init`:
|
|
|
|
| To | Set | See |
|
|
| --- | --- | --- |
|
|
| point at your app | `app.url`, or `app.bundleId` on mobile | [The app under test](/reference/config#the-app-under-test) |
|
|
| start the app with the run | `app.command` | [Starting your app](/web#starting-your-app) |
|
|
| use a model | `agents.default.model` | [Models](/models) |
|
|
| test several browsers or devices | one `targets` entry each, with a `name` | [targets](/reference/config#targets) |
|
|
| give tests more time | `timeout`, `actionTimeout`, `assertionTimeout` | [timeout](/reference/config#timeout) |
|
|
| retry failed tests | `retries`, `1` in CI | [retries](/reference/config#retries) |
|
|
| run tests in parallel | `workers`, `1` in CI | [workers](/reference/config#workers) |
|
|
| pick the test files | `tests` | [tests](/reference/config#tests) |
|
|
| keep traces and videos | `trace`, `video` | [Recording](/reference/config#recording) |
|
|
| write a JUnit report | `reporters: ['list', 'junit']` | [reporters](/reference/config#reporters) |
|
|
| sign in and pass API keys | `credentials`, `secrets` | [Authentication](/authentication) |
|
|
| write the replay cache in CI | `cache: 'read-write'` | [Caching](/cache) |
|
|
|
|
<Accordion title="Example config with common options">
|
|
```ts title="e2e.config.ts"
|
|
import type { E2EConfig } from 'e2e';
|
|
import { web } from '@e2e-dev/web';
|
|
import { gateway } from 'ai';
|
|
|
|
const app = {
|
|
url: process.env.APP_URL ?? 'http://localhost:3000',
|
|
command: { executable: 'npm', args: ['run', 'dev'], reuseExisting: true },
|
|
};
|
|
|
|
export default {
|
|
agents: { default: { model: gateway('openai/gpt-6-luna-fast') } },
|
|
targets: [
|
|
{ name: 'chromium', engine: web({ viewport: { width: 1440, height: 900 } }), app },
|
|
{ name: 'firefox', engine: web({ browser: 'firefox' }), app },
|
|
],
|
|
timeout: 180_000,
|
|
workers: 4,
|
|
reporters: ['list', 'junit'],
|
|
video: 'retain-on-failure',
|
|
} satisfies E2EConfig;
|
|
```
|
|
|
|
`--target firefox` runs one target. Targets that share one `command` share
|
|
one server process.
|
|
</Accordion>
|
|
|
|
## Next
|
|
|
|
<CardGroup cols={2}>
|
|
<Card title="Core concepts" icon="pen-to-square" href="/core-concepts">
|
|
Goals, assertions, and locators.
|
|
</Card>
|
|
<Card title="Authentication" 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 on GitHub Actions, Expo Workflows, Bitrise, or Codemagic.
|
|
</Card>
|
|
</CardGroup>
|