e2e

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

e2e: agentic end-to-end tests in TypeScript

e2e：TypeScript 中的 Agent 驱动端到端测试

e2e runs UI tests with agent goals and exact assertions.

agent.act

drives one goal;

agent.assert

agent.waitFor

, and

agent.extract

judge the screen.

screen

app

browser

, and

expect

make exact interactions and checks. The replay cache reruns verified actions and checks their recorded end state without a model call; agent judgments still run live. UI targets use

@e2e-dev/web

for browsers or

@e2e-dev/mobile

for iOS simulators and Android emulators. A test that takes only

app

can check an API with

fetch

and

expect

(topic

writing-tests

). Model sign-in commands are in setup.

// e2e.config.ts
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { gateway } from 'ai';

export default {
  targets: [
    {
      engine: web(),
      app: {
        url: 'http://127.0.0.1:3000',
        command: { executable: 'pnpm', args: ['dev'], log: '.e2e/logs/app.log' },
      },
    },
  ],
  // The model behind every agent.* step: an AI SDK instance; gateway() from 'ai' reads AI_GATEWAY_API_KEY or a Vercel OIDC token.
  agents: {
    default: {
      model: gateway('openai/gpt-6-luna-fast'),
      system: 'You are a thorough QA agent. Verify every outcome on screen.',
    },
  },
} satisfies E2EConfig;

// tests/billing.e2e.ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';

test('a member upgrades to Pro', async ({ app, agent, screen, browser }) => {
  await app.open('/settings/billing');
  await agent.act('upgrade the workspace to the Pro plan');
  await expect(screen.getByRole('status')).toContainText('Pro');
  await expect(browser).toHaveURL('/settings/billing');
});

e2e 使用 Agent 目标和精确断言来运行 UI 测试。

agent.act

驱动单个目标；

agent.assert

、

agent.waitFor

和

agent.extract

根据屏幕内容进行判断。

screen

、

app

、

browser

和

expect

用于执行精确的交互与检查。replay cache 无需调用模型即可重放已验证的操作，并检查其记录的最终状态；Agent 判断仍会实时执行。UI target 使用

@e2e-dev/web

处理浏览器，或使用

@e2e-dev/mobile

处理 iOS 模拟器和 Android 模拟器。仅使用

app

的测试可以通过

fetch

和

expect

检查 API（主题

writing-tests

）。模型登录命令见 setup。

// e2e.config.ts
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
import { gateway } from 'ai';

export default {
  targets: [
    {
      engine: web(),
      app: {
        url: 'http://127.0.0.1:3000',
        command: { executable: 'pnpm', args: ['dev'], log: '.e2e/logs/app.log' },
      },
    },
  ],
  // The model behind every agent.* step: an AI SDK instance; gateway() from 'ai' reads AI_GATEWAY_API_KEY or a Vercel OIDC token.
  agents: {
    default: {
      model: gateway('openai/gpt-6-luna-fast'),
      system: 'You are a thorough QA agent. Verify every outcome on screen.',
    },
  },
} satisfies E2EConfig;

// tests/billing.e2e.ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';

test('a member upgrades to Pro', async ({ app, agent, screen, browser }) => {
  await app.open('/settings/billing');
  await agent.act('upgrade the workspace to the Pro plan');
  await expect(screen.getByRole('status')).toContainText('Pro');
  await expect(browser).toHaveURL('/settings/billing');
});

Topics

主题

Read the topic for the job before writing code. The files sit next to this one; the installed CLI prints the same text with

npx e2e guide <topic>

(

e2e guide

alone prints this page). For anything the topics do not cover, the full documentation ships in the

docs/

directory of the installed

e2e

package (

node_modules/e2e/docs

in a single-package project); a link such as

/reference/cli

docs/reference/cli.mdx

