Quickstart

videoGetting Started with Agentic e2e in 4 MinutesIn this video, Kacper takes a simple Next.js app from zero to a working agentic test suite. (opens in a new tab)

#Set up with your coding agent

Paste this prompt into Claude Code, Codex, Cursor, or another coding agent in your app’s directory:

The agent installs the e2e skill, so later prompts such as “add a test for checkout” need no more setup.

#Set up manually

#Run your first test

1. 1
   Create the test project

   In your app’s directory:

   npmpnpmbun

   [ copy ]

   npx e2e init

   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.

   WebMobile

   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.

   Example web config and test

   This config uses Vercel AI Gateway. The wizard configures the provider you chose.

   e2e.config.ts[ copy ]

   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;

   tests/example.e2e.ts[ copy ]

   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();
   });

2. 2
   Run the example

   npmpnpmbun

   [ copy ]

   npx e2e run

   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.

#Use a subscription or API key

npm install -D ai

export AI_GATEWAY_API_KEY=...

import { gateway } from 'ai';

const agent = { model: gateway('openai/gpt-6-luna-fast') };

#Add an agent step

Give agent.act one atomic goal per call, then check the result. Adapt the example to a flow in your app:

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: '[email protected]' },
  });

  await agent.assert('the welcome screen greets Ada by name');
  await expect(screen.getByRole('status')).toContainText('trial');
});

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();
});

params fill the goal’s placeholders. agent.assert judges the screen. expect checks an exact value.

npx e2e run tests/agent.e2e.ts

pnpm exec e2e run tests/agent.e2e.ts

bunx e2e run tests/agent.e2e.ts

If you chose None in the wizard, add a model first. Add --headed to watch a web test. Add --no-cache to skip cached actions.

#Configure the project

e2e.config.ts holds the options. These are the ones most projects change after init:

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;

#Next