WebdriverIO 配置全指南WebDriver 选项、Testrunner 选项与 Hooks 生命周期详解【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverioWebdriverIO 是面向 Node.js 的下一代浏览器与移动端自动化测试框架。无论你是通过原生 WebDriver 协议绑定、以独立包standalone方式使用 WebdriverIO还是使用 WDIO 测试运行器都需要一份完整可靠的配置说明来掌控测试环境。本文以仓库中的 Configuration.md 为骨架结合wdio-config、wdio-types、webdriver等核心包的源码实现与 examples/wdio.conf.js 示例配置系统讲解 WebDriver 连接选项、WebdriverIO 运行选项、Testrunner 调度选项以及贯穿整个测试生命周期的 Hooks帮助你精确调校配置写出可复制、可运行、可排障的测试工程。WebDriver 连接选项使用webdriver协议包与驱动服务器通信时可以通过以下选项控制连接行为。这些选项在 packages/webdriver/src/constants.ts 中被声明为带类型、默认值、正则校验的Definition并通过validateConfig机制见 packages/wdio-config/src/utils.ts与用户配置合并校验——因此传入错误的类型或非法值会在启动时直接抛出异常而不是在运行中途才暴露。protocol与驱动服务器通信所使用的协议。类型String默认值http源码实现在webdriver包默认配置中以/http|https/正则进行校验仅允许http或https。hostname驱动服务器所在的主机。类型String默认值0.0.0.0文档值源码中为localhost说明本机运行时通常无需修改只有连接远程 Grid、Selenium Server 或云服务时才需要显式指定。port驱动服务器监听的端口。类型Number默认值undefined未设置时由 WebdriverIO 按协议与场景自动推断例如本机 Chromedriver 为9515、Selenium Standalone 为4444。path驱动服务器端点的路径。类型String默认值/说明接入自定义 Grid 网关或代理时可能需要设置为具体的挂载路径。queryParams向驱动服务器传播的查询参数。类型Object默认值undefined典型用途为 Selenium Grid / Selenoid 等后端注入诸如?quota之类的查询串参数。user 与 key类型String默认值undefineduser是你的云服务用户名key是对应的访问密钥/密钥。它们与 Sauce Labs、BrowserStack、TestingBot、TestMu AI原 LambdaTest账号配合时WebdriverIO 会根据你的账号信息自动设置连接选项主机、端口、路径等。即使你不使用云服务商这两个选项也可用于认证任意其他 WebDriver 后端。类型定义见 packages/wdio-types/src/Options.ts。capabilities定义要在 WebDriver 会话中运行的 capabilities。更详细的规范见 WebDriver Protocol如果驱动较旧不支持 W3C 协议则需要改用 JSONWireProtocol 的 DesiredCapabilities。除了 WebDriver 标准 capabilities还可以叠加浏览器与厂商专属的 options 来深度配置远端浏览器或设备常见的包括goog:chromeOptions用于 Google Chromemoz:firefoxOptions用于 Mozilla Firefoxms:edgeOptions用于 Microsoft Edgesauce:options用于 Sauce Labsbstack:options用于 BrowserStackselenoid:options用于 Selenoid类型Object默认值null。{ browserName: chrome, // options: chrome, edge, firefox, safari browserVersion: 27.0, // browser version platformName: Windows 10 // OS platform }在移动端做 Web 或原生测试时capabilities的语义与 WebDriver 协议不同需遵循 Appium 的 capabilities 文档可以看到WebdriverIO 会针对chrome/chromium、firefox、edge分别改写goog:chromeOptions、moz:firefoxOptions、ms:edgeOptions中的--headless参数这解释了为什么wdio run wdio.conf.js --headless能够一键切换无头模式。logLevel日志详细级别。类型String默认值info可选值trace|debug|info|warn|error|silent该类型在 packages/wdio-types/src/Options.ts 中被定义为WebDriverLogTypes。除了全局级别还可以通过logLevels针对单个 logger如webdriver、webdriverio单独设置级别使用silent可完全关闭某个 logger。outputDir存放所有 testrunner 日志文件包括 reporter 日志与wdio日志的目录。若不设置所有日志流式输出到stdout。由于多数 reporter 天生面向stdout官方建议仅对确实需要落盘的 reporter如junit开启此选项。在 standalone 模式下WebdriverIO 唯一生成的日志就是wdio日志。类型String默认值nullconnectionRetryTimeout任何 WebDriver 请求到驱动或 Grid 的超时时间。类型Number默认值120000毫秒源码默认值可在 packages/webdriver/src/constants.ts 的connectionRetryTimeout定义中确认默认120000。connectionRetryCount到 Selenium 服务器的请求重试最大次数。类型Number默认值3bidiResponseTimeoutWebDriver Bidi 命令等待浏览器响应的超时时间毫秒。如果你运行的命令例如execute在合法情况下耗时较长应调大此值否则 WebdriverIO 会在浏览器完成前就放弃等待。类型Number默认值180000agent允许使用自定义的http/https/http2agent 发起请求。类型Object默认值{ http: new http.Agent({ keepAlive: true }), https: new https.Agent({ keepAlive: true }) }headers向每个 WebDriver 请求注入自定义headers。如果你的 Selenium Grid 需要 Basic 认证推荐通过此选项传入Authorization头。示例读取环境变量并做 Base64 编码import { Buffer } from buffer; // 从环境变量读取用户名和密码 const username process.env.SELENIUM_GRID_USERNAME; const password process.env.SELENIUM_GRID_PASSWORD; // 用冒号分隔组合用户名与密码 const credentials ${username}:${password}; // 使用 Base64 编码凭据 const encodedCredentials Buffer.from(credentials).toString(base64); export const config: WebdriverIO.Config { // ... headers: { Authorization: Basic ${encodedCredentials} } // ... }类型Object默认值{}transformRequest 与 transformResponsetransformRequest是发起 WebDriver 请求前拦截 HTTP 请求选项的函数transformResponse是响应返回后拦截响应对象的函数第一个参数是原始响应对象第二个是对应的RequestOptions。类型transformRequest: (RequestOptions) RequestOptionstransformResponse: (Response, RequestOptions) Response默认值均为none这两个回调非常适合做统一的请求/响应日志、加解密、代理改写等横切处理。strictSSL是否要求 SSL 证书有效。类型Boolean默认值true说明可通过环境变量STRICT_SSL或strict_ssl覆盖。当后端使用自签名证书时需设为false。enableDirectConnect是否启用 Appium 的 direct connection 特性。即便该开关开启若响应中没有相应的 key此选项也不会产生任何副作用。类型Boolean默认值truecacheDir缓存目录根路径用于存放启动会话时下载的所有驱动文件。类型String默认值process.env.WEBDRIVER_CACHE_DIR || os.tmpdir()即默认取环境变量WEBDRIVER_CACHE_DIR否则落到系统临时目录。maskingPatterns为了日志安全通过正则表达式在日志中打码obfuscate敏感信息。字符串格式为可带 flag 的正则如/.../i多个正则用逗号分隔。类型String默认值undefined示例{ maskingPatterns: /--key([^ ]*)/i,/RESULT (.*)/ }该配置在 packages/wdio-logger/src/utils.ts 的mask函数中真正生效模式中没有捕获组时整个匹配替换为掩码有捕获组时仅替换每个捕获组其余部分保留替换值统一为**MASKED**。同时它也支持WDIO_LOG_MASKING_PATTERNS环境变量并可针对单个 logger 单独设置见 packages/wdio-logger/src/index.ts。这非常适合隐藏云服务商凭据、令牌等敏感数据。WebdriverIO 选项standalone 可用以下选项含上文列出的全部 WebDriver 选项可在 standalone 模式下使用。automationProtocol定义用于浏览器自动化的协议。目前只支持webdriver它是 WebdriverIO 使用的核心自动化技术。若想接入其他自动化技术可将此属性设置为一个符合如下接口的模块路径import type { Capabilities } from wdio/types; import type { Client, AttachOptions } from webdriver; export default class YourAutomationLibrary { /** * 启动自动化会话返回一个带相应自动化命令的 * WebdriverIO monad。参考 webdriver 包作为参考实现。 */ static newSession( options: Capabilities.RemoteConfig, modifier?: (...args: any[]) any, userPrototype?: PropertyDescriptorMap, customCommandWrapper?: (...args: any[]) any ): PromiseClient; /** * 允许用户附加到已存在的会话 * optional */ static attachToSession( options?: AttachOptions, modifier?: (...args: any[]) any, userPrototype?: {}, commandWrapper?: (...args: any[]) any ): Client; /** * 将新会话的 session id 与浏览器 capabilities 直接写入传入的浏览器对象 * optional */ static reloadSession( instance: Client, newCapabilities?: WebdriverIO.Capabilitie ): Promisestring; }类型String默认值webdriverbaseUrl通过设置基准 URL 来缩短url命令调用如果url参数以/开头则前缀拼接baseUrlbaseUrl自身若带路径则除外如果url参数不以 scheme 或/开头如some/path则直接完整前置拼接baseUrl。类型String默认值nullwaitforTimeout 与 waitforIntervalwaitforTimeout是所有waitFor*命令的默认超时注意选项名中是小写f。该超时只影响以waitFor*开头的命令及其默认等待时间。要为某个测试单独加长超时请查阅对应测试框架的文档。类型Number默认值waitforTimeout: 5000、waitforInterval: 100waitforInterval是所有waitFor*命令检查期望状态如可见性是否变化的默认轮询间隔。两个默认值均可在 packages/wdio-config/src/constants.ts 中确认。maxSpyCollectedBodySize使用mock命令时可返回的响应体最大字节数。设为0可禁用对侦察负载的数据收集。类型Number默认值10485760即 10MBregion如果运行在 Sauce Labs 上可选择在不同的数据中心之间运行测试。可使用简短区域代号us默认映射到us-west-1或eu映射到eu-central-1也可以直接使用完整区域名。类型String默认值us可选值us|eu|us-west-1|eu-central-1|us-east-4|staging注意只有当你提供了与 Sauce Labs 账号关联的user与key选项时才生效。(仅对 VM 与模拟器/真机生效)Testrunner 选项以下选项含上文列出的全部选项仅在通过 WDIO testrunner 运行测试时生效。specs 与 excludespecs定义要执行的测试文件。可以指定一个 glob 模式一次匹配多个文件也可以把一个 glob 或一组路径放进数组使它们在同一 worker 进程中运行。所有路径均相对于配置文件所在路径解析。类型specs: (String | String[])[]默认[]exclude从测试执行中排除 spec同样相对于配置文件路径解析类型String[]默认[]示例配置可在 e2e/wdio/wdio.conf.ts 等实际运行配置中看到。suites一个描述各种测试套件的对象随后可在wdioCLI 上通过--suite选项指定要运行的套件。类型Object默认值{}capabilitiestestrunner 版与上文 WebDriver 的capabilities相同区别在于这里可以指定一个multiremote对象或一个 WebDriver 会话数组以并行执行。同样可以应用上文定义的厂商/浏览器专属 capabilities。类型Object|Object[]默认值[{ wdio:maxInstances: 5, browserName: firefox }]maxInstances 与 maxInstancesPerCapabilitymaxInstances是并行运行的 worker 总数上限。在 Sauce Labs 等外部云厂商的机器上运行时该值可以高达100——因为测试分布在多台 VM 上而非单机。若在本机运行请设置更合理的数值如3、4或5。本质上这就是同时启动并运行测试的浏览器数量因此它取决于本机 RAM 大小与同时运行的其他应用数量。也可以在 capability 对象内通过wdio:maxInstancescapability 应用maxInstances从而限制该特定 capability 的并行会话数。类型Number默认值100maxInstancesPerCapability同样默认100注意一个典型场景在 examples/wdio.conf.js 中maxInstances被设为10其注释解释了10 个 spec 文件 maxInstances 10 全部同时运行、每个 capability 分别派生进程的调度语义。injectGlobals将 WebdriverIO 的全局变量如browser、$、$$注入全局环境。如果设为false应从wdio/globals导入import { browser, $, $$, expect } from wdio/globals注意WebdriverIO 不负责注入测试框架专属的全局变量。类型Boolean默认值truebail希望在指定数量的测试失败后停止测试运行时可使用bail默认0即无论结果如何都运行所有测试。注意此处的一个测试在使用 Mocha/Jasmine 时指单个 spec 文件内的所有测试使用 Cucumber 时指 feature 文件内的所有步骤。要控制单个测试文件内的 bail 行为请查看对应的框架选项。类型Number默认值0specFileRetries 系列specFileRetries整个 spec 文件整体失败时重试的次数。类型Number默认0。specFileRetriesDelay两次 spec 文件重试之间的延迟秒。类型Number默认0。specFileRetriesDeferred重试的 spec 文件是立即重试还是推迟到队列末尾。类型Boolean默认true。groupLogsByTestSpec选择日志输出的视图方式。设为false不同测试文件的日志实时打印。注意并行运行时可能出现不同文件日志混排。设为true日志按 Test Spec 分组仅在对应 Test Spec 完成时打印。类型Boolean默认值false实时打印autoAssertOnTestEnd控制 WebdriverIO 是否在每次测试结束时自动断言所有软断言soft assertions。设为true时累积的软断言会被自动检查若有失败则导致测试失败设为false时你必须手动调用断言方法来检查软断言。类型Boolean默认值trueservices服务替你接管那些你不想亲力亲为的特定工作几乎零成本地增强测试环境如启动 Selenium、启动 Appium、上传结果到云等。类型String[] | Object[]默认值[]ServiceEntry支持多种形态字符串、Hook 对象、服务类、[名称, 选项]或[类, 选项]二元组详见 packages/wdio-types/src/Services.ts。framework 与 mochaOpts / jasmineOpts / cucumberOptsframework定义 WDIO testrunner 使用的测试框架。类型String默认值mocha可选值mocha|jasmine|cucumbermochaOpts、jasmineOpts、cucumberOpts是框架相关选项具体可选项请参见框架适配器文档与 Frameworks。其默认值为{ timeout: 10000 }在 packages/wdio-config/src/constants.ts 中对应为mochaOpts.timeout、jasmineOpts.defaultTimeoutInterval、cucumberOpts.timeout均为10000。cucumberFeaturesWithLineNumbers使用 Cucumber 框架时带行号的 Cucumber feature 列表用法见 Frameworks.md。类型String[]默认值[]对应地packages/wdio-config/src/utils.ts 的isCucumberFeatureWithLineNumber会识别形如/foo/bar:9的:行号后缀。reporters要使用的 reporter 列表。一个 reporter 可以是字符串也可以是一个[reporterName, { /* reporter options */}]数组——第一个元素是 reporter 名字符串第二个元素是 reporter 选项对象。类型String[] | Object[]默认值[]示例reporters: [ dot, spec [junit, { outputDir: ${__dirname}/reports, otherOption: foobar }] ]reporterSyncInterval 与 reporterSyncTimeoutreporterSyncInterval决定 reporter 在异步上报日志例如流式传给第三方厂商时检查其是否已同步的间隔。类型Number默认100毫秒。reporterSyncTimeout决定 reporter 完成日志上传的最大时间超过后 testrunner 会抛出错误。类型Number默认5000毫秒。execArgv启动子进程时指定的 Node 参数。类型String[]默认值nullfilesToWatch一组支持 glob 的字符串模式告诉 testrunner 在使用--watch标志运行时额外监视其他文件例如应用源码文件。默认情况下 testrunner 已经监视所有 spec 文件。类型String[]默认值[]updateSnapshots设为true时更新快照。最理想的用法是作为 CLI 参数传入例如wdio run wdio.conf.js --s。类型new | all | none默认值未提供且在 CI 中运行时为none未提供时默认new否则取显式提供的值resolveSnapshotPath覆盖默认的快照路径。例如将快照存储到测试文件旁边export const config: WebdriverIO.Config { resolveSnapshotPath: (testPath, snapExtension) testPath snapExtension, }类型(testPath: string, snapExtension: string) string默认值将快照文件存放在测试文件旁边的__snapshots__目录中tsConfigPathWDIO 使用tsx编译 TypeScript 文件。你的 TSConfig 会从当前工作目录自动检测但你可以在这里指定自定义路径或通过设置TSX_TSCONFIG_PATH环境变量指定。在 packages/wdio-cli/src/commands/run.ts 中可以看到CLI 会依次考虑命令行--tsConfigPath参数、TSX_TSCONFIG_PATH环境变量以及配置文件同目录下的tsconfig.json。类型String默认值nullHooks测试生命周期钩子WDIO testrunner 允许你在测试生命周期的特定时机注册 hooks从而执行自定义操作例如测试失败时截图。每个 hook 的参数都携带关于生命周期的具体信息如测试套件或测试的详细信息。完整的 hook 示例可参考 examples/wdio.conf.js 中的带注释配置。重要提示部分 hooksonPrepare、onWorkerStart、onWorkerEnd、onComplete在不同的进程中执行因此无法与位于 worker 进程中的其他 hooks 共享全局数据。所有支持 hook 的完整清单可见 packages/wdio-config/src/constants.ts 的SUPPORTED_HOOKS其类型签名定义在 packages/wdio-types/src/Services.ts。进程级 hookslauncher 进程执行Hook触发时机参数onPrepare所有 worker 启动前执行一次configWebdriverIO 配置对象、paramcapabilities 详情数组onWorkerStartworker 进程被创建前执行可用于为 worker 初始化特定服务、异步修改运行时环境cidcapability id如0-0、capsworker 会话 capabilities、specsworker 要运行的 specs、args与主配置合并的对象、execArgv传给 worker 的字符串参数数组onWorkerEndworker 进程退出后立即执行cid、exitCode0 成功1 失败、specs、retries按 spec 文件使用的重试次数见 Retry.mdonComplete所有 worker 关闭、进程即将退出时执行在此抛出错误会导致测试运行失败exitCode0 成功1 失败、config、caps、result包含测试结果的结果对象会话级 hooksworker 进程执行Hook触发时机参数beforeSession初始化 webdriver 会话与测试框架之前执行允许你根据 capability 或 spec 调整配置config、caps、specsafterSession终止 webdriver 会话之后立即执行config、caps、specsbefore测试执行开始前执行此时可访问所有全局变量如browser是定义自定义命令的理想位置caps、specs、browser创建的浏览器/设备会话实例after所有测试结束后执行仍可访问测试中的全部全局变量result0 通过1 失败、caps、specs套件/测试级 hooksHook触发时机参数beforeSuite套件开始前仅 Mocha/Jasminesuite套件详情afterSuite套件结束后仅 Mocha/JasminesuitebeforeHook套件内的 hook如 Mocha 的beforeEach执行之前test测试详情、context测试上下文Cucumber 中代表 World 对象afterHook套件内的 hook如 Mocha 的afterEach执行之后test、context、result含error、result、duration、passed、retries属性beforeTest测试执行前仅 Mocha/Jasminetest、context测试执行的作用域对象afterTest测试结束后仅 Mocha/Jasminetest、context、result其中result.error失败时的错误对象否则undefined、result.result测试函数返回对象、result.duration测试时长、result.passed是否通过、result.retries单测重试信息如{ attempts: 0, limit: 0 }相关规则见 Retry.md 与 Cucumber 重试afterTest的实际用法可见 examples/wdio.conf.js 中的afterTest: function (test, context, { error, result, duration, passed, retries })签名。命令级 hooksHook触发时机参数beforeCommandWebdriverIO 命令执行前运行commandName命令名、args命令将收到的参数afterCommandWebdriverIO 命令执行后运行commandName、args、result命令结果、error若有错误则为 Error 对象断言级 hooksHook触发时机参数beforeAssertionWebdriverIO 断言发生前执行params含params.matcherName匹配器名如toHaveTitle、params.expectedValue传入匹配器的值、params.options断言选项afterAssertionWebdriverIO 断言发生后执行同beforeAssertion的参数外加params.result断言结果Cucumber 专属 hooksHook触发时机参数beforeFeatureCucumber Feature 运行前urifeature 文件路径、featureCucumber feature 对象afterFeatureCucumber Feature 运行后uri、featurebeforeScenarioCucumber Scenario 运行前world包含 pickle 与测试步骤信息的 world 对象、contextCucumber World 对象afterScenarioCucumber Scenario 运行后world、resultresult.passed是否通过、result.error失败时的错误栈、result.duration场景耗时毫秒数、contextbeforeStepCucumber Step 运行前step、scenario、contextafterStepCucumber Step 运行后step、scenario、resultresult.passed、result.error、result.duration、context会话刷新 hookHook触发时机参数onReload刷新refresh发生时执行oldSessionId旧会话 ID、newSessionId新会话 ID配置的合并与校验机制了解配置如何被处理有助于排查为什么我的选项没生效类问题。核心流程如下默认配置DEFAULT_CONFIGS()packages/wdio-config/src/constants.ts产出一份包含全部默认值的配置对象其中specs: []、framework: mocha、waitforTimeout: 5000、connectionRetryTimeout: 120000、maxInstances: 100、injectGlobals: true、全部 hooks 初始化为空数组等。合并与校验validateConfigpackages/wdio-config/src/utils.ts按Options.Definition的描述逐项校验缺必填项抛错、类型不匹配抛错、match正则不匹配抛错最终返回补全默认值后的配置。webdriver包的DEFAULTSpackages/webdriver/src/constants.ts就是这样一个Definition其中protocol用/(http|https)/校验hostname默认localhost。CLI 覆盖wdio run命令会解析--headless、--mochaOpts.timeout、--tsConfigPath等参数并在启动时合入配置见 packages/wdio-cli/src/commands/run.ts。因此当你修改配置时应优先确认选项是否属于对应层级WebDriver / WebdriverIO / Testrunner、拼写是否与Options.ts中的定义一致再检查 CLI 参数与环境变量如STRICT_SSL、WEBDRIVER_CACHE_DIR、TSX_TSCONFIG_PATH、WDIO_LOG_MASKING_PATTERNS是否发生了覆盖。结语WebdriverIO 的配置体系按协议连接 → 运行语义 → 测试调度 → 生命周期钩子四层展开WebDriver 选项负责连接与协议细节WebdriverIO 选项定义 standalone 场景下的运行行为Testrunner 选项控制 worker、spec、reporter 的调度而 hooks 则让测试工程师在任意时机介入流程。结合本仓库中 packages/wdio-types/src/Options.ts 的类型定义、packages/wdio-config/src/constants.ts 的默认值、examples/wdio.conf.js 的完整示例你可以在类型安全的前提下完成从单浏览器冒烟到多 capability 并行的复杂配置并利用 maskingPatterns、hooks 等能力构建安全、可控、可观测的测试工程。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考