WebdriverIO 测试框架集成实战指南：Mocha、Jasmine、Cucumber 与 Serenity/JS

WebdriverIO 测试框架集成实战指南Mocha、Jasmine、Cucumber 与 Serenity/JS【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverioWebdriverIO 的 Testrunner测试运行器为 Mocha、Jasmine 与 Cucumber.js 提供了开箱即用的内置支持同时也可通过适配器包接入 Serenity/JS 等第三方开源框架。本文以 Frameworks.md 为核心结合仓库内wdio-mocha-framework、wdio-jasmine-framework、wdio-cucumber-framework三个适配器的源码实现系统讲解每个框架的安装方式、mochaOpts/jasmineOpts/cucumberOpts配置项、命令行参数透传、条件跳过skip、报告发布等进阶用法读完即可在实际wdio.conf配置文件中落地可运行的测试套件。集成方式概览WebdriverIO Runner 内置支持三个测试框架Mocha、Jasmine 与 Cucumber.js此外还能与 Serenity/JS 等第三方开源框架集成。要在 WebdriverIO 中使用某个测试框架核心是安装对应的适配器包adapter packageMocha →wdio/mocha-frameworkJasmine →wdio/jasmine-frameworkCucumber →wdio/cucumber-frameworkSerenity/JS →serenity-js/webdriverio等一组模块:::tip 适配器安装位置 适配器包必须安装在 WebdriverIO 所在的同一位置。如果你将 WebdriverIO 全局安装请务必将适配器包也全局安装反之亦然。 :::集成测试框架后你可以在 spec 文件或 step definitions 中通过全局browser变量直接访问 WebDriver 实例而无需手动管理会话生命周期——WebdriverIO 会负责实例化并结束 Selenium 会话browser对象的初始化、beforeSession等钩子都由 Testrunner 统一调度。使用 MochaMocha 是 WebdriverIO 默认推荐的测试框架之一采用 describe/it 的 BDD 风格组织用例。安装与基础断言首先从 NPM 安装适配器包npm install wdio/mocha-framework --save-devWebdriverIO 默认内置了一套 断言库安装完成后即可直接使用无需额外引入describe(my awesome website, () { it(should do some assertions, async () { await browser.url(https://webdriver.io) await expect(browser).toHaveTitle(WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO) }) })注意Mocha 用例中所有 WebdriverIO 命令都必须以await调用WebdriverIO v7 起全面转向异步 API。三种接口风格WebdriverIO 支持 Mocha 的BDD默认、TDD与QUnit接口。若想使用 TDD 风格编写 spec在配置的mochaOpts中设置ui: tdd测试文件即可改写成如下形式suite(my awesome website, () { test(should do some assertions, async () { await browser.url(https://webdriver.io) await expect(browser).toHaveTitle(WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO) }) })从 Mocha 选项类型定义 可以看到ui的合法取值包括bdd | tdd | qunit | exports。其他 Mocha 专有设置都可以通过配置中的mochaOpts键指定。done回调不再支持Mocha 中已废弃的done回调用法在 WebdriverIO 中不被支持以下写法会抛出done is not a functionit(should test something, (done) { done() // throws done is not a function })原因是适配器将每个测试体包装为返回 Promise 的异步函数done已无注入入口。请改用async/await或返回 Promise。命令行透传框架选项mochaOpts不仅可以在配置文件中声明还可以作为命令行参数透传WDIO 会将其解析为实际的 Mocha 选项wdio run wdio.conf.ts --mochaOpts.grep my test --mochaOpts.bail --no-mochaOpts.checkLeaks该命令最终等效于传递如下 Mocha 选项{ grep: [my-test], bail: true checkLeacks: false }其中--no-mochaOpts.checkLeaks用于将布尔选项置为false。从源码看Mocha 适配器入口 会先通过handleRequires处理require选项中的模块并按rootDir解析为绝对路径再用合并后的mochaOpts构造new Mocha(mochaOpts)实例随后应用grep/invert过滤并执行测试。Mocha Options 一览以下选项可在wdio.conf.js的mochaOpts中配置。需要说明的是并非所有 Mocha 选项都被支持例如parallel选项会直接报错——WDIO Testrunner 拥有自己的一套并行执行机制按 capability/spec 分片到多 worker。选项类型默认值说明requirestring\|string[][]加载指定模块用于添加或扩展基础功能WebdriverIO 框架级选项compilersstring[][]使用指定模块编译文件编译模块会先于 require 被加载WebdriverIO 框架级选项allowUncaughtbooleanfalse是否传播未捕获的错误bailbooleanfalse首个测试失败后立即终止checkLeaksbooleanfalse检查全局变量泄漏delaybooleanfalse延迟根套件执行fgrepstringnull按给定字符串过滤测试forbidOnlybooleanfalse标记为only的测试将使整个套件失败forbidPendingbooleanfalse存在 pending 测试时使套件失败fullTracebooleanfalse失败时输出完整堆栈globalstring[][]期望存在于全局作用域的变量grepRegExp\|stringnull按正则表达式过滤测试invertbooleanfalse反转测试过滤结果retriesnumber0失败测试的重试次数timeoutnumber30000超时阈值毫秒在适配器运行过程中beforeSuite/afterSuite会被包装为 Mocha 原生的beforeAll/afterAll钩子执行而beforeTest/afterTest等配置钩子则通过executeHooksWithArgs依次调用套件执行时长、测试 UID 生成等细节也由适配器在emit阶段统一计算并发送给报告器。使用 JasmineJasmine 是另一个被内置支持的测试框架采用describe/it结构并自带丰富的匹配器。安装与配置首先安装适配器包npm install wdio/jasmine-framework --save-dev然后通过配置中的jasmineOpts属性配置 Jasmine 环境。同样支持命令行透传wdio run wdio.conf.ts --jasmineOpts.grep my test --jasmineOpts.failSpecWithNoExpectations --no-jasmineOpts.random从 Jasmine 适配器入口 源码可以看到适配器实例化时会通过Object.assign({ cleanStack: true }, ...)合并jasmineOpts同时兼容历史遗留的jasmineNodeOpts键并将cleanStack等选项交给内部JasmineReporter使用测试接口固定为 BDD 风格beforeAll、beforeEach、it、fit、xit、afterEach、afterAll。Jasmine Options 一览以下选项可通过配置中的jasmineOpts属性应用选项类型默认值说明defaultTimeoutIntervalnumber60000Jasmine 操作的默认超时时间毫秒helpersstring[][]相对 spec 目录、需在 Jasmine spec 之前加载的文件路径含 glob数组requiresstring[][]用于添加或扩展基础功能所需加载的模块randombooleantrue是否随机化 spec 执行顺序seedFunctionnull随机化使用的种子为null时在开始时随机确定种子failSpecWithNoExpectationsbooleanfalse未运行任何断言的 spec 是否被判为失败默认报告为通过oneFailurePerSpecbooleanfalsespec 是否只保留第一个断言失败specFilterFunction(spec) true用于过滤 spec 的函数grepstring\|Regexpnull只运行匹配该字符串或正则的测试仅在未设置自定义specFilter时生效invertGrepbooleanfalse为true时反转grep匹配结果仅在未设置自定义specFilter时生效在 Jasmine 选项类型定义 中还可看到expectationResultHandler、stopOnSpecFailure、stopSpecOnExpectationFailure等更细粒度选项前者允许在每个断言完成后回调例如在断言失败时自动截图。使用 CucumberCucumber 是行为驱动开发BDD的核心工具以.feature文件描述业务行为并通过 step definitions 将其映射到自动化代码。安装与启用安装适配器包npm install wdio/cucumber-framework --save-dev然后在 配置文件 中把framework设为cucumberexport const config { // ... framework: cucumber, cucumberOpts: { // ... } }Cucumber 的全部选项通过cucumberOpts提供。仓库内 Cucumber 默认选项 定义了所有选项的初始值适配器在构造时用Object.assign({}, DEFAULT_OPTS, config.cucumberOpts)合并用户配置并自动在format中注入自带的cucumberFormatter把 Cucumber 运行事件转发给 WebdriverIO 报告器。命令行调整选项cucumberOpts中的选项例如用于过滤测试的自定义tags可通过命令行指定格式为cucumberOpts.{optionName}value# 只运行带有 smoke 标签的测试 npx wdio run ./wdio.conf.js --cucumberOpts.tagssmoke # 按场景名称过滤 首个失败即中止 npx wdio run ./wdio.conf.js --cucumberOpts.namesome scenario name --cucumberOpts.failFast上述命令会把cucumberOpts.tags设为smoke确保只有带该标签的测试被执行。Cucumber Options 一览以下选项可通过配置中的cucumberOpts属性应用选项类型默认值说明backtraceBooleantrue是否显示错误完整回溯requireModulestring[][]在加载任何 support 文件之前需要 require 的模块failFastbooleanfalse首个失败后立即中止运行nameRegExp[][]只执行名称匹配表达式的场景可重复requirestring[][]执行 feature 前需要加载含 step definitions的文件支持 globimportString[][]ESM 场景下 support 代码所在路径strictbooleanfalse存在未定义或 pending 步骤时判为失败tagsString只执行标签匹配表达式的 feature 或场景timeoutNumber30000step definitions 的超时毫秒retryNumber0失败用例的重试次数retryTagFilterRegExp—只对标签匹配表达式的 feature/场景重试需同时指定retrylanguageStringenfeature 文件的默认语言orderStringdefined按固定或随机顺序运行测试formatstring[]—使用的 formatter 名称与输出文件路径WebdriverIO 主要支持将输出写入文件的 formatterformatOptionsobject—提供给 formatter 的选项tagsInTitleBooleanfalse将 Cucumber 标签追加到 feature/场景名称wdio/cucumber-framework专有选项cucumber-js 本身不识别ignoreUndefinedDefinitionsBooleanfalse将未定义定义视为警告专有选项failAmbiguousDefinitionsBooleanfalse将歧义定义视为错误专有选项tagExpressionString标签匹配表达式的旧写法即将废弃请改用tagsprofilestring[][]指定要使用的 profile关于profile请注意profile 内仅支持worldParameters、name、retryTagFilter这几个取值因为cucumberOpts优先级更高且使用 profile 时务必不要在cucumberOpts中重复声明这些值。:::note 默认值核对 文档表格中的backtracetrue与timeout30000默认值与当前仓库 constants.ts 中DEFAULT_OPTS略有差异源码中backtrace: false、timeout取DEFAULT_TIMEOUT 60000。以你所安装的版本实际行为为准。 :::此外和 Mocha 一样Cucumber 的parallel选项在 WebdriverIO 中也不受支持——Cucumber 适配器入口 会在构造阶段直接抛出The option parallel is not supported by WebdriverIO因为并行执行由 WDIO 自身的多 worker 机制负责。requireModule 示例requireModule可用于加载babel/register、ts-node等编译/转译模块甚至支持带配置项的数组形式cucumberOpts: { requireModule: [babel/register] // 或 requireModule: [ [ babel/register, { rootMode: upward, ignore: [node_modules] } ] ] }源码中的registerRequiredModules()也支持三种形式字符串直接import、[module, config]数组形式导入后调用其 default 并传入配置、以及自定义函数直接调用。require / import 示例cucumberOpts: { require: [path.join(__dirname, step-definitions, my-steps.js)] }cucumberOpts: { import: [path.join(__dirname, step-definitions, my-steps.js)] }require用于 CommonJS 风格、import用于 ESM 风格加载 support 代码两者都支持 glob。适配器在loadFiles阶段会分别展开 glob并在每次运行前清理require.cache从而支持同一次进程内重跑 step definitions 文件。按 capabilities 条件跳过测试skip普通 Cucumber 的标签过滤能力作用于全部配置的浏览器/设备无法针对某个 capability 组合跳过。为此 WebdriverIO 为 Cucumber 提供了专有的标签语法skip([condition])其中condition是可选的能力capabilities属性及取值组合当所有属性都匹配时被标记的场景或 feature 才会被跳过。你也可以在场景/feature 上叠加多个skip标签以满足多种不同的跳过条件。使用skip注解而不修改tagExpression时被跳过的测试仍会显示在测试报告中。语法示例skip或skip()总是跳过被标记项skip(browserNamechrome)不会对 chrome 浏览器执行该测试skip(browserNamefirefox;platformNamelinux)跳过 firefox linux 组合下的执行skip(browserName[chrome,firefox])对 chrome 和 firefox 浏览器都跳过skip(browserName/i.*explorer/)跳过浏览器名匹配该正则的 capabilities如iexplorer、internet explorer、internet-explorer等其实现位于 Cucumber 工具函数 的generateSkipTagsFromCapabilities()适配器先用Gherkin.compile将 feature 编译为 pickles 提取所有标签再把skip(...)表达式解析为键值对逐一与当前 worker 的 capabilities 匹配匹配成功时生成(not skip...)形式的 Cucumber 标签表达式注入到cucumberOpts.tags从而在运行前就实现条件跳过。导入 Step Definition 辅助函数通常Given、When、Then及各类钩子从cucumber/cucumber导入import { Given, When, Then } from cucumber/cucumber但如果你在其他与 WebdriverIO 无关的测试中也使用了不同版本的 Cucumber则应在 e2e 测试中从 WebdriverIO 的 Cucumber 包导入这些辅助函数import { Given, When, Then, world, context } from wdio/cucumber-framework这能确保在 WebdriverIO 框架内使用正确的辅助函数同时允许你在其他类型的测试中保持独立的 Cucumber 版本。从源码看适配器文件末尾执行了export * from cucumber/cucumber重导出并且setDefinitionFunctionWrapper会为带retry的步骤包装同步/异步执行器以支持步骤级重试。发布 Cucumber 报告Cucumber 原生支持把测试运行报告发布到https://reports.cucumber.io/通过cucumberOpts.publish或CUCUMBER_PUBLISH_TOKEN环境变量控制。但直接使用 WebdriverIO 执行测试时该方式会为每个 feature 文件分别更新报告难以查看汇总结果。为此wdio/cucumber-framework提供了基于 Promise 的方法publishCucumberReport推荐在onComplete钩子中调用入参为存放 cucumber message 报告的目录通过cucumberOpts.format生成cucumber message报告建议为文件名使用动态命名如 UUID避免覆盖报告、确保每次运行都被准确记录设置以下环境变量CUCUMBER_PUBLISH_REPORT_URL报告发布 URL未设置时默认使用https://messages.cucumber.io/api/reportsCUCUMBER_PUBLISH_REPORT_TOKEN发布所需的授权 token未设置则该函数直接退出、不发布报告配置与代码示例import { v4 as uuidv4 } from uuid import { publishCucumberReport } from wdio/cucumber-framework; export const config { // ... Other Configuration Options cucumberOpts: { // ... Cucumber Options Configuration format: [ [message, ./reports/${uuidv4()}.ndjson], [json, ./reports/test-report.json] ] }, async onComplete() { await publishCucumberReport(./reports); } }其中./reports/是存放cucumber message报告的目录。从 Cucumber 适配器入口 的publishCucumberReport实现可以看到其完整流程先GET请求报告服务获取location响应头再读取目录下所有.ndjson文件合并内容最后以PUT Bearer Token 方式上传报告。使用 Serenity/JSSerenity/JS 是一个开源框架旨在让复杂软件系统的验收测试与回归测试更快、更具协作性、更易规模化。对 WebdriverIO 测试套件Serenity/JS 主要提供三类能力增强报告Enhanced Reporting作为任何内置 WebdriverIO 框架的即插即用替代品产出深度测试执行报告与项目活文档living documentationScreenplay 模式 API在原生 WebdriverIO API 之上提供可选抽象层让测试代码跨项目、跨团队可移植复用集成库Integration Libraries为遵循 Screenplay 模式的套件提供编写 API 测试、管理本地服务器、执行断言等可选集成能力。安装 Serenity/JS为已有的 WebdriverIO 项目添加 Serenity/JS从 NPM 安装以下模块npm install serenity-js/{core,web,webdriverio,assertions,console-reporter,serenity-bdd} --save-dev各模块职责serenity-js/core为核心库serenity-js/web提供 Web 交互原语如Navigate、Pageserenity-js/webdriverio提供 WebdriverIO 集成与BrowseTheWebWithWebdriverIO能力serenity-js/assertions提供断言serenity-js/console-reporter负责向标准输出打印执行结果serenity-js/serenity-bdd负责下载与调用 Serenity BDD CLI 生成报告。配置 Serenity/JS将framework设为serenity-js/webdriverio并在serenity配置中指定底层测试运行器与报告服务stage crew。TypeScript 版本import { WebdriverIOConfig } from serenity-js/webdriverio; export const config: WebdriverIOConfig { // Tell WebdriverIO to use Serenity/JS framework framework: serenity-js/webdriverio, // Serenity/JS configuration serenity: { // Configure Serenity/JS to use the appropriate adapter for your test runner runner: cucumber, // runner: mocha, // runner: jasmine, // Register Serenity/JS reporting services, a.k.a. the stage crew crew: [ // Optional, print test execution results to standard output serenity-js/console-reporter, // Optional, produce Serenity BDD reports and living documentation (HTML) serenity-js/serenity-bdd, [ serenity-js/core:ArtifactArchiver, { outputDirectory: target/site/serenity } ], // Optional, automatically capture screenshots upon interaction failure [ serenity-js/web:Photographer, { strategy: TakePhotosOfFailures } ], ] }, // Configure your Cucumber runner cucumberOpts: { // see Cucumber configuration options below }, // ... or Jasmine runner jasmineOpts: { // see Jasmine configuration options below }, // ... or Mocha runner mochaOpts: { // see Mocha configuration options below }, runner: local, // Any other WebdriverIO configuration };JavaScript 版本与之等价export const config { // Tell WebdriverIO to use Serenity/JS framework framework: serenity-js/webdriverio, // Serenity/JS configuration serenity: { runner: cucumber, // runner: mocha, // runner: jasmine, crew: [ serenity-js/console-reporter, serenity-js/serenity-bdd, [ serenity-js/core:ArtifactArchiver, { outputDirectory: target/site/serenity } ], [ serenity-js/web:Photographer, { strategy: TakePhotosOfFailures } ], ] }, cucumberOpts: { // see Cucumber configuration options below }, jasmineOpts: { // see Jasmine configuration options below }, mochaOpts: { // see Mocha configuration options below }, runner: local, // Any other WebdriverIO configuration };其余 WebdriverIO 配置如 capabilities、reporters、services 等照常保留。生成 Serenity BDD 报告与活文档Serenity BDD 报告与活文档由 Serenity BDD CLI一个 Java 程序生成它由serenity-js/serenity-bdd模块负责下载与托管。要产出报告测试套件需要调用serenity-bdd update下载 Serenity BDD CLI该命令会将 CLI 的jar缓存到本地按上文配置说明注册SerenityBDDReporter产出中间的 Serenity BDD.json报告需要生成报告时调用serenity-bdd run调用 Serenity BDD CLI。Serenity/JS 官方项目模板采用的模式是在package.json中组合postinstall下载 CLI、npm-failsafe即使测试套件失败也继续执行报告流程——这恰恰是最需要报告的时刻与rimraf清理上一次运行遗留的报告{ scripts: { postinstall: serenity-bdd update, clean: rimraf target, test: failsafe clean test:execute test:report, test:execute: wdio wdio.conf.ts, test:report: serenity-bdd run } }使用 Serenity/JS Screenplay 模式 APIScreenplay 模式是一种以用户为中心、强调抽象分层的高质量验收测试编写方式它让测试场景贴近业务语言并促使团队养成良好的测试与软件工程习惯。当把serenity-js/webdriverio注册为 WebdriverIO 的framework后Serenity/JS 会默认配置一组 actors每个 actor 都可以使用BrowseTheWebWithWebdriverIO浏览 Web使用TakeNotes.usingAnEmptyNotepad()记录笔记。这足以让你在既有测试套件中引入 Screenplay 模式的场景。例如 specs/example.spec.ts 所示的用例Screenplay 场景与原生 WebdriverIO 场景可以共存import { actorCalled } from serenity-js/core import { Navigate, Page } from serenity-js/web import { Ensure, equals } from serenity-js/assertions describe(My awesome website, () { it(can have test scenarios that follow the Screenplay Pattern, async () { await actorCalled(Alice).attemptsTo( Navigate.to(https://webdriver.io), Ensure.that( Page.current().title(), equals(WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO) ), ) }) it(can have non-Screenplay scenarios too, async () { await browser.url(https://webdriver.io) await expect(browser) .toHaveTitle(WebdriverIO · Next-gen browser and mobile automation test framework for Node.js | WebdriverIO) }) })小结与进一步探索Mocha默认 BDD支持 TDD/QUnitmochaOpts覆盖超时、重试、grep 过滤等不支持done回调与parallel。实现细节见 wdio-mocha-framework 与其 选项类型定义。JasminejasmineOpts支持随机执行顺序、种子、grep、断言失败策略等并额外提供expectationResultHandler等扩展钩子。实现细节见 wdio-jasmine-framework 与其 选项类型定义。CucumbercucumberOpts提供最丰富的选项支持skip条件跳过、步骤级重试、publishCucumberReport汇总发布报告注意parallel不受支持、tagExpression已废弃。实现细节见 wdio-cucumber-framework、选项类型定义 与 工具函数。Serenity/JS通过framework: serenity-js/webdriverio接入可复用内置的 Cucumber/Jasmine/Mocha 配置同时获得增强报告、活文档与 Screenplay 模式 API。仓库内的 mocha 冒烟测试、jasmine 测试 与 cucumber 测试资源含 features 与 step-definitions是上述配置落地的直接参考样例完整的配置项解析与命令行透传逻辑则可查阅 ConfigurationFile.md 及各适配器源码。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考