e2e

Open source project by TesterArmy (tester-army/e2e, Apache-2.0).

Why use it?

The docs give two reasons under “Why e2e”. Less time on tests: “Write a goal instead of a script of selectors and waits. When the UI changes, the agent adapts, so you fix fewer tests.” And cheap runs: e2e records an agent.act step when a later check passes, and the next run replays it with no model calls.

Describe a goal in natural language and an agent drives the app to reach it. Check the result with locators and assertions in the same test.

// tests/checkout.e2e.ts
import { test, expect } from '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');
});

What you can do with it

• Have a coding agent write the tests — Per the docs, “A coding agent such as Claude Code, Codex, or Cursor can write, run, and debug e2e tests.” Once the skill is installed, later prompts such as “add a test for checkout” need no more setup.

• Explore without a test — e2e explore runs the agent against your app with a goal instead of a test file. The agent plans a step, does it, and records findings until the goal is covered or a budget ends, then writes an assessment. The docs example:

  npx e2e explore 'Explore the checkout flow like a first-time buyer and report anything off'

  The sample output in the docs lists findings with a severity, such as “Cart total does not update when Hyperion quantity increases” and “Neuromancer shows an impossible negative stock availability”.

• Run a bug bash — A bug bash runs many e2e explore sessions at the same time, each on one area of the app. A coding agent then writes a test for each finding and reports it as a bug only when the test fails. The docs prompt for your coding agent:

  Bug bash the checkout and account settings on this branch.

• See a finished setup in your stack — examples/ has Vite, Next.js, Astro, Expo, SwiftUI, Jetpack Compose, Kotlin Multiplatform, and Flutter, each a standalone project with a passing suite.

Key features

• Agent goals and exact steps in one test

  agent.act drives one goal; agent.assert judges the screen; screen and expect act and check exactly. The docs recommend one agent.act per goal, then an expect: the expect fails when the agent did the wrong thing.

• Replay cache

  The replay cache records the actions of an agent.act() step after a later check verifies the result. On the next run, the runner replays those actions without a model call. When a control or the expected end state no longer matches, the agent takes over from the current screen. agent.assert, agent.waitFor, and agent.extract always run live.

• Web and mobile with the same APIs

  @e2e-dev/web is the browser engine: Chromium, Firefox, and WebKit through Playwright. @e2e-dev/mobile runs tests on iOS simulators, Android emulators, and phones connected to your machine, and tests use the same agent, screen, and expect APIs as browser tests.

• A skill and an MCP server for coding agents

  The agent learns e2e from the skill. e2e mcp lets coding agents inspect your app, try locators, and take masked screenshots before writing tests. Each agent, subagents included, opens its own session; up to 4 sessions may be open at once by default. The server does not run tests, and it needs no model.

• A trace page for each failure

  A run writes a trace page for each failed, timed-out, interrupted, or flaky test, at .e2e/results/<test>/trace.md. The page has the failing line and every step with what it did, console errors, failed requests, and the screen at the failure.

• Bring your own model

  Agent steps use the model you set in e2e.config.ts: a gateway such as Vercel AI Gateway or OpenRouter, a direct API key, a local server, or your subscription.

How to use

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.

In your app’s directory:

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. For Claude Code, the skill goes to .claude/skills/e2e/ and the MCP server is registered in .mcp.json.

Run the example:

npx e2e run

The example makes no model calls, so it needs no sign-in or API key. After you add an agent step, run one file:

npx e2e run tests/agent.e2e.ts

Add --headed to watch a web test. Add --no-cache to skip cached actions.

You can also set up with your coding agent: the quickstart has a prompt to paste into Claude Code, Codex, Cursor, or another coding agent in your app’s directory.

To register only the MCP server with Claude Code by hand:

claude mcp add e2e -- npx e2e mcp

Notes

• Telemetry is on by default — The CLI sends anonymous usage data, such as which commands and engines run and where runs fail, but no test content, app content, or credentials. Opt out with npx e2e telemetry disable, E2E_TELEMETRY_DISABLED=1, or DO_NOT_TRACK=1. With E2E_TELEMETRY_DEBUG=1, the CLI prints the exact payloads and sends nothing. Telemetry lists every field.
• Pre-1.0 — “e2e is in active development on the way to 1.0. APIs and config can still change between minor releases.”
• There is no default model — The built-in agent needs a model that supports tool calls and images. Tests without agent steps need no model.
• Claude Max or Team uses an API key — ChatGPT, GitHub Copilot and other plans connect with npx e2e login. Claude Max or Team uses an API key, paid from the plan’s monthly API credits, not its usage limits.
• Explore and bug bashes use model calls — An explore run stops after 8 steps or 10 minutes; raise --max-steps <n> (up to 12) or --timeout <ms> (up to 15 minutes). Each run ends with its tokens, cost, and duration. The docs say to compare each finding with its evidence before you act on it.
• Hosted engines are separate services — @e2e-dev/kernel, @e2e-dev/limrun, @e2e-dev/eas, and @e2e-dev/smol connect hosted browsers, simulators, and emulators. You don’t need them to run on local browsers and simulators.
• Update the skill after upgrading — After you upgrade e2e, run init again to update the skill. npx e2e guide [topic] prints it from the installed package.
• Source — tester-army/e2e (Apache-2.0). Docs: e2e.tester.army/docs.