「漫说测试」· 实战实测一个真实跑通的 demo 全记录装包 → 配置 → 用例 → 出报告附完整可运行项目 指令执行层级 踩坑指南。【贴图1】一、先说结论能跑而且很好上手。我用tester-army/e2ev0.18.0建了一个最小项目一个登录表单 购物车页面用浏览器真实点击「登录 → 加购 ×2」两条用例全绿耗时3.45 秒并生成了机器可读的report.json。最香的一点确定性用例只用定位器 断言全程零模型调用、零 API 费用——这是它比一堆「AI 测试」噱头工具更务实的地方。【贴图2】二、它到底是什么e2e是一个开源的 agentic 端到端测试框架核心玩法是用自然语言描述目标让 agent 自己驱动页面agent.act/agent.assert也可以用传统定位器 断言做精确校验screenexpect关键设计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 e2elatest|项目根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.0npm 11.16.0。五、三步跑通第 0 步建目录、初始化先「进项目根」mkdire2e-democde2e-demonpminit-y第 1 步装包在项目根# 核心 CLI / SDKnpminstalle2elatest# 浏览器引擎它内部锁死 playwright-core千万别再单独装 playwrightnpminstall--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 httprequire(node:http);const PORTNumber(process.env.PORT||4173);const PAGE!doctype htmlhtmllangenheadmetacharsetutf-8titleAcme Storefront/title/headbodyh1Acme Storefront/h1formidsigninlabelforemailEmail/labelinputidemailtypeemaillabelforpasswordPassword/labelinputidpasswordtypepasswordbuttontypesubmitSign in/button/formdividstatusrolestatus/divsectionclassrowhiddenidshopspanItemsincart:/spanspanidcart-count>cart-count0/spanbuttontypebuttonidaddAdd to cart/button/sectionscriptconst statusdocument.getElementById(status);const shopdocument.getElementById(shop);const countEldocument.getElementById(cart-count);letcount0;document.getElementById(signin).addEventListener(submit,(e){e.preventDefault();const emaildocument.getElementById(email).value.trim();if(!email){status.textContentEmail required;return;}status.textContentSigned in as email;shop.hiddenfalse;});document.getElementById(add).addEventListener(click,(){count1;countEl.textContentString(count);});/script/body/html;http.createServer((req,res){ if(req.url/){ res.writeHead(200,{content-type:text/html;charsetutf-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.tsimporttype{E2EConfig}frome2e;import{web}frome2e-dev/web;exportdefault{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.tsimport{test}frome2e-dev/web;import{expect}frome2e;test(a shopper signs in and adds two items to the cart, async({app,screen}){await app.open(/);await screen.getByLabel(Email).fill(qaexample.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 qaexample.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 ✓ targetwebcommandready 121ms ✓|web|tests/checkout.e2e.ts(2tests)2.78s Test Files1passed(1)Tests2passed(2)Duration3.45s → Report .e2e/report.jsonreport.json里关键字段status: passed、exitCode: 0——CI 门禁可以直接拿退出码判断。【贴图9】七、踩坑记录唯一一个现象第一次运行直接报错——errorwhileloading shared libraries: libatk-1.0.so.0: cannotopenshared objectfile原因容器/裸机缺少 Chromium 的系统依赖库。解决在项目根执行官方推荐命令--with-deps会顺带把系统库装好sudo./node_modules/.bin/e2e-webinstallchromium --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。WindowsPowerShell注意|事项|Linux/macOS|WindowsPowerShell|| — | — | — ||装 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_DISABLED1。八、进阶加上 agent自然语言步骤确定性用例很稳但真正「agentic」的部分长这样// 需要先在 config 里配置模型 登录 await agent.act(sign in with the email qaexample.test and the password hunter2-hunter2);await agent.assert(the page confirms the user is signed in);启用方式二选一在项目根# 方式 A用订阅登录ChatGPT Plus/Pronpx e2e login openai# 方式 B用 API KeyexportAI_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-demo/ ├── app/server.js# 被测应用├── e2e.config.ts# 测试配置自管被测进程├── tests/checkout.e2e.ts# 确定性用例零模型├── tests/agent-example.e2e.ts# agent 示例默认 skip└── .e2e/report.json# 运行报告自动生成cde2e-demo# ← 进项目根npminstalle2elatestnpminstall-De2e-dev/websudo./node_modules/.bin/e2e-webinstallchromium --with-deps npx e2e run# ← 在项目根跑本文为真实环境实测记录代码均已在本地跑通。