mirror of
https://github.com/tester-army/e2e.git
synced 2026-11-22 18:19:48 +08:00
272 lines
8.4 KiB
Plaintext
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>
|