WebdriverIO v6 发布详解从 v5 平滑迁移的完整指南【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio导读本篇文章以 WebdriverIO 官方发布的 v6 版本说明原始博客为核心骨架系统梳理这一重大版本更新的全部技术要点弃用 Node v8、将基于 Chrome DevTools 协议的devtools自动化协议设为默认、通过替换 HTTP 依赖实现 4 倍体积缩减、服务配置标准化、命令参数对象化以及内置expect-webdriverio断言库等。读完本文你将掌握从 v5 升级到 v6 的具体操作步骤并理解这些变更背后的源码实现逻辑能够在实际项目中独立完成升级与配置改造。如果你刚在去年投入大量时间迁移到 v5 而担心又要经历一轮痛苦升级大可放心这次大版本更新的“破坏性”远比去年小得多。去年的架构性改动让团队别无选择只能打破大量接口而这次团队非常谨慎确保升级框架不会成为一项繁重的工作。v6 的改动更加合理包含许多细微但有助于项目持续成长、同时保持高性能的调整。本文会详细说明所有主要变更并解释从 v5 迁移到 v6 需要做什么。弃用 Node v8 支持Node v8 已于 2020 年初被 Node.js 官方团队宣布弃用官方不再建议在任何系统上运行基于该版本的应用。WebdriverIO v6 随之放弃了对 Node v8 的支持并强烈建议升级到 Node v12该版本受支持至 2022 年 4 月。如何升级 Node.js升级 Node.js 前需要先弄清楚它最初是如何安装的Docker 环境直接升级基础镜像即可- FROM mhart/alpine-node:8 FROM mhart/alpine-node:12本地环境推荐使用NVMNode Version Manager来安装和管理 Node.js 版本。关于 NVM 的安装与 Node 升级的详细步骤请查阅其项目 README 中的 Installing and Updating 一节。devtools自动化协议成为默认Puppeteer、Cypress.io 等自动化工具的成功证明WebDriver 协议当前的形式已无法完全满足现代开发者和自动化工程师的需求。WebdriverIO 项目成员本身也是定义 WebDriver 规范的W3C Working Group的参与者正与浏览器厂商合作改进现状微软方面也已就类似 Chrome DevTools 协议的**双向连接bidirectional connection**方案提出了提案。在浏览器厂商就新的 WebDriver 架构达成共识之前项目希望提供替代方案——这就是原生支持 Puppeteer、复用同一套 API 的原因。v6 将该能力完整嵌入项目运行本地测试脚本时不再需要下载浏览器驱动。WebdriverIO 会先检查localhost:4444/上是否有正在运行、可访问的浏览器驱动如果没有则自动回退到 Puppeteer。注意仅当测试在本地运行、且浏览器与测试位于同一台机器上时才支持使用 Puppeteer 替代 WebDriver。使用 WebdriverIO API 时WebDriver 与 Puppeteer 的体验应当一致而基于 Puppeteer 运行命令甚至可能更快。能够访问 Puppeteer意味着你可以利用功能远更丰富的 Chrome DevTools 协议。在测试中可以自由地在 Puppeteer 与 WebdriverIO API 之间切换例如describe(my e2e tests, () { // ... it(replaces the WebdriverIO logo with the Puppeteer logo, () { browser.url(https://webdriver.io) /** * 用 Promise 风格运行 Puppeteer 代码拦截网络请求 * 把文档页的 WebdriverIO 图标替换为 Puppeteer 图标 */ const wdioLogo webdriverio.png const pptrLogo https://user-images.githubusercontent.com/10379601/29446482-04f7036a-841f-11e7-9872-91d1fc2ea683.png browser.call(async () { const puppeteerBrowser browser.getPuppeteer() const page (await puppeteerBrowser.pages())[0] await page.setRequestInterception(true) page.on(request, (interceptedRequest) ( interceptedRequest.url().endsWith(wdioLogo) ? interceptedRequest.continue({ url: pptrLogo }) : interceptedRequest.continue() )) }) // 继续使用同步风格的 WebdriverIO 命令 browser.refresh() browser.pause(2000) }) })这里调用的是browser.getPuppeteer()。查看其源码实现 getPuppeteer.ts可以看到它并非简单地直连浏览器它会优先复用已连接的会话this.puppeteer?.connected然后依次尝试 Selenium 4 的se:cdp能力、Selenoid/Moon 的 Aerokube 能力、Chromium 的debuggerAddress甚至对 Firefox ≥ 79 通过moz:debuggerAddress建立 DevTools 连接。从源码结构还可以推断使用 Puppeteer 需要先安装puppeteer-core依赖否则该方法会抛出明确错误。关于“跨浏览器”的坦诚说明WebdriverIO 集成了 Puppeteer因此可以在 Chrome、FirefoxNightly和 Chromium Edge 上运行测试。但请注意这里的“跨浏览器”是带引号的——很多自动化工具在宣传跨浏览器支持时并不真正诚实所有基于 Chromium 的浏览器Google Chrome、Chromium Edge 或基于 Electron 的应用底层使用完全相同的引擎在多个 Chromium 系浏览器上重复测试的价值存疑。此外Firefox 的支持现在是、将来也仍将是实验性的——它由 Mozilla 的一个团队临时实现该团队并未承诺将其带出实验状态或持续维护。项目也没有计划集成 Playwright因为无法承担用户每次安装 WebdriverIO 时都下载其定制浏览器构建的成本团队会观察其发展未来再考虑集成。WebdriverIO 团队同时强调他们仍持续投入于WebDriver这一自动化标准——它至今仍是唯一真正意义上的跨浏览器自动化协议团队始终优先选择由代表整个行业的多元化群体共同制定的标准方案。如何更新如果你的测试已经在 WebDriver 上运行则无需做任何改动。只有当 WebdriverIO 找不到正在运行的浏览器驱动时才会回退到 Puppeteer。性能提升v6 的一大目标是让 WebdriverIO 更快、更高性能。基于 Puppeteer 运行测试本身就能加速本地执行此外团队还优化了其他方面替换 HTTP 依赖v6 移除了重量级依赖request该库已于 2020 年 2 月 11 日全面弃用改用got。由此webdriver与webdriverio两个包的打包体积缩小了4 倍更富可能的运行环境改用got后WebdriverIO 在技术上可以在浏览器内运行这为构建 WebdriverIO 脚本的在线 fiddle 平台路线图中的规划项目创造了可能。内部执行优化v6 附带大量内部改进以加速测试执行、降低 CPU 和内存占用。尤其是在获取元素的路径上显著减少了开销如何更新这些性能改进是“免费”的升级到 v6 时你不需要做任何额外操作就能获得更好性能。服务配置标准化社区构建了大量 wdio-service 服务和 wdio-reporter 报告器这些插件都需要在wdio.conf.js中进行特定配置。v5 及之前服务和报告器的专属选项可以散落在wdio.conf.js的任意位置例如 Sauce 服务// wdio.conf.js exports.config // ... services: [sauce], user: process.env.SAUCE_USERNAME, key: process.env.SAUCE_ACCESS_KEY, region: us, sauceConnect: true, // ... };v6 将所有配置都移入services列表、紧挨着服务定义的位置这样既能保持配置文件结构清晰也让“原生支持的配置项集合”边界一目了然。上面的例子在 v6 中应改写为// wdio.conf.js exports.config // ... user: process.env.SAUCE_USERNAME, key: process.env.SAUCE_ACCESS_KEY, region: us, // WebdriverIO Configuration services: [ [sauce, { sauceConnect: true, // wdio/sauce-service configuration sauceConnectOpts: { // wdio/sauce-service configuration // ... } }] ], // ... };在推进这项工作的同时团队还审视了各服务的选项命名将其改得更短、更精确。如何更新逐一检查你的 WDIO 配置文件找出那些不是由 WebDriver 或 WDIO 官方明确定义的配置项完整的官方配置项说明见 Configuration.md按上面的示例将它们移动到对应的服务列表项中。此外检查服务选项名是否已变更并相应更新。命令接口变更从位置参数到命名参数过去WebdriverIO 在click等单个命令中塞入了大量附加功能通过传入参数来启用。不幸的是参数数量不断膨胀导致混乱且让命令变得难以阅读——比如为了“等待元素不再存在”你曾需要写$(#elem).waitForExist(null, null, true)足以说明问题恶化到了什么程度。v6 改变了多个命令的参数结构改用命名参数named parameters。代码因此更易读使用 TypeScript 时也能获得更好的类型约束。上面的例子在 v6 中变为$(#elem).waitForExist({ reverse: true })这一设计在源码中体现得很清晰。以 waitForExist.ts 为例它的签名是一个解构的WaitForOptions对象包含timeout默认取配置项waitforTimeout、interval默认取waitforInterval、reverse默认false和timeoutMsg默认根据元素选择器与超时时间动态生成四个命名选项实现上它内部委托给waitUntil按reverse标志对isExisting()取反。同样地waitForEnabled.ts 内部也是通过this.waitForExist({ timeout, interval, timeoutMsg })这样的命名参数实现。如何更新v6 改变了以下命令的参数结构受影响的browser方法newWindowreact$react$$waitUntil受影响的 element 方法dragAndDropmoveToreact$react$$scrollIntoViewwaitForClickablewaitForDisplayedwaitForEnabledwaitForExistwaitUntil如果你使用 TypeScript编译器会自动标出所有需要更新的调用点如果不使用 TypeScript则建议在代码库中逐个搜索上述命令并修改。整体来说这是一项机械、直接的任务。新的内置断言库升级到 v6 后你将自动获得新内置断言库expect-webdriverio。这是专为 WebdriverIO 设计的断言库灵感来自 Jest 的expect包关键特性包括等待断言成功自动重试天然契合 WebdriverIO 的自动等待机制详细的错误信息支持 Mocha、Cucumber、Jest 和 Jasmine内置 TypeScript 类型与 JS 自动补全这不仅能简化 WebdriverIO 框架的配置还能在断言失败时给出更好的错误消息。例如检查元素可见性/文本时const elem $(#someElem) expect(elem).toHaveText(Click #2)失败时会得到比传统断言库清晰得多的错误提示明确指出期望文本与实际文本的差异。如何更新如果你已经在使用 Chai 等断言库可以继续使用尤其是当你并不需要expect-webdriverio时。不过你也可以开始用新断言 API 编写新断言在正式淘汰旧库之前两种断言库可以并存。其他值得关注的变更除上述主要更新外v6 还有若干值得一提的细节调整TypeScript 支持改进了 WebdriverIO 与 WebDriver 的类型定义包含更完善的描述与更多细节。WebDriver 默认路径将默认 WebDriver 路径从/wd/hub改为/因为大多数浏览器驱动现在都默认这一路径。这对你通常没有影响——但如果升级后连接 WebDriver 端点遇到问题这可能是原因之一。给 Appium 用户的提示如果你使用本地或全局安装的 Appium并通过命令行启动 Appium还应提供 CLI 参数--base-path /。这能避免 Appium 找不到匹配的本地模拟器/真机而回退到 WebdriverIO 使用的默认path: /。若你使用的是wdio/appium-service则无需任何改动。命令重命名Chrome WebDriver 会话中命令launchApp更名为launchChromeApp。Spec 过滤默认开启Spec Filtering 功能现在默认启用——如果框架在文件中找不到可运行的测试就不会启动浏览器会话且此行为无法再关闭。新钩子测试运行器新增名为onWorkerStart的钩子会在启动 worker 进程前立即执行。源码层面该钩子的调度逻辑位于 launcher.ts——launcher 会先运行用户配置的onWorkerStart钩子再执行各 launcher service 的同名钩子传入runnerId、workerCaps、specs、参数与execArgv对应的配置模板说明见 wdio.conf.tpl.ejs。钩子签名修改修改了 before/after test/hook 等钩子的签名允许你访问框架的原生事件对象。请查阅 ConfigurationFile.md 并据此更新你的钩子。Cucumber 升级wdio/cucumber-framework适配器更新为使用 Cucumber v6。Capabilities 覆盖行为默认情况下使用 launcher 时不再合并 capabilities而是直接覆盖。LTS 支持策略随着 v6 发布WebdriverIO 将在发布新的 v7 大版本之前持续支持 v5。项目建立了向后移植backporting流程能够将 v6 的 bug 修复和特性无缝移植回 v5。请注意随着两个版本的代码逐渐分化并非所有特性和 bug 修复都能回移植维护者可能会要求贡献者将对master分支的 PR 同样提交到v5分支。尽管如此项目仍普遍建议尽快升级到最新版本以确保用上所有已完成的 bug 修复。迁移总结将 v5 升级到 v6 的核心动作可以归纳为四步其一将 Node.js 升级到 v12Docker 则更换基础镜像其二在wdio.conf.js中把各服务/报告器的专属选项收拢进services列表项并同步更新被改名的服务选项其三将上述 14 个命令的调用从位置参数改写为命名参数对象配合 TypeScript 可自动定位其四若遇到连接问题确认 WebDriver 默认路径由/wd/hub改为/后的影响Appium 用户需加--base-path /。至于性能提升与新的expect-webdriverio断言库则无需任何额外操作即可直接受益。整体而言v6 是一次比 v5 温和得多、但长期收益显著的大版本升级。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考