Topic	File	Read it when
`setup`	references/setup.md	Adding e2e to a project, writing `e2e.config.ts` , starting the app from the config, mobile targets
`writing-tests`	references/writing-tests.md	Writing or fixing tests: fixtures, locators, actions, matchers, sign-in sessions, the `browser` fixture
`agent`	references/agent.md	Adding `agent.*` steps, picking a model, cost and budgets, the replay cache
`running`	references/running.md	CLI flags, reporters, `.e2e/report.json` , exit codes, CI
`explore`	references/explore.md	Exploring an app toward a goal without a test file: `e2e explore` , its budgets, verdict, and `run.explore`
`debugging`	references/debugging.md	A run failed: error codes and their fixes, `--headed` , `--debug` , `--ai-trace`
`mcp`	references/mcp.md	Driving the live app from a coding agent over MCP: `e2e mcp` , its tools, and the explore-then-write loop
`bug-bash`	references/bug-bash.md	Asked to bug bash, QA, or hunt for bugs across an app or a branch: parallel `e2e explore` charters, merging findings, proving each with a repro test

编写代码前，先阅读与任务对应的主题。相关文件位于本文档旁；已安装的 CLI 可通过

npx e2e guide <topic>

打印相同文本（仅运行

e2e guide

会打印本页）。如果主题未涵盖某项内容，完整文档随已安装的

e2e

包一起提供，位于

docs/

目录（在单包项目中为

node_modules/e2e/docs

）；例如

/reference/cli

这样的链接对应

docs/reference/cli.mdx

。

主题	文件	何时阅读
`setup`	references/setup.md	将 e2e 添加到项目、编写 `e2e.config.ts` 、从配置启动应用、配置移动端 target 时
`writing-tests`	references/writing-tests.md	编写或修复测试：fixtures、locators、actions、matchers、登录会话、 `browser` fixture
`agent`	references/agent.md	添加 `agent.*` 步骤、选择模型、设置成本和预算、配置 replay cache 时
`running`	references/running.md	使用 CLI flags、reporters、 `.e2e/report.json` 、退出码、CI 时
`explore`	references/explore.md	无需测试文件、以目标为导向探索应用时：了解 `e2e explore` 、其预算、verdict 和 `run.explore`
`debugging`	references/debugging.md	运行失败时：了解错误代码及其修复方式、 `--headed` 、 `--debug` 、 `--ai-trace`
`mcp`	references/mcp.md	通过 MCP 从 coding agent 驱动实时应用时：了解 `e2e mcp` 、其工具以及先探索再编写测试的流程
`bug-bash`	references/bug-bash.md	被要求进行 bug bash、QA 或跨应用或分支排查缺陷时：并行执行 `e2e explore` 、合并发现，并通过复现测试证明每个问题

Workflow

工作流

Look at what exists:

e2e.config.ts

e2e.config.mts

, the

tests

