实测|2026 最火的 agentic 测试框架 tester-army/e2e,我 10 分钟跑通了第一个用例

873 阅读7分钟

图片

「漫说测试」· 实战实测

一个真实跑通的 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     # ← 在项目根跑

本文为真实环境实测记录,代码均已在本地跑通。