1. 项目概述1.1 这套方案到底在解决什么问题端到端测试是软件质量保障链条中最接近真实用户的一环但它也是团队里最容易被嫌弃的一环。接触过TestOps或者自动化测试体系的人应该都有感受单测跑得飞快单元测试覆盖率高得漂亮可是一到E2E层面要么是Selenium脚本一跑就是几十分钟、动不动就因为等待超时莫名失败要么是Playwright框架本身很好用但缺少一套完整、可复现的工程化方案脚本散落在各个业务仓库里没人敢动也没人敢改。这个项目标题里的Onyx测试框架它不是浏览器自动化工具本身而是一套基于Node.js生态构建的、面向端到端测试场景的统一测试执行与调度框架。配合Playwright作为底层浏览器驱动引擎形成了一套从测试组织和编写、到执行与报告输出、再到CI集成的完整闭环。简单说Onyx负责定义规则、组织用例、控制并发、管理生命周期Playwright负责真正去打开浏览器、操作页面、验证业务结果。这套方案面向的核心人群很明确有一定Pytest或Jest经验、但还没有把端到端测试真正落地成体系的测试开发工程师以及被Selenium脚本维护成本折磨到想要换一条路的前端团队成员。它不是那种“看一眼就会”的教程而是可以拿到项目里直接对照实施的全套工程实践。你在本地搭一次大概两三个小时能把基础框架跑通后面逐步把商业关键路径的场景补进去基本就能替代原来靠人工回归的工作量。1.2 为什么是Onyx和Playwright的组合单看Playwright本身它已经提供了非常不错的API体验自动等待、多浏览器支持、网络拦截、Trace Viewer回放这些能力比早期的Selenium要舒服很多。但工具的API好用不意味着团队的测试工程化水平会自动变好。真正让端到端测试在项目里活下去的是那层“看不到”的组织能力用例怎么分组、失败如何重试、测试数据从哪来、跑完的产物怎么归档、和多条测试流水线之间如何协作。Onyx框架在这种场景下的定位就很清晰了——它把测试工程里最容易被忽视的那部分固化成了默认规范。它提供了一套声明式的用例组织方式支持按功能域或业务场景划分测试集内置了执行进度追踪、失败用例自动隔离重跑、执行数据的本地持久化和增量同步能力。配合Playwright的浏览器上下文隔离机制Onyx可以在每一条用例运行前创建一个干净的浏览器环境彻底避免用例之间的状态串扰。很多团队在选型时纠结于“框架”和“库”的边界Playwright已经能跑得很好了为什么还非要套一层Onyx我的理解是如果只是做几个核心冒烟脚本直接用Playwright完全可以但如果目标是让几十个人协作维护上千条用例没有统一的框架约束最后的脚本仓库大概率会变成一座没人愿意碰的危楼。Onyx做的事情不是增加复杂度而是把所有用例的执行节奏、失败策略、产物统一管起来让你写的每一个测试文件都有固定的生命周期和运行契约。2. 方案整体设计与组件拆解2.1 Onyx框架的测试组织模式设计一套端到端测试方案最忌讳的就是上来就写用例。Onyx给我的感觉是它把“先想清楚怎么组织用例”这件事强制变成了第一步。它的核心组织单元是Test Session和Test Group两个层级有点类似于Pytest里的Session和Module但它额外强化了“目录即结构”的约定e2e/ ├── onyx.config.js ├── groups/ │ ├── checkout/ # 支付下单相关用例组 │ │ ├── guest-order.spec.js │ │ └── member-order.spec.js │ ├── account/ # 账号体系相关用例组 │ │ └── login.spec.js │ └── search/ # 搜索链路相关用例组 │ └── keyword-search.spec.js └── fixtures/ ├── users.json └── products.jsonOnyx在加载时会将groups目录下的每个子目录注册为一个独立的Test Group每条用例的标签Tags决定了它归属到哪条执行链路。例如打上smoke标签的用例会自动纳入冒烟合集打上weekly的用例则只在定时流水线里执行。这种约定式设计的好处是测试开发人员不需要阅读几十页框架文档看一遍现有目录结构就能写出符合规范的用例。每个Test Group在执行时是隔离的Onyx会为它们分配独立的资源上下文。在底层这一点依赖的是Playwright的Browser Context机制每一条用例都从全新的Context启动没有共享的Cookie、没有残留的本地存储用例之间的隔离由框架自动保证。2.2 执行引擎的调度与并发策略端到端测试最让人难受的几个痛点全量回归耗时太长、失败用例影响整条流水线、环境不稳定导致重试成本高。Onyx在这些方面做了几件比较务实的事情。第一按依赖关系分层调度。Onyx允许在用例声明中通过dependsOn字段建立显式依赖比如“下单用例”依赖“登录用例”完成前置会话准备。调度器在运行时会先执行被依赖的用例并把会话数据写入隔离存储供后续用例通过Fixture读取。这比让每条用例从头开始准备数据要高效得多也规避了并行执行时抢用同一批账号的问题。第二动态并发分配。Onyx不是简单地把所有用例丢进线程池而是基于每个Test Group的标签和平均历史执行时长估算出合理的并发度。比如参数配置的默认并发Worker数为4但如果某个Group内部有全局资源锁例如只允许一个用户同时在线Onyx支持在该Group上声明maxParallel: 1从框架层面限制并行度。第三失败用例的隔离重跑。E2E最常见的问题就是偶发性失败比如第三方登录回调偶尔超时、CDN资源加载慢导致元素晚出现了几百毫秒。Onyx内置了失败用例的自动重试机制但它不是简单原地重跑而是把失败用例放入一个新的执行队列按--retry-isolated模式单独调度避免重跑时再次因为并发资源竞争导致二次失败。2.3 为什么Playwright是更合适的浏览器驱动层在选型阶段团队内部其实对比过Cypress和Selenium。先说说Cypress它的交互体验和调试工具确实做得很好但它有一个硬约束浏览器上下文固定在同一页面多标签页和跨域场景处理起来很别扭而且Cypress的架构决定了它无法很好地用同一个驱动进程操作多个不同浏览器上下文。而我们的项目里有大量跨系统跳转、第三方支付回调、站内信通知这类跨页面场景用Cypress会绕很远的路。再谈SeleniumWebDriver协议本身设计得比较成熟但它的等待策略过于原始要么是隐式等待配合硬编码sleep要么是显式等待写在业务代码的各个角落。Playwright最大的不同在于它的自动等待是内置在每一个DOM交互动作里的click、fill这类操作会自动等待元素稳定、可见、可操作匹配了真实用户的操作感知。举一个具体的例子。在Selenium里我们要等待一个按钮变得可点击普遍写法是先WebDriverWait再包一层expected_conditions在Playwright里直接page.click(button[data-testidsubmit])框架会自动轮询元素状态直到满足可操作条件或超时。这不仅减少了一大批样板等待代码更重要的是让用例的行为更接近“用户真的在使用系统”的语义。3. 方案落地从零构建Onyx与Playwright测试环境3.1 环境准备与依赖安装这套方案的基础环境要求并不复杂一台能跑Node.js的开发机即可。推荐使用Node.js 18以上版本因为Playwright的浏览器驱动对较新版本Node的兼容性更好同时Onyx框架本身也用到了较新的node:test能力。不过这里需要提前说明Node版本不要太激进地使用最新的奇数版本以20 LTS系列最为稳妥实测下来在CI的镜像里也更不容易出问题。安装依赖分两步。第一步是在项目根目录初始化npm工程并安装Onyx与Playwright核心库npm init -y npm install -D onyx/test-framework playwright playwright/test第二步是安装浏览器内核。很多新手在这里会漏掉光装npm包但系统里没有浏览器内核跑起来会直接报browserType.launch: Executable doesnt exist。执行下面的指令拉取Chromium和Firefox即可npx playwright install chromium firefox如果是CI环境还可以追加--with-deps参数让Playwright自动处理系统层面的依赖库避免在Ubuntu镜像里出现缺libnss3这类动态库的问题。这一步看起来简单但实际踩坑概率很高后面我会在常见问题里展开讲。3.2 创建Onyx配置文件Onyx框架约定的配置文件是onyx.config.js放在e2e目录的根目录。这个文件承担三层职责加载测试组、配置执行参数、注入环境变量。一个可用的最小配置长这样module.exports { // 指定测试用例根目录 testDir: ./groups, // 默认并发Worker数 workers: 4, // 失败重试策略 retry: { // 最多重试2次 maxRetries: 2, // 开启隔离重跑模式 isolated: true, }, // 全局超时时间毫秒 timeout: 60000, // 测试报告输出目录 outputDir: ./reports, // 注入到用例中的全局环境变量 env: { BASE_URL: process.env.E2E_BASE_URL || https://staging.example.com, API_PREFIX: /api/v1, }, // 是否在本地运行时开启headed模式 headed: process.env.E2E_HEADED 1, };这里有几个参数值得展开说。timeout是单条用例的执行超时E2E用例因为涉及真实网络请求建议给到60秒到90秒太短会导致稳定业务场景误报失败太长又会让失败用例拖着整条流水线慢如蜗牛。workers表示并发数它不等于越多越好如果测试环境是共享的staging环境过高的并发会把后端服务压出各种偶发超时建议先从1个Worker跑通再逐步加压。env这一层很关键。它允许你在不同环境下复用同一份测试代码开发环境、测试环境、预发布环境只需要通过外部环境变量E2E_BASE_URL切换即可。在CI流水线里每个环境跑一遍同一套用例这比在测试代码里硬编码URL要安全得多。3.3 编写第一个Onxy测试用例配置好框架之后来写一条真正能跑的用例。沿用前面的目录结构在groups/account/下新建login.spec.js内容如下const { test, expect } require(onyx/test-framework); const { chromium } require(playwright); test(普通用户可以通过密码登录系统, async ({ browser }) { // 从全局Context创建一个全新的浏览器上下文隔离的会话环境 const context await browser.newContext(); const page await context.newPage(); // 访问登录页 await page.goto(${process.env.BASE_URL}/login); // 填充登录表单 await page.getByLabel(用户名).fill(tester01); await page.getByLabel(密码).fill(Passw0rd!); // 提交登录 await page.getByRole(button, { name: 登 录 }).click(); // 断言登录成功后跳转到首页且能看到用户昵称 await expect(page).toHaveURL(/\/dashboard/); await expect(page.getByText(欢迎回来测试用户)).toBeVisible(); // 关闭上下文释放资源 await context.close(); });这段用例里有几个地方值得新手特别注意。test(..., async ({ browser }) {})里解构出来的browser是Onyx通过Hook注入的全局浏览器实例。Onyx会在所有用例执行前启动Playwright浏览器进程并在整个Test Session结束时统一关闭。每条用例内部必须显式调用browser.newContext()来创建隔离上下文如果忘了这一步直接使用默认Context等于把这条用例和其他用例的会话状态混在一起了这恰恰是长期维护E2E测试时最隐蔽的坑。getByLabel和getByRole这类查询器是Playwright推荐的选择器方式。它们模仿用户感知页面的方式去定位元素比依赖CSS类名或XPath稳定得多。前端同学只要不把for属性和label的关联改坏这类定位器在重构样式时几乎不会受到影响。反过来如果测试代码里到处是page.$(.btn-primary)这样的类选择器前端一次CSS命名调整就能让几十条用例同时变红。3.4 用Fixture管理测试数据现实项目里测试用例几乎不可能只依赖一组写死的账号。登录场景只是最基础的往下走就会遇到不同权限级别的用户、不同的商品SKU、不同的订单状态。如果每一条用例里都去数据库造数据或者调接口注册账号用例的可读性和独立性会急剧下降。Onyx提供了一套Fixture机制来处理这件事。在fixtures/目录下放一份JSON数据源配合loadFixture方法在用例里引用const { test, expect, loadFixture } require(onyx/test-framework); test(会员用户可以将商品加入购物车, async ({ browser }) { const fixture await loadFixture(users.json); const memberUser fixture.users.find(u u.role member); const context await browser.newContext(); const page await context.newPage(); // 登录会员账号 await page.goto(${process.env.BASE_URL}/login); await page.getByLabel(用户名).fill(memberUser.username); await page.getByLabel(密码).fill(memberUser.password); await page.getByRole(button, { name: 登 录 }).click(); // 后续业务步骤 await page.goto(${process.env.BASE_URL}/products/1001); await page.getByRole(button, { name: 加入购物车 }).click(); await expect(page.getByLabel(购物车数量)).toHaveText(1); await context.close(); });这里要注意loadFixture在Onxy的默认行为里是每次调用都会读取一次JSON文件所以不要把重量级的数据都塞进Fixture里。合理的做法是Fixture只保存测试身份数据和基础的静态业务数据动态变化的数据比如一个“可用优惠券”的编号应该通过API请求实时获取或者通过环境变量注入否则测试跑久了会出现数据过期问题。4. 关键机制解析自动等待、网络拦截与Trace回放4.1 自动等待机制到底做了什么Playwright的自动等待是它和Selenium拉开差距的地方之一。我见过不少从Selenium转过来的开发习惯了显式等待之后刚接触Playwright时反而担心它“不知道等到什么时候”。其实Playwright对每个操作都有内置的可操作性检查元素是否附加到DOM、是否可见、是否稳定元素位置不变化、是否被其他元素遮挡、是否可接收事件。只有当这些条件全部满足时操作才会执行否则会一直等到超时时间截止。这套机制最直观的价值体现在页面重渲染频繁的场景。比如单页应用里点击一个Tab后组件异步加载Loading状态从出现到消失可能只有几百毫秒。在Selenium里你可能会临时加一个time.sleep(1)去“赌一把”在Playwright里page.click会自动等待元素变成可操作状态再继续下一步完全不需要写sleep。不过自动等待也不是银弹。它等待的是“元素可操作”不保证“数据加载完成”。举个例子一个列表页在请求完成之前渲染了骨架屏列表区域是存在的但内部没有内容此时自动等待认为元素可操作直接去断言列表项数量就很容易抓到空数据。这个场景的正确做法是显式等待某个业务完成标志比如某个“加载完成”的文案出现或者某个请求的响应到达。4.2 网络拦截与Mock策略E2E测试一根筋地跑真实后端请求会有两个麻烦一是后端不稳定测试的结果会被环境拖累二是某些第三方服务短信验证码、支付回调在测试环境里根本没有办法真的触发。Playwright提供了一套完整的网络拦截与Mock能力可以在浏览器发出请求前就拦截下来返回预设的响应内容。Onxy框架里可以这样使用test(未登录用户下单时跳转登录页, async ({ browser }) { const context await browser.newContext(); // 拦截下单接口返回未登录错误 await context.route(**/api/orders, route { route.fulfill({ status: 401, contentType: application/json, body: JSON.stringify({ code: UNAUTHORIZED, message: 请先登录 }), }); }); const page await context.newPage(); await page.goto(${process.env.BASE_URL}/checkout); // 点击提交订单按钮 await page.getByRole(button, { name: 提交订单 }).click(); // 断言被重定向到登录页 await expect(page).toHaveURL(/\/login/); await context.close(); });这里有个经验之谈Mock应该只使用在无法真实还原的外部依赖上而不是把自家后端的接口也mock掉。如果连自家的核心下单接口都mock掉这个E2E测试就退化成了一堆前端交互的“无意义排练”失去端到端验证的真实价值。比较合理的Mock对象是第三方支付网关、短信服务、OAuth授权服务器这些测试环境永远无法真实触达的外部系统。4.3 Trace Viewer让测试失败不再靠猜E2E用例失败之后最原始的排查方式是看终端日志。日志只告诉你哪个断言失败了但不告诉你页面上到底长什么样。Playwright提供了非常实用的Trace功能可以录制整个测试过程中浏览器的内部状态。在Onyx里开启Trace不需要写额外代码。配置文件中设置trace: { enabled: true, // 只在失败时保留trace减少磁盘占用 saveOnlyOnFailure: true, },跑完测试后reports目录下会生成.zip格式的Trace文件包含完整的DOM快照、网络请求记录、控制台输出和每个操作的截图。用Playwright的Trace Viewer打开后你可以像放录像一样回放整条用例的执行过程查看每一步操作发生时页面上的真实状态。这个能力在排查“偶发失败”时价值极大。比如一条用例昨天跑得好好的今天突然在点击某个按钮后等待超时从Trace回放里能看到按钮确实被一个遮罩层盖住了再配合网络请求记录发现这个遮罩层在某个接口响应后才消失问题定位就很清楚了。如果没有Trace这种问题大概率要靠反复重跑碰运气。5. 端到端测试的CI接入与执行策略5.1 在流水线里跑出稳定结果本地能跑通的用例跑到CI里变红这是所有E2E测试工程都要面对的一道坎。常见的差别包括CI机器的网络更慢、无浏览器桌面环境、容器内存受限等。要让这套方案在CI里稳定落地需要提前做好几件事。第一不要把浏览器以headless模式跑在有桌面的镜像里。听起来有点绕实际意思是CI机器本身不需要显示服务Playwright在无头模式下是不依赖X Server的。但如果镜像缺少操作系统的共享库比如libatk、libcups浏览器进程启动就会失败。在Dockerfile里用Playwright官方镜像作为基础镜像或者执行npx playwright install --with-deps都可以一次性装齐依赖。第二将E2E拆成冒烟集和全量集。冒烟集只跑主流程用例控制在5分钟以内每次代码合并后触发全量集放在夜间定时任务里跑。Onyx的标签机制在这里发挥作用冒烟集只执行smoke标签的用例全量集跑除了daily-skip之外的所有用例。这样做的好处是开发迭代里快速得到反馈又不牺牲深夜的完整回归覆盖面。第三失败通知必须附带可直接打开的Trace链接。在CI的产物归档中把Trace文件上传到对象存储并在钉钉或邮件通知里附带链接。测试开发同学点开链接就能开始排查而不是重新在本地跑一遍后者在环境不一致时往往复现不出CI里的问题。一个可参考的流水线步骤大致如下stages: - e2e-smoke - e2e-full e2e-smoke: stage: e2e-smoke script: - npm ci - npx playwright install --with-deps chromium - npx onyx run --tags smoke --headedfalse artifacts: paths: - e2e/reports/** when: always e2e-full: stage: e2e-full script: - npm ci - npx playwright install --with-deps chromium - npx onyx run --tags not flaky --headedfalse artifacts: paths: - e2e/reports/** when: always5.2 并发与隔离的工程取舍关于CI里的并发这里要聊得更深一点。E2E用例和单元测试不一样它们的并发不是单纯地增加线程数而是要同时考虑后端测试环境的承载能力。一个4核8G的staging后端容器同时服务20个无头浏览器发来的请求往往会出现响应延迟飙升。这种情况下Playwright侧的用例不会直接报错但超时率会明显上升最终表现为测试套件“今天全绿、明天一堆偶发失败”。一个务实的做法先保守地跑串行把每一条用例的执行时间和稳定性基线建立起来。然后逐渐增加并发观察两条指标——用例平均耗时和失败率。当失败率开始出现与代码变更无关的波动时就说明并发数已经触顶了。把这组数据记录下来写进Onxy配置里后续CI扩容后可以再往上调整。另一个容易翻车的地方是测试账号的隔离。如果两条用例并发使用同一个账号登录就会互相踢掉对方的会话导致断言失败。Onxy的隔离上下文虽然能隔开浏览器状态但隔不开后端账号状态。所以测试账号的数量至少要大于并发Worker数并且让Fixture按Worker序号动态分配账号。例如把账号池命名为tester01到tester10在用例里根据Worker编号取号彻底锁死账号冲突问题。6. 真实项目里的疑难杂症与排查速查表6.1 高频问题实录与解决路径跑E2E测试的过程中你会反复遇到几类问题。这里我直接列一份速查表每条都附上排查思路希望能帮你少踩几次坑。问题现象常见原因排查思路与解决路径浏览器启动报Executable doesnt exist只安装了npm包没有下载浏览器内核执行npx playwright install确认缓存目录权限用例执行到goto时超时目标环境无法访问或请求被防火墙拦截先用curl测试URL连通性再检查代理环境变量点击按钮后元素仍不可见页面存在覆盖层或请求未完成用Trace回放确认现场定位覆盖层的触发条件不同环境下部分用例失败测试环境数据差异或域名配置写死检查是否所有URL都取自env.BASE_URL禁止硬编码并发跑时登录状态互相影响测试账号不足组建账号池并按Worker序号分配确保池子大小大于并发数断言数量时偶发失败前端接口返回慢于DOM渲染完成等待业务标志元素而不是直接断言列表项数量CI环境跑不过但本地正常系统依赖库缺失用官方镜像或执行npx playwright install --with-depsTrace文件太大CI产物归档慢全量用例都保存了Trace配置saveOnlyOnFailure: true只保留失败用例Trace6.2 对偶发失败说再见的实操经验偶发失败是E2E测试维护团队意志力的最大消耗源。一条用例今天过了明天没碰任何代码却红了如果团队选择“重跑一把看看”测试结果的可信度就会快速崩塌。我在多个项目里实践下来这套组合拳比较有效。第一给用例打上稳定性标签。在Onxy中可以用stable和flaky区分用例状态。新写的用例默认不带稳定标签只有连续运行10次以上、期间无代码变更且全绿才能升级为stable。这条下限强约束能阻止不稳定的用例污染主流程的门禁。第二失败自动建单。这是比失败重试更有效的一层保障。CI里失败时自动创建一个Issue并把Trace链接、失败日志、运行的提交号全部带过去。就算这个失败在重跑后消失了Issue依然存在积累到一个数量级后统计分析就能发现哪些页面的哪些元素是真正的“脆弱点”。第三用历史数据反哺超时配置。Onxy每次执行后会把每条用例的耗时记录持久化。定期拉一份周期耗时报告把执行时间波动大的用例找出来可能是页面资源加载抖动也可能是后端接口响应不稳定。对这些用例单独放宽超时时间比全局统一延长超时更合理——全局延长只会让真正卡死的用例也拖到很晚才报错。7. 后续扩展这套方案还能怎么长出来Onxy与Playwright这套组合的可扩展性比它第一眼看上去要多不少。如果团队里的E2E测试体系已经跑稳了有几个方向可以继续长出来。一个是视觉回归的融合。Playwright的截图能力可以非常准确地输出页面的像素级快照配合Onxy的Fixture机制可以定期对核心页面做截图对比。相比传统的像素对比工具这套方案的好处是复用现有的页面导航和登录流程不需要单独维护一套截图脚本。另一个是移动端Web测试的统一。Playwright支持通过设备描述符模拟移动端视口和UA把它接入Onxy后同一套用例可以在桌面和移动视口下各跑一遍。对于纯Web业务、没有独立App的团队来说移动端H5的回归成本可以压得很低。还有一类演进是把E2E和性能看板打通。Onxy执行过程中会记录每个关键操作的耗时这些数据导出后与前端性能监控平台交叉比对能在用户大规模反馈“页面变慢”之前先发现核心链路的性能劣化。我个人的体会是E2E测试不是一次性搭建完就结束的工程它更像是在项目里养一个需要长期调整节奏的守护进程。工具的选型固然重要但让用例保持稳定、让失败可以快速定位、让团队愿意持续维护才是这套方案真正的价值所在。最后分享一个小技巧在Onxy配置里为每一条用例加上业务需求的编号作为标签比如story-12345当一条用例失败时你能直接从标签反查PRD和需求文档省掉大量“这个用例当初是验证什么来着”的考古时间。
