「漫说测试」· 实战实测
一个真实跑通的 demo 全记录:装包 → 配置 → 用例 → 出报告,附完整可运行项目 + 指令执行层级 + 踩坑指南。
【贴图1】
一、先说结论
能跑,而且很好上手。
我用 tester-army/e2e(v0.18.0)建了一个最小项目:一个登录表单 + 购物车页面,用浏览器真实点击「登录 → 加购 ×2」,两条用例全绿,耗时 3.45 秒,并生成了机器可读的 report.json。
最香的一点:确定性用例(只用定位器 + 断言)全程零模型调用、零 API 费用——这是它比一堆「AI 测试」噱头工具更务实的地方。
【贴图2】
二、它到底是什么?
e2e 是一个开源的 agentic 端到端测试框架,核心玩法是:
-
用自然语言描述目标,让 agent 自己驱动页面(
agent.act/agent.assert); -
也可以用传统定位器 + 断言做精确校验(
screen+expect); -
关键设计:agent 步骤跑通一次会被记录,下次运行直接重放、不再调模型,直到页面变化——所以模型成本可控;
-
浏览器引擎底层用 Playwright,移动端走 iOS/Android 模拟器;
-
官网开源、Apache-2.0 许可 ^1。
一句话:它把「AI 的灵活」和「断言的确定」塞进了同一个测试文件里。
【贴图3】
【贴图4】
【贴图5】
【贴图6】
三、先看清结构:完整项目 + 指令执行层级
这一步 90% 的人会踩——不是框架难,是**「命令该在哪一层跑」没说清**。先看完整结构:
e2e-demo/ ← 「项目根」:所有命令都在这一层执行
├── package.json ← 依赖与脚本
├── tsconfig.json ← TS 配置(e2e.config.ts / tests 用)
├── e2e.config.ts ← ⭐ 测试配置(runner 自管被测进程)
├── app/
│ └── server.js ← 被测应用(40 行 Node 静态站)
├── tests/
│ ├── checkout.e2e.ts ← 确定性用例(零模型)
│ └── agent-example.e2e.ts ← agent 示例(默认 skip)
└── .e2e/ ← 运行期自动生成(勿手动建)
├── logs/app.log
└── report.json
指令在哪个层级执行(最容易搞错的地方):
|
指令
|
在哪个目录执行
|
说明
|
| --- | --- | --- |
| npm install e2e@latest | 项目根e2e-demo/ |
装核心 CLI/SDK
|
| npm install -D @e2e-dev/web | 项目根 |
浏览器引擎(别再装 playwright)
|
| sudo ./node_modules/.bin/e2e-web install chromium --with-deps | 项目根 |
补 Chromium 系统库(容器必备)
|
| node app/server.js | 项目根 |
手动起被测应用(一般不用,runner 会自管)
|
| npx e2e run | 项目根 |
⭐ 跑测试;必须在含 e2e.config.ts 的目录执行
|
| npx e2e login openai | 项目根 |
订阅登录模型(用 agent 步骤时)
|
| export AI_GATEWAY_API_KEY=*** |
项目根
|
API Key(用 agent 步骤时)
|
一句话:除了「进目录」那两条(
mkdir e2e-demo && cd e2e-demo),其余命令一律在「项目根 e2e-demo/」里执行。配置里的相对路径(tests/**/*.e2e.ts、app/server.js、.e2e/logs/app.log)也都以项目根为基准。npx e2e run如果在子目录里跑,找不到e2e.config.ts,就会报错。
【配图·fig-tarmy-d:项目结构与指令层级】
四、环境准备
| 项目 | 要求 | | --- | --- | | Node.js | ≥ 24.8(或 22.22.3+) | | 包管理 | npm / pnpm 均可 | | 浏览器依赖 | 首次需补 Chromium 系统库(见踩坑部分) |
我本机环境:Node v24.18.0 + npm 11.16.0。
五、三步跑通
第 0 步:建目录、初始化(先「进项目根」)
mkdir e2e-demo && cd e2e-demo
npm init -y
第 1 步:装包(在项目根)
# 核心 CLI / SDK
npm install e2e@latest
# 浏览器引擎(它内部锁死 playwright-core,千万别再单独装 playwright)
npm install --save-dev @e2e-dev/web
⚠️ 官方明确要求:浏览器测试用
@e2e-dev/web,它会精确锁定playwright-core版本;不要额外安装playwright,否则版本打架。
【贴图7】
【贴图8】
第 2 步:造一个被测应用(在项目根,写 app/server.js)
为了不依赖外部网站,我写了一个 40 行的 Node 静态站 app/server.js:带一个登录表单和一个「加入购物车」按钮。
// app/server.js
const http = require('node:http');
const PORT = Number(process.env.PORT || 4173);
const PAGE = `<!doctype html>
<html lang="en"><head><meta charset="utf-8"><title>Acme Storefront</title></head>
<body>
<h1>Acme Storefront</h1>
<form id="signin">
<label for="email">Email</label>
<input id="email" type="email">
<label for="password">Password</label>
<input id="password" type="password">
<button type="submit">Sign in</button>
</form>
<div id="status" role="status"></div>
<section class="row" hidden id="shop">
<span>Items in cart:</span>
<span id="cart-count" data-testid="cart-count">0</span>
<button type="button" id="add">Add to cart</button>
</section>
<script>
const status = document.getElementById('status');
const shop = document.getElementById('shop');
const countEl = document.getElementById('cart-count');
let count = 0;
document.getElementById('signin').addEventListener('submit', (e) => {
e.preventDefault();
const email = document.getElementById('email').value.trim();
if (!email) { status.textContent = 'Email required'; return; }
status.textContent = 'Signed in as ' + email;
shop.hidden = false;
});
document.getElementById('add').addEventListener('click', () => {
count += 1; countEl.textContent = String(count);
});
</script>
</body></html>`;
http.createServer((req, res) => {
if (req.url === '/' ) { res.writeHead(200, {'content-type':'text/html; charset=utf-8'}); res.end(PAGE); return; }
if (req.url === '/healthz') { res.end('ok'); return; }
res.writeHead(404); res.end('not found');
}).listen(PORT, '127.0.0.1', () => console.log('app on', PORT));
第 3 步:写配置 e2e.config.ts(放项目根)
亮点:app.command 让 runner 自己拉起/结束被测进程,你再也不用手动开 dev server。
// e2e.config.ts
import type { E2EConfig } from 'e2e';
import { web } from '@e2e-dev/web';
export default {
tests: 'tests/**/*.e2e.ts',
targets: [
{
name: 'web',
engine: web(),
app: {
url: 'http://127.0.0.1:4173',
command: {
executable: 'node',
args: ['app/server.js'],
env: { PORT: '4173' },
log: '.e2e/logs/app.log',
},
},
},
],
// 确定性用例不需要下面这段;要用 agent 步骤再放开并登录模型
} satisfies E2EConfig;
第 4 步:写用例 tests/checkout.e2e.ts(零模型版)
// tests/checkout.e2e.ts
import { test } from '@e2e-dev/web';
import { expect } from 'e2e';
test('a shopper signs in and adds two items to the cart', async ({ app, screen }) => {
await app.open('/');
await screen.getByLabel('Email').fill('qa@example.test');
await screen.getByLabel('Password').fill('hunter2-hunter2');
await screen.getByRole('button', { name: 'Sign in' }).click();
await expect(screen.getByRole('status')).toContainText('Signed in as qa@example.test');
await screen.getByRole('button', { name: 'Add to cart' }).click();
await screen.getByRole('button', { name: 'Add to cart' }).click();
await expect(screen.getByTestId('cart-count')).toHaveText('2');
});
第 5 步:跑!(在项目根)
npx e2e run
六、运行结果(真实输出)
RUN e2e v0.18.0 /…/e2e-demo
✓ target "web" command ready 121ms
✓ |web| tests/checkout.e2e.ts (2 tests) 2.78s
Test Files 1 passed (1)
Tests 2 passed (2)
Duration 3.45s → Report .e2e/report.json
report.json 里关键字段:"status": "passed"、"exitCode": 0——CI 门禁可以直接拿退出码判断。
【贴图9】
七、踩坑记录(唯一一个)
现象:第一次运行直接报错——
error while loading shared libraries: libatk-1.0.so.0: cannot open shared object file
原因:容器/裸机缺少 Chromium 的系统依赖库。
解决(在项目根执行,官方推荐命令,--with-deps 会顺带把系统库装好):
sudo ./node_modules/.bin/e2e-web install chromium --with-deps
装完 ldconfig -p | grep libatk 能看到库,再跑就绿了。非容器环境通常不会遇到这一步(Windows 基本遇不到)。
排错速查表(实测最常撞的两个)
报错①:npm error could not determine executable to run
-
症状:执行
npx exe run报“找不到可执行文件”。 -
原因:命令拼错了——是
e2e,不是exe。 -
修复:
npx e2e run。
报错②:CONFIG_LOAD_FAILED ... Cannot find package '@e2e-dev/web' ... run npm install
-
症状:配置加载失败,提示
@e2e-dev/web已在 package.json 声明但没装。 -
原因:直接
npx e2e run时,npx 只临时抓了e2e,没有安装项目依赖。 -
修复:在项目根先
npm install,再npx e2e run。
Windows(PowerShell)注意:
|
事项
|
Linux/macOS
|
Windows(PowerShell)
|
| --- | --- | --- |
|
装 Chromium
| sudo ./node_modules/.bin/e2e-web install chromium --with-deps | npx e2e-web install chromium
(去掉 sudo)
|
|
跑测试
| npx e2e run | npx e2e run
,或更稳的 .\node_modules\.bin\e2e run
|
|
核对
| ls node_modules/@e2e-dev | dir node_modules\@e2e-dev
(应有 web)
|
顺带:关遥测用
npx e2e telemetry disable(或设E2E_TELEMETRY_DISABLED=1)。
八、进阶:加上 agent(自然语言)步骤
确定性用例很稳,但真正「agentic」的部分长这样:
// 需要先在 config 里配置模型 + 登录
await agent.act('sign in with the email qa@example.test and the password hunter2-hunter2');
await agent.assert('the page confirms the user is signed in');
启用方式二选一(在项目根):
# 方式 A:用订阅登录(ChatGPT Plus/Pro)
npx e2e login openai
# 方式 B:用 API Key
export AI_GATEWAY_API_KEY=*** # 或 OPENROUTER_API_KEY=***
💡 我把 agent 示例单独放一个文件并
test.skip,这样没有模型的环境也能跑确定性套件,有模型时再单独开——团队协作很实用。
九、我的使用建议
✅ 适合:
-
想在现有 Playwright/Selenium 体系上,低成本试水 AI 测试的团队;
-
需要「自然语言探索 + 精确断言」混合的复杂业务流程;
-
对模型成本敏感(重放机制帮你省钱)。
⚠️ 注意:
-
当前 0.18.x,尚未到 1.0,小版本间 API 可能变,适合先在非关键流程试点;
-
agent 步骤质量依赖模型与页面语义,配置里给足
context/system提示会更稳。
【贴图10】
🎁 加料包:完整可运行项目,直接拿走
上面这套 demo 我打包好了——e2e-demo/ 是能直接跑的真项目(package.json、e2e.config.ts、app/server.js、tests ×2 全都在),配上一份《tester-army/e2e 快速上手手册》:完整项目结构 + 指令执行层级表 + 完整代码 + 踩坑 + 落地清单。
公众号后台回复「e2e」,领取《tester-army/e2e 快速上手手册(含完整可运行 demo)》。
附:一键复现清单
e2e-demo/
├── app/server.js # 被测应用
├── e2e.config.ts # 测试配置(自管被测进程)
├── tests/checkout.e2e.ts # 确定性用例(零模型)
├── tests/agent-example.e2e.ts # agent 示例(默认 skip)
└── .e2e/report.json # 运行报告(自动生成)
cd e2e-demo # ← 进项目根
npm install e2e@latest && npm install -D @e2e-dev/web
sudo ./node_modules/.bin/e2e-web install chromium --with-deps
npx e2e run # ← 在项目根跑
本文为真实环境实测记录,代码均已在本地跑通。