glob (default

tests/**/*.e2e.ts

e2e

package.json

. Nothing there: follow

setup

Learn the screens before writing a test: routes, labels, roles, button text. Semantic locators need the accessible names the app renders, so read the components, open the page with
```
--headed
```
, or drive the live app over the registered
```
e2e mcp
```
server (topic
```
mcp
```
):
```
open_session
```
,
```
observe
```
, and
```
locate
```
show exact names and check a locator before you write it.
Write
```
tests/<feature>.e2e.ts
```
. Drive the flow with
```
agent.act
```
, one goal per call, and pin each outcome right after with
```
expect
```
or
```
agent.assert
```
. Exact values go through
```
screen
```
: a sign-in form in a setup test, a field that must receive one specific string, a count that must be one number.
Run one file:
```
npx e2e run tests/<feature>.e2e.ts
```
. Agent steps need a model in the config and that provider's authentication (a saved subscription login, an API key); a local endpoint may need none. Tests without agent steps need no model.
Read the failure: the reporter prints the error code, message, and a code frame;
```
.e2e/report.json
```
has every step and artifact path. Fix the locator, the expectation, or the app. Never add a sleep.

先查看现有内容：
```
e2e.config.ts
```
或
```
e2e.config.mts
```
、
```
tests
```
glob（默认值为
```
tests/**/*.e2e.ts
```
）、
```
package.json
```
中的
```
e2e
```
。如果这些都不存在：请遵循
```
setup
```
主题。
编写测试前先了解界面：路由、标签、角色和按钮文本。语义 locator 需要应用渲染出的可访问名称，因此应阅读组件、使用
```
--headed
```
打开页面，或通过已注册的
```
e2e mcp
```
server 驱动实时应用（主题
```
mcp
```
）：
```
open_session
```
、
```
observe
```
和
```
locate
```
会显示确切名称，编写 locator 前应先检查它。
编写
```
tests/<feature>.e2e.ts
```
。使用
```
agent.act
```
驱动流程，每次调用只处理一个目标，并紧接着使用
```
expect
```
或
```
agent.assert
```
固定每个结果。精确值通过
```
screen
```
处理：setup 测试中的登录表单、必须填入某个特定字符串的字段、必须等于某个数字的计数。
运行单个文件：
```
npx e2e run tests/<feature>.e2e.ts
```
。Agent 步骤需要在配置中提供模型，并准备好相应提供方的认证信息（已保存的订阅登录或 API key）；本地 endpoint 可能无需认证。不含 Agent 步骤的测试不需要模型。
读取失败信息：reporter 会打印错误代码、消息和代码帧；
```
.e2e/report.json
```
包含每个步骤及其 artifact 路径。修复 locator、expectation 或应用。绝不要添加 sleep。

Rules

规则

Run the CLI as
```
npx e2e ...
```
(or
```
pnpm exec e2e ...
```
).
The config is
```
export default { ... } satisfies E2EConfig
```
with
```
import type { E2EConfig } from 'e2e'
```
.
```
targets
```
is required; a UI target names an engine and declares the app beside it:
```
{ engine: web(), app: { url, command } }
```
. A tools-only target can omit the engine and set
```
platform
```
.
Import
```
test
```
,
```
describe
```
, the hooks,
```
expect
```
,
```
credentials
```
, and
```
secrets
```
from
```
e2e
```
. A test that uses the
```
browser
```
fixture imports
```
test
```
,
```
describe
```
, and the hooks from
```
@e2e-dev/web
```
: the same runtime functions, typed with
```
browser
```
.
Config and tests are ES modules whatever
```
package.json
```
sets as
```
type
```
.
Locators resolve when used. Actions wait for readiness and
```
expect
```
retries assertions. Reads such as
```
textContent()
```
fail at once on zero matches and
```
count()
```
answers from the current screen; nothing waits for a value to change, so use a matcher when a value has to settle.
A locator that matches two nodes fails with
```
LOCATOR_AMBIGUOUS
```
; narrow it (topic
```
writing-tests
```
).
Secrets never appear in test code. Declare accounts under
```
credentials
```
and every other sensitive value under
```
secrets
```
in the config; resolve with
```
credentials.user(name).password
```
or
```
secrets.get(name)
```
(separate namespaces:
```
secrets.get
```
never returns a password), and hand the opaque
```
Secret
```
only to
```
fill()
```
or
```
agent.act
```
params.
Agent instructions: one goal per
```
act
```
, the wording on screen, real values in params. Judge meaning, not phrasing:
```
toContain('Pro')
```
, not an exact sentence a model produced.
Check each agent goal's outcome. A passing
```
act
```
with a recorded check can be cached and replayed without model calls (topic
```
agent
```
).
Shape the agent for this app:
```
context
```
for vocabulary the screens use,
```
system
```
for how it works, tools for a test API, named personas under
```
agents
```
. When a step fails, tighten the goal first, then the context, then the agent.
```
.e2e/
```
is output (
```
report.json
```
,
```
artifacts/
```
,
```
cache/
```
,
```
logs/
```
; the config's
```
output
```
moves the report and artifacts, never
```
cache/
```
or the app's log). Read it, never edit it.

使用
```
npx e2e ...
```
（或
```
pnpm exec e2e ...
```
）运行 CLI。
配置应采用
```
export default { ... } satisfies E2EConfig
```
形式，并使用
```
import type { E2EConfig } from 'e2e'
```
。
```
targets
```
为必填项；UI target 需要指定 engine，并在旁边声明 app：
```
{ engine: web(), app: { url, command } }
```
。仅工具 target 可以省略 engine 并设置
```
platform
```
。
从
```
e2e
```
导入
```
test
```
、
```
describe
```
、hooks、
```
expect
```
、
```
credentials
```
和
```
secrets
```
。使用
```
browser
```
fixture 的测试需从
```
@e2e-dev/web
```
导入
```
test
```
、
```
describe
```
和 hooks：它们是相同的运行时函数，只是带有
```
browser
```
类型。
无论
```
package.json
```
的
```
type
```
设置为何，配置和测试都使用 ES modules。
Locator 在使用时解析。操作会等待就绪状态，
```
expect
```
会重试断言。
```
textContent()
```
等读取操作在零匹配时立即失败，
```
count()
```
则根据当前屏幕返回结果；不会自动等待值发生变化，因此当值需要稳定下来时应使用 matcher。
匹配两个节点的 locator 会以
```
LOCATOR_AMBIGUOUS
```
失败；应缩小匹配范围（主题
```
writing-tests
```
）。
密钥绝不能出现在测试代码中。在配置中将账户声明在
```
credentials
```
下，其他所有敏感值声明在
```
secrets
```
下；通过
```
credentials.user(name).password
```
或
```
secrets.get(name)
```
解析（两个命名空间彼此独立：
```
secrets.get
```
永远不会返回密码），并且只能将不透明的
```
Secret
```
传给
```
fill()
```
或
```
agent.act
```
的参数。
Agent 指令：每次
```
act
```
只设置一个目标，使用屏幕上的措辞，并在参数中填写真实值。判断语义而非表述：使用
```
toContain('Pro')
```
，不要要求模型生成完全一致的句子。
检查每个 Agent 目标的结果。
```
act
```
成功且结果检查已记录后，即可缓存并在无模型调用的情况下重放（主题
```
agent
```
）。
针对此应用配置 Agent：使用
```
context
```
描述界面使用的词汇，使用
```
system
```
描述工作方式，使用
```
tools
```
提供测试 API，并在
```
agents
```
下定义具名 personas。步骤失败时，先收紧目标，再调整 context，最后调整 Agent。
```
.e2e/
```
是输出目录（
```
report.json
```
、
```
artifacts/
```
、
```
cache/
```
、
```
logs/
```
；配置中的
```
output
```
会移动报告和 artifacts，但不会移动
```
cache/
```
或应用日志）。只读取，不要编辑。

Feedback

反馈

When e2e itself gets in your way, tell the e2e team: a command or API that broke (

bug

), docs or this skill that misled you (

docs

), or a capability you needed and did not find (

feature

). Send it once per problem, after you worked around it or gave up, never for failures of the app under test.

bash

npx e2e feedback --type bug -m "<one or two sentences>" \
  --task "<what you were doing>" --expected "<...>" --actual "<error code and message>" \
  --approach "<what you tried>" --command "<e2e command>" --agent "<agent / model>"

Describe e2e's behavior only: never paste app content, page text, test files, URLs of private apps, or credentials. Secret-named environment variables and common token shapes are redacted, but do not rely on it.

--dry-run

prints what would be sent. Tell the user you sent it and give them the reference id it prints.

当 e2e 本身妨碍你工作时，请告知 e2e 团队：某个命令或 API 出现故障（

bug

）、文档或此 skill 误导了你（

docs

），或者你所需的功能不存在（

feature

）。每个问题只发送一次，并且应在你已经绕过问题或放弃之后发送；被测应用自身的失败绝不要发送。

bash

npx e2e feedback --type bug -m "<one or two sentences>" \
  --task "<what you were doing>" --expected "<...>" --actual "<error code and message>" \
  --approach "<what you tried>" --command "<e2e command>" --agent "<agent / model>"

仅描述 e2e 的行为：绝不粘贴应用内容、页面文本、测试文件、私有应用 URL 或凭据。以 secret 命名的环境变量和常见 token 形式会被脱敏，但不要依赖这一点。

--dry-run

会打印将要发送的内容。告知用户你已发送反馈，并提供它打印的 reference id。