Coding agents

A coding agent uses the skill, the e2e CLI, and the JSON report. e2e mcp also gives it a live session on the app to inspect controls before writing a test. e2e init installs the skill and registers the MCP server.

The skill

npx --no-install e2e init

Path	Read by	Content
`.agents/skills/e2e/`	Codex, Cursor, Copilot, Gemini CLI, OpenCode, Zed, and most other agents	`SKILL.md` plus `references/setup.md`, `writing-tests.md`, `agent.md`, `running.md`, `explore.md`, `debugging.md`, and `mcp.md`
`.claude/skills/e2e/`	Claude Code	The same files

SKILL.md is the entry point: the mental model, a sample test, the rules, and the list of topics. An agent reads a topic file only when it needs it. Re-running init after an upgrade refreshes the copies. Without init, npx skills add tester-army/e2e installs the skill from the repository, and npx --no-install e2e guide [topic] prints it from the installed package. init does not touch AGENTS.md, CLAUDE.md, or Cursor rules. Agents that load skills on demand find this one by its frontmatter description. For an always-on pointer, one line in the project’s instructions file is enough:

AGENTS.md

End-to-end tests use @e2edev/e2e; read .agents/skills/e2e/SKILL.md before writing or running one.

How an agent looks at the app

e2e mcp serves a live session on one target. Its catalog includes the engine’s action tools and locate, which tries a screen.* locator and returns the call to write when exactly one node matches. The server exposes open_session, tools, call, and close_session; call dispatches to the session’s catalog by name. init registers the server in .mcp.json for Claude Code and .cursor/mcp.json for Cursor. To register it with Claude Code by hand:

claude mcp add e2e -- npx --no-install e2e mcp

See the MCP server reference for its tools, session rules, and flags. Run tests and read reports through the CLI.

How an agent writes a test

The skill tells an agent to look before it writes: read e2e.config.ts for the tests glob, targets, and credentials, then an existing test for the project’s conventions. Then it writes deterministic steps first and reaches for the agent only where the flow varies.

tests/checkout.e2e.ts

import { test, expect, credentials } from '@e2edev/e2e';

test('a signed-in user reaches checkout', async ({ screen, app, agent }) => {
  const user = credentials.user('customer');
  await app.open('/login');
  await screen.getByLabel('Email').fill(user.username);
  await screen.getByLabel('Password').fill(user.password);
  await screen.getByRole('button', { name: 'Sign in' }).click();
  await expect(screen.getByRole('heading', { name: 'Welcome back' })).toBeVisible();

  await agent.act('Add the cheapest item on the page to the cart and open the cart');
  await expect(screen.getByRole('heading', { name: 'Your cart' })).toBeVisible();
});

The rules the skill states, and why each is there:

npx --no-install e2e, never npx e2e. The bare form fetches whatever package is called e2e on npm when the runner is not installed locally.
One agent.act per goal, followed by an expect. The assertion makes the step’s cache entry eligible for replay, and it is what fails when the agent did the wrong thing.
No sleeps. Locators poll, actions wait for their target, and expect retries until its timeout.
Secrets through credentials.user(name), declared in the config, never literal in a test.

How an agent runs it

npx --no-install e2e run tests/checkout.e2e.ts

Run one file while iterating. With no executor configured, acquiring agent without a model raises MODEL_UNAVAILABLE after the engine attempt starts. A custom executor can implement agent.act and agent.assert without a model. agent.waitFor and agent.extract still need a configured model when they request a judgment. Provider credentials are needed only when a model request is made. Check model configuration when the error reports a missing model. For other exit-code-2 failures, follow the reported CLI, config, or collection error. The exit code says which side failed. 1 is a test. 2 is the CLI, config, or collection, and retrying it changes nothing. 3 is the engine, the app process, or the model provider.

How an agent reads the result

Every run writes .e2e/report.json. --reporter json prints the same document on stdout for an agent that would rather parse than open a file.

{
  "run": {
    "status": "failed",
    "exitCode": 1,
    "errors": [],
    "results": [
      {
        "titlePath": ["a signed-in user reaches checkout"],
        "file": "tests/checkout.e2e.ts",
        "status": "failed",
        "attempts": [
          {
            "status": "failed",
            "steps": [{ "kind": "agent", "api": "agent.act", "label": "Add the cheapest item...", "status": "passed" }],
            "error": { "code": "ASSERTION_FAILED", "message": "expected heading \"Your cart\" to be visible" },
            "artifacts": [{ "kind": "screenshot", "path": ".e2e/artifacts/checkout/failure.png" }]
          }
        ]
      }
    ]
  }
}

The reading order the skill teaches: run.errors[] first, because a run-level failure means no test result is meaningful. Then the error of the last attempt of each failed result, and the artifacts[] beside it; the screenshot usually says more than the message. steps[] shows how far the test got. For an agent step that went wrong, --debug adds the transcript as an artifact and --ai-trace writes a trace the unbox-ai CLI summarizes. Nothing should read .e2e/ai-trace.json directly; it is megabytes of resent context.

How an agent treats the cache

Each passing agent.act records its actions under .e2e/cache/ and the next run replays them. For a coding agent this means three things:

A test is not proven until it passes with the cache off. Run --no-cache once before declaring done, and whenever the failure might be the recording rather than the app.
Never edit a cache entry. A failing run evicts the entries it implicates.
--no-cache also makes --ai-trace complete, since replayed steps make no model calls to trace.

The bar the skill is written to

An agent given only the skill, a project that init scaffolded, and a target it can reach should write a test that passes on its first run. If your agent needs a second attempt, the skill is missing something; the fix belongs in skills/e2e/ in the e2e repository, not in your project’s copy.

CLI reference

init, guide, mcp, and run, flag by flag.

MCP server

Inspect the app before writing a test.

Debugging a run

The report, the artifacts, and the agent flags.

Get started

Web

Mobile

Guides

Extend

Coding agents

The skill

How an agent looks at the app

How an agent writes a test

How an agent runs it

How an agent reads the result

How an agent treats the cache

The bar the skill is written to

CLI reference

MCP server

Debugging a run

​The skill

​How an agent looks at the app

​How an agent writes a test

​How an agent runs it

​How an agent reads the result

​How an agent treats the cache

​The bar the skill is written to

CLI reference

MCP server

Debugging a run

The skill

How an agent looks at the app

How an agent writes a test

How an agent runs it

How an agent reads the result

How an agent treats the cache

The bar the skill is written to