WebdriverIO DevTools 的 Nightwatch 适配器零测试代码改动为 Nightwatch 套件接入可视化调试与 Trace 模式【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio导读WebdriverIO DevTools 生态为浏览器自动化测试提供了一套开发者工具 UI而 Nightwatch 适配器wdio/nightwatch-devtools将同一套可视化调试体验带到 Nightwatch 测试套件中——无需改动任何测试代码只需在nightwatch.conf.cjs中做少量接线。阅读完本文你将掌握如何安装与配置该适配器、如何运行实时 DashboardLive 模式与无头 Trace 模式、如何开启 BiDi 捕获与会话录屏以及 Nightwatch 在框架钩子深度上的已知局限。它是什么一套三框架共享的 DevTools 前端wdio/nightwatch-devtools是 WebdriverIO DevTools 的 Nightwatch 适配器与 WebdriverIO 服务、Selenium 适配器共享同一个可视化的调试 UI。它由适配器负责从测试框架侧捕获命令、DOM、控制台、网络与断言数据底层变换逻辑位于共享的 trace 管线文档中描述为wdio/devtools-core与wdio/devtools-trace层因此无论由哪个适配器产出Trace 产物格式与show-trace播放器完全一致可对照 Cross-Framework Support 中的能力矩阵。Live 模式默认测试执行时自动在浏览器新窗口打开交互式 Dashboard可实时观看、调试并一键重跑测试。Trace 模式跳过 UI在会话结束时写出可移植的trace.zip离线产物适合 CI、Agent 对比与后续回放。安装npm install wdio/nightwatch-devtools该包同时随附show-trace可执行文件用于回放 Trace 产物无需额外安装依赖见后文 Trace 模式。Setup两种接入方式标准 Nightwatchmocha 风格在nightwatch.conf.cjs中引入适配器的default导出并通过test_settings.target.globals注入nightwatchDevtools(...)。globals是 Nightwatch 对外暴露钩子的入口适配器借此在会话生命周期内接管捕获// nightwatch.conf.cjs const nightwatchDevtools require(wdio/nightwatch-devtools).default module.exports { src_folders: [tests], test_settings: { default: { desiredCapabilities: { browserName: chrome, // Required for network request capture goog:loggingPrefs: { performance: ALL } }, globals: nightwatchDevtools({ port: 3000 }) } } }关键点goog:loggingPrefs: { performance: ALL }是网络请求捕获Network Logs的前置条件缺失时网络面板无法工作但其余功能不受影响。随后照常运行测试DevTools UI 会在新浏览器窗口中自动打开nightwatch你的测试文件一行都不用改。适配器通过浏览器代理包装来拦截命令见 Limitations 中“无原生命令钩子”的说明因此测试代码可以保持原样。Cucumber / BDD对于 Cucumber 场景除了主导出之外还需要导入cucumberHooksPath并传给 Cucumber 的require选项。这会注册Before/After场景钩子镜像 WebdriverIO 服务中beforeScenario/afterScenario的行为// nightwatch.conf.cjs const nightwatchDevtools require(wdio/nightwatch-devtools).default const { cucumberHooksPath } require(wdio/nightwatch-devtools) module.exports { src_folders: [features/step_definitions], test_runner: { type: cucumber, options: { feature_path: features, require: [cucumberHooksPath] // -- register DevTools Cucumber hooks } }, test_settings: { default: { desiredCapabilities: { browserName: chrome, goog:loggingPrefs: { performance: ALL } }, globals: nightwatchDevtools({ port: 3000 }) } } }对比WebdriverIO 的接线方式是services: [[devtools, { … }]]Selenium 是DevTools.configure({ … })而 Nightwatch 统一通过globals: nightwatchDevtools({ … })传入配置见 Reference。三种适配器的选项名称、类型与默认值完全一致。配置选项全览选项类型默认值说明portnumber3000DevTools 后端服务端口若被占用会自动递增。hostnamestringlocalhost后端服务绑定的主机名。screencastScreencastOptions{ enabled: false }按会话录制.webm视频详见 Screencast。bidibooleanfalse选择接入 WebDriver BiDi 捕获浏览器控制台 JS 异常 网络。需要在 capabilities 中设置webSocketUrl: true且 chromedriver 支持 BiDi。接入后逐命令的 Chrome performance-log 网络路径会被关闭避免请求重复出现。modelive \| tracelivelive打开 DevTools UItrace跳过 UI 并写出可移植产物详见 Trace 模式。两种模式互斥每次会话只能选其一。traceFormatzip \| ndjson-directoryzipTrace 产物的布局。仅mode: trace时生效。traceGranularitysession \| spec \| testsession每个 session / spec 文件 / 测试各产出一个 Trace。test会写入test-results/spec-title-browser[-retryN]/trace.zip。仅mode: trace时生效详见 Trace 模式粒度。注意BDDdescribe/it接口会退化为单个会话级切片详见 Per-test slicing。tracePolicyon \| retain-on-failure \| retain-on-first-failure \| on-first-retry \| on-all-retries \| retain-on-failure-and-retrieson保留哪些 Trace。需配合traceGranularity: test。仅mode: trace时生效。filmstripbooleantrue在 Trace 中录制密集、连续的截屏条供播放器平滑拖拽回放而非每个动作只一帧。会对会话运行截屏录制器Nightwatch 下为轮询模式。仅mode: trace时生效。screenshotoff \| on \| only-on-failureoff按测试截图。仅 Trace 模式 traceGranularity: test时生效。仅产出——PNG 写入 Trace 输出目录当emitArtifactsManifest: true时同时写入清单不会内联附加到 Allure见下方说明。videooff \| TraceRetentionPolicyoff按测试的视频切片按给定保留策略如retain-on-failure保留。仅 Trace 模式 traceGranularity: test时生效。非off值会自行启动截屏录制器——你不需要再同时设置filmstrip或screencast.enabled。仅产出——.webm写入 Trace 输出目录当emitArtifactsManifest: true时同时写入清单不会内联附加到 Allure。emitArtifactsManifestbooleanfalse在 Trace 旁写出devtools-artifacts-sessionId.json清单供报告器/CI 发现产物的通用索引。Nightwatch 必须显式开启——它没有实时 Allure 信号可供自动检测因此不像 WDIO/Selenium 那样自动启用。仅mode: trace时生效。captureAssertionsbooleantrue将断言捕获为 Trace 动作行——node:assert以及原生的browser.assert/browser.verify包括取反的.not.*匹配器。设为false可退出。Nightwatch 不支持内联 Allure 附加。其官方nightwatch-allure报告器是事后post-hoc处理没有实时附加 API而allure-js-commons的attachment()在 Nightwatch 运行中为空操作。因此screenshot/video产物是仅产出的文件加上emitArtifactsManifest: true时的清单写入 Trace 输出目录但不附加到 Allure 测试。按测试切片以及这些产物对 Cucumber 与 exports-object 接口是有意义的BDDdescribe/it接口会退化到会话粒度那里的按测试门控不生效。组合示例globals: nightwatchDevtools({ port: 3000, hostname: localhost, screencast: { enabled: true }, bidi: true })Screencast会话录屏wdio/nightwatch-devtools可以录制浏览器会话的连续.webm视频。录制在插件见到的第一个会话上开始并在 Nightwatch 的after()钩子中定稿。仅轮询模式。Nightwatch 不像 WebdriverIObrowser.getPuppeteer()和 Seleniumdriver.createCDPConnection那样暴露稳定的 CDP 逃生通道因此截屏录制器通过按固定间隔调用browser.takeScreenshot()来捕获帧。它适用于 Nightwatch 支持的每一种浏览器。globals: nightwatchDevtools({ port: 3000, screencast: { enabled: true, pollIntervalMs: 200 } })选项类型默认值说明enabledbooleanfalse总开关。pollIntervalMsnumber200截屏间隔毫秒。越小视频越流畅但 WebDriver 往返次数越多。200 ms ≈ 5 fps。captureFormatjpeg \| pngjpeg交给 ffmpeg 编码器、最终混流进.webm前的每帧像素格式。轮询模式下源截屏始终是 PNG因此它不改变采集方式——只改变编码器每帧收到的格式。maxWidth/maxHeight/quality--CDP 专属选项轮询模式下被忽略。仅为与 WDIO/Selenium 适配器保持形状兼容而列出。前置条件fluent-ffmpeg已是本包的运行时依赖加上 PATH 上的ffmpeg二进制。macOSbrew install ffmpegLinuxapt install ffmpeg。缺少 ffmpeg 时录制器仍会运行但编码步骤会打印一条警告并跳过写文件。输出视频文件写在刚运行过的测试文件旁边回退到nightwatch.conf.*所在目录最后回退到process.cwd()。完整路径会出现在 Nightwatch 日志行 Screencast video: path中视频也会被推流到 Dashboard 的 Screencast 标签页。更完整的录屏功能参考浏览器支持、三个适配器下的输出路径见 Screencast。BiDi 捕获可选开启启用 WebDriver BiDi 捕获浏览器控制台消息、JS 异常与网络请求。这与 selenium-devtools 使用的路径等价——两个适配器在wdio/devtools-core中共享相同的附加逻辑。globals: nightwatchDevtools({ port: 3000, bidi: true })同时需要在 capabilities 中设置webSocketUrl: truechromedriver 才会真正暴露 BiDi 通道desiredCapabilities: { browserName: chrome, webSocketUrl: true, // ← enables BiDi goog:chromeOptions: { /* ... */ } }当 BiDi 接入后逐命令的 Chrome performance-log 网络捕获路径会被关闭避免 Dashboard 中请求出现两次。如果webSocketUrl缺失或 chromedriver 版本不暴露 BiDi附加会静默失败performance-log 回退路径继续工作。与 WDIO/Selenium 的差异这两者的 BiDi 是自动接入的Nightwatch 必须显式开启bidi: truewebSocketUrl这也是 Cross-Framework Support 能力矩阵中的已知差距之一。Trace 模式无头捕获路径无头捕获路径——不会打开 DevTools UI 窗口。会话结束时适配器在test-results/文件夹解析出的测试/配置目录旁写入一个可移植的trace-sessionId.zip或目录其结构与 WebdriverIO 的 Trace 产物一致。globals: nightwatchDevtools({ mode: trace, traceFormat: ndjson-directory // optional; default zip })粒度与 CucumbertraceGranularity决定一个产物覆盖什么范围——session默认、spec或test。Nightwatch 在每个 Cucumber 场景后都会退出浏览器。一个session级 Trace 会跨越这种情况整个运行一个 zip每个场景嵌套在其 feature 之下。test则为每个场景写入自己的 zip 到自己独立的文件夹中——这是 Cucumber 的推荐做法产物更小并且这正是tracePolicy保留策略所基于的粒度。globals: nightwatchDevtools({ mode: trace, traceGranularity: test // one trace per Cucumber scenario })在 BDDdescribe/it接口上test会退化为单个会话级切片Nightwatch 内部运行每个it()并且每个模块只触发一次插件的按测试钩子。动作树中仍会把每个it显示为独立分组。Trace 模式下会跳过后端端口绑定、UI 窗口和screencast选项。完整的 Trace 功能参考产物内容、查看器、移动端测试、何时选zip还是ndjson-directory见 Trace Mode。Trace 产物里有什么Nightwatch 与 WebdriverIO、Selenium 适配器共享同一条 Trace 管线因此无论哪个适配器产出产物结构完全一致。一个 Nightwatch Trace 携带完整的逐动作捕获——每个用户可见动作的截图、深度缩进的 accessibility-tree 快照、可交互元素列表以及 Markdown 转录文本——因此它可以在show-trace播放器中打开支持 DOM/快照时间旅行、A11y与Transcript标签页、pick-locator 元素覆盖层以及Cucumber 下Feature → Scenario → Step嵌套。一个 zip 内典型包含trace.traceNDJSON 动作事件、trace.networkHAR 风格网络条目、transcript.md面向人/LLM 的摘要、resources/pageid-ts.jpeg每动作截图、resources/pageid-ts-elements.json可交互元素列表与resources/pageid-ts-snapshot.txtAI 友好的可访问性树快照。用随wdio/nightwatch-devtools附带的show-trace命令打开 Trace无需额外依赖npx show-trace test-results/trace-sessionId.zip # in a project that installs the adapter pnpm show-trace test-results/trace-sessionId.zip # from the devtools monorepo播放器支持 DOM 时间旅行、A11y 标签页与 pick-locator 覆盖层、Transcript 标签页与 Copy-for-LLM、可拖拽时间轴与密集胶片条平滑回放以及Space播放/暂停、←/→逐步、Home/End首末、,/.速度、/过滤、?快捷键帮助等键盘快捷键。完整演练见 Trace Player。Per-test slicing 与 BDDdescribe/it注意点按测试的选项——traceGranularity: test以及与之配对的tracePolicy、screenshot、video——需要一个按测试钩子来切割每个测试的切片。exports-objectmocha 风格接口和 Cucumber按场景钩子暴露了这一钩子因此能获得真正的按测试切片。BDDdescribe/it接口是例外Nightwatch 内部运行每个it()并且每个模块只触发一次插件的按测试钩子因此traceGranularity: test会退化为单个会话级切片键到第一个测试。产物清单仍然列出每个测试用例及其正确状态只有按测试的切片/产物键控会退化。会话级与 spec 级 Trace 不受影响。关于保留策略的另一处 Nightwatch 限制Nightwatch 的--retries会在内部重跑测试而不重新触发插件的按测试钩子因此除retain-on-failure外的 retry-aware 策略on-first-retry、retain-on-first-failure等都会退化为retain-on-failure。这一差距在 Trace Mode 与 Cross-Framework Support 中均有记录。特性总览Nightwatch 适配器提供与 WebdriverIO 相同的 DevTools UI 体验。以下每个特性都由基础的globals: nightwatchDevtools({ port: 3000 })配置自动捕获——无需按特性配置网络日志额外需要goog:loggingPrefs: { performance: ALL }见 SetupInteractive Test Rerunning Visualization— 实时浏览器预览、逐命令截图、一键重跑测试/套件Preserve Rerun (Compare)— 快照失败的测试、重跑并排对比两次运行的差异Multi-Framework Support— 标准mocha 风格与 Cucumber/BDD 运行器Console Logs— 捕获并检查浏览器控制台输出bidi: true下实时Network Logs— 监控 API 调用与网络活动Metadata— 每个浏览器会话的能力、环境与计时TestLens— 从任意命令跳到触发它的源码行Session Screencast— 浏览器会话的连续.webm录制Trace Mode— 无头捕获产出可移植的trace.zip不开 UI 窗口Screencast 是唯一拥有自己选项的特性完整列表见 Screencastglobals: nightwatchDevtools({ port: 3000, screencast: { enabled: true, pollIntervalMs: 200 } })Limitations 与 Feature ParityNightwatch 没有提供 WebdriverIO 那样深度的框架钩子因此与 WDIO DevTools 服务相比存在一些差异局限详情无原生命令钩子Nightwatch 没有beforeCommand/afterCommand钩子。命令改由浏览器代理包装来拦截。有限的测试上下文browser.currentTest提供的元数据少于 WDIO runner 上下文测试名与文件路径需要额外的启发式推断。扁平套件嵌套Nightwatch 不原生支持多层嵌套的describe块插件最多报告两层。延迟的结果可用性测试结果只在afterEach中定稿测试中途不可用。Screencast 仅轮询模式不同于 WDIO通过browser.getPuppeteer()做 CDP push和 Selenium通过driver.createCDPConnection做 CDP pushNightwatch 缺少稳定的 CDP 逃生通道因此帧通过轮询browser.takeScreenshot()捕获。适用于 Nightwatch 支持的每种浏览器每帧成本与轮询间隔成正比。按测试 Trace 切片BDDdescribe/itBDD 接口每个模块只触发一次插件的按测试钩子因此traceGranularity: test退化为一个会话级切片。exports-objectmocha 风格与 Cucumber 接口能获得真正的按测试切片。仅产出的 Trace 产物按测试的screenshot/video文件写入 Trace 输出目录emitArtifactsManifest: true时写入清单但不内联附加到 Allure——Nightwatch 没有实时 Allure 附加 API。结论整体而言Nightwatch 适配器与 WebdriverIO DevTools 服务的功能对等度约为80–90%。对于已经使用 Nightwatch、希望在不重写测试的前提下获得现代可视化调试与可移植离线 Trace 的团队这是一个低摩擦的接入方案一次安装、一个globals调用、零测试代码改动。在决定采用前请重点评估两处差距录屏仅轮询模式性能开销与pollIntervalMs成正比以及 BDDdescribe/it下按测试切片退化为会话级。【免费下载链接】webdriverioNext-gen browser and mobile automation test framework for Node.js项目地址: https://gitcode.com/GitHub_Trending/we/webdriverio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考