1. 项目概述当 WebdriverIO 遇上 Electron如果你正在用 WebdriverIO 8 给 Electron 应用写自动化测试并且卡在了那个该死的 WebSocket 连接错误上那么你来对地方了。我最近刚用 WebdriverIO 8 完整地跑通了一个大型 Electron 项目的端到端测试流水线期间踩遍了所有关于 WebSocket 连接的坑。从ECONNREFUSED到ERR_CONNECTION_TIMEOUT再到 Electron 主进程默默崩溃却不报错这些坑每一个都足以让你怀疑人生。这篇文章不是官方文档的复读机而是我花了近两周时间通过反复试错、阅读源码、分析网络包才总结出的实战经验。我会带你从零开始不仅告诉你配置怎么写更会深入解释 WebdriverIO 8 与 Electron 之间 WebSocket 通信的底层机制以及当连接失败时每一步你应该去哪里找线索、怎么分析。我们的目标很简单让你能稳定、可靠地建立起那条连接测试脚本和 Electron 应用的生命线。2. 核心难题拆解为什么 WebSocket 连接如此脆弱在开始动手之前我们必须先理解问题的根源。WebdriverIO 与 Electron 的通信本质上是一个客户端-服务器模型。WebdriverIO 测试运行器是客户端而被测的 Electron 应用需要启动一个 WebSocket 服务器。这个服务器通常由wdio-electron-service这个包来帮助我们在 Electron 的主进程中启动。2.1 通信架构与失败点想象一下这个场景你运行npm run wdio期待测试开始。背后发生了以下一连串事件服务启动wdio-electron-service根据你的配置尝试在指定的端口默认是9515启动一个 WebSocket 服务器。应用启动服务会尝试启动你指定的 Electron 应用可执行文件或通过appEntryPoint启动开发态应用。注入与连接在 Electron 应用启动后服务会向其中注入客户端脚本并尝试让 WebdriverIO 的测试运行器作为客户端去连接第 1 步启动的 WebSocket 服务器。会话建立连接成功后双方开始基于 WebDriver 协议通信。这个链条上的任何一个环节断裂都会导致你看到令人困惑的错误。最常见的几个断裂点包括端口冲突9515端口被其他进程可能是上次未退出的测试、ChromeDriver、或其他软件占用。应用启动失败appEntryPoint路径错误或者 Electron 应用本身在启动时就因代码错误而崩溃。WebSocket 服务器未就绪Electron 的主进程代码中可能因为异步操作导致 WebSocket 服务器在 WebdriverIO 尝试连接时还未启动完成。路径与参数不符开发环境下的应用路径与生产构建后的路径不同配置未做区分。版本地狱webdriverio、wdio-electron-service、electron三者版本不兼容。2.2 从错误信息定位问题环节面对一长串错误栈快速定位到上述哪个环节出问题是关键。这里有个简单的判断流程错误信息包含ECONNREFUSED这通常指向环节1或3。意味着 WebdriverIO 客户端无法连接到目标地址和端口。要么是服务器根本没启动端口被占、服务启动失败要么是地址/端口配错了。错误信息包含timeout这更棘手可能指向环节2或4。服务器可能启动了但 Electron 应用启动太慢或者启动后内部逻辑卡死导致 WebSocket 服务器无法正常响应连接请求。Electron 窗口一闪而过或根本看不到这明确指向环节2。你的 Electron 应用本身在启动阶段就崩溃了。需要独立于 WebdriverIO 先运行你的 Electron 应用确保它是正常的。连接成功但立刻断开或无法执行任何命令这可能指向环节4即协议通信层面不匹配通常与版本兼容性有关。理解了这个流程我们就不再是盲目地修改配置而是有了清晰的排查方向。3. 环境准备与基础配置工欲善其事必先利其器。一套清晰、可复现的初始环境是成功的基石。3.1 依赖安装与版本锁定版本兼容性是第一个拦路虎。我强烈建议使用固定的版本组合而不是始终安装latest。首先初始化你的测试项目如果还没有的话mkdir my-electron-e2e cd my-electron-e2e npm init -y然后安装核心依赖。以下是我在多个项目中验证过的一个稳定组合以 2024 年初为时间点npm install --save-dev webdriverio8.16.13 npm install --save-dev wdio-electron-service3.2.1 npm install --save-dev electron25.9.0 # 请确保与你项目中 Electron 版本一致 npm install --save-dev wdio/cli注意这里最关键的是wdio-electron-service与electron的版本匹配。务必去wdio-electron-service的 npm 页面 或 GitHub 仓库查看其peerDependencies确认其支持的 Electron 版本范围。例如wdio-electron-service3.x通常支持 Electron25-28。3.2 初始化 WebdriverIO 配置接下来使用 CLI 工具生成基础配置文件。这比手动创建更可靠。npx wdio init在初始化向导中你会被问到一系列问题。以下是我的选择建议测试框架选择Mocha或Jasmine看个人喜好。我选Mocha。测试运行器选择wdio/local-runner本地运行。测试位置选择specs按测试文件组织。是否添加 Page Objects可以先选No后期再引入。测试报告器spec报告器是必须的它会在控制台输出直观的结果。可以额外选allure用于生成精美报告。插件/服务这里至关重要一定要用空格键选中electron服务。如果列表里没有说明wdio-electron-service安装可能有问题。基础 URL对于 Electron 测试这个可以留空或填http://localhost因为 Electron 不是 Web 服务器。初始化完成后你会得到一个wdio.conf.js或.ts文件。这是我们的主战场。3.3 核心配置文件详解生成的配置文件是通用的我们需要为 Electron 测试进行针对性改造。以下是一个功能完整的wdio.conf.js示例我逐段加上注释const { join } require(path); exports.config { // 1. 运行器与测试文件配置 runner: local, specs: [ ./test/specs/**/*.js // 你的测试用例文件路径 ], exclude: [], // 2. 核心能力配置 - 这里告诉 WebdriverIO 我们测的是 Electron capabilities: [{ maxInstances: 1, // Electron 测试通常单实例运行 browserName: electron, // 必须是 electron wdio:electronServiceOptions: { // 这是给 electron-service 的配置 // 应用入口这是最关键的一项 // 场景A测试已打包的应用程序 // appBinaryPath: join(__dirname, path/to/your/packed/app.exe) // Windows // appBinaryPath: join(__dirname, path/to/your/packed/app.app/Contents/MacOS/app) // macOS // appBinaryPath: join(__dirname, path/to/your/packed/app) // Linux // 场景B测试开发中的应用程序更常用 appEntryPoint: join(__dirname, path/to/your/electron/main.js), // 指向你的 Electron 主进程文件 // 可选传递给 Electron 应用的参数 appArgs: [], // 可选自定义 WebSocket 端口避免冲突 port: 9515, } }], // 3. 日志级别调试时设为 debug 或 trace能看到大量底层通信信息 logLevel: info, // 4. 服务配置必须包含 electron services: [electron], // 5. 框架配置以 Mocha 为例 framework: mocha, mochaOpts: { ui: bdd, timeout: 60000 // Electron 启动可能较慢超时时间设长一点 }, // 6. 测试前/后的钩子函数 before: async function (capabilities, specs) { // 这里可以放一些全局的准备工作 // 例如设置全局变量、清理临时文件等 }, afterTest: async function(test, context, { error, result, duration, passed, retries }) { // 每个测试用例执行后运行 if (error) { // 测试失败时可以截图需要额外配置 // await browser.saveScreenshot(./errorShots/${test.title}.png); } } };第一个关键决策点appBinaryPath还是appEntryPointappBinaryPath指向已经通过electron-builder或类似工具打包好的可执行文件如.exe,.app,.deb。用于测试最终分发给用户的产物。appEntryPoint指向你的 Electron 主进程源代码文件如src/main/index.js。用于在开发过程中进行快速迭代测试。wdio-electron-service会帮你动态启动一个 Electron 实例来运行这个文件。对于日常开发我强烈推荐使用appEntryPoint。它启动更快无需每次修改代码都重新打包并且源码映射source map能让你在测试失败时直接定位到源代码行。4. 深入实战配置 WebSocket 连接与排错基础配置只是开始真正的挑战在于处理各种边界情况和连接故障。下面我们进入深水区。4.1 手动指定 WebSocket 端口与主机默认的9515端口可能被占用。你可以通过配置修改它。修改wdio:electronServiceOptionscapabilities: [{ browserName: electron, wdio:electronServiceOptions: { appEntryPoint: join(__dirname, src/main/index.js), port: 29515, // 换一个不常用的端口 hostname: 127.0.0.1, // 明确指定主机避免 localhost 解析问题 } }]同时你需要确保你的测试代码如果有或任何其他配置没有硬编码9515端口。wdio-electron-service会自动使用这里配置的端口。如何检查端口占用在启动测试前手动检查一下你想用的端口是否空闲。Linux/macOS:lsof -i :29515Windows:netstat -ano | findstr :29515如果端口被占命令会返回进程信息。你可以选择终止该进程kill -9 PID或任务管理器结束任务或者直接换一个端口。4.2 处理 Electron 应用启动参数与环境变量有时你的 Electron 应用需要特定的启动参数或环境变量才能正常运行例如指定用户数据目录、启用开发者工具、传递配置等。这些都需要通过wdio-electron-service传递进去。wdio:electronServiceOptions: { appEntryPoint: join(__dirname, src/main/index.js), appArgs: [ --disable-gpu, // 禁用GPU加速在一些CI环境如Docker中可能更稳定 --no-sandbox, // 禁用沙盒同样是CI环境常见选项 --my-custom-flagvalue // 你的自定义参数 ], env: { NODE_ENV: test, MY_CUSTOM_ENV: e2e_testing, ELECTRON_DISABLE_SECURITY_WARNINGS: true // 禁用安全警告让日志更干净 } }重要心得如果你的应用在独立运行时需要某些参数那么在 WebdriverIO 测试中也必须通过appArgs或env提供。一个常见的坑是应用读取process.argv或process.env来初始化但在测试环境中这些值缺失导致应用行为异常甚至启动失败。4.3 启用详细日志进行诊断当连接失败时最有力的武器就是日志。将 WebdriverIO 的日志级别调到最高。// 在 wdio.conf.js 中 exports.config { logLevel: trace, // 从 info 改为 trace将输出所有级别的日志包括最底层的 WebSocket 帧 outputDir: ./wdio-logs, // 将日志输出到文件避免控制台刷屏 // ... 其他配置 };运行测试后仔细查看日志文件。搜索关键词如WebSocket,connection,ERR,ECONNREFUSED,socket hang up。trace级别的日志会清晰显示连接尝试的 IP 和端口、握手过程、以及失败的具体原因。此外别忘了 Electron 应用自身的日志。wdio-electron-service会捕获 Electron 主进程的stdout和stderr并将其重定向到 WebdriverIO 的日志中。所以确保在你的 Electron 主进程代码里在关键节点尤其是启动 WebSocket 服务器的地方添加console.log语句。// 在你的 Electron 主进程文件 (main.js) 中 const { app, BrowserWindow } require(electron); console.log([Electron Main] App starting...); // ... 你的其他代码 // 假设这是 wdio-electron-service 启动 WebSocket 服务器的地方通常由服务内部处理 // 但你可以在应用启动后打印状态 app.whenReady().then(() { console.log([Electron Main] App is ready.); createWindow(); });这些日志会出现在 WebdriverIO 的输出中帮助你判断 Electron 应用是否成功启动、以及启动到了哪一步。4.4 编写一个最简单的连通性测试在搭建复杂测试套件之前先写一个最简单的测试来验证基础连接是否成功。在./test/specs/下创建connection.spec.jsdescribe(Electron 应用基础连接测试, () { it(应该成功启动应用并获取标题, async () { // 获取当前窗口句柄这可以验证 WebDriver 会话是否建立 const windowHandles await browser.getWindowHandles(); expect(windowHandles).toHaveLength(1); // 获取应用标题你的 Electron 窗口标题 const title await browser.getTitle(); console.log(应用标题: ${title}); // 这里不一定要有具体的断言只要上面两行不报错就说明连接和基本通信是正常的 expect(title).toBeDefined(); }); it(应该能在渲染进程执行脚本, async () { // 在渲染进程上下文中执行一段 JavaScript const result await browser.execute(() { // 这个函数在渲染进程的上下文中执行 return process.versions.electron; // 返回 Electron 版本 }); console.log(渲染进程中 Electron 版本: ${result}); expect(result).toMatch(/\d\.\d\.\d/); // 断言它是一个版本号格式 }); });运行这个测试npx wdio run wdio.conf.js。如果它能通过恭喜你最难的 WebSocket 连接关已经过了如果失败结合前面的日志你就能获得非常具体的错误信息用于排查。5. 高级场景与疑难杂症解决通过了基础测试我们可能会遇到一些更复杂的情况。5.1 处理多窗口或 BrowserView复杂的 Electron 应用可能有多个窗口或 BrowserView。WebdriverIO 需要知道操作哪个。你需要使用switchWindow或通过getWindowHandles来管理。it(应该能操作第二个窗口, async () { // 假设你的应用会打开第二个窗口 await browser.waitUntil( async () (await browser.getWindowHandles()).length 2, { timeout: 10000, timeoutMsg: 第二个窗口未在10秒内打开 } ); const handles await browser.getWindowHandles(); await browser.switchToWindow(handles[1]); // 切换到第二个窗口 // 现在你的所有命令都会在第二个窗口的上下文中执行 const secondWindowTitle await browser.getTitle(); console.log(第二个窗口标题: ${secondWindowTitle}); // 操作完成后如果需要切换回主窗口 await browser.switchToWindow(handles[0]); });5.2 模拟主进程与渲染进程的 IPC 通信自动化测试经常需要验证进程间通信IPC。你可以通过execute方法在渲染进程触发 IPC 事件但断言需要在主进程侧进行这通常比较困难。一个实用的模式是在测试模式下让主进程通过一个全局变量或将状态写入一个临时文件来暴露 IPC 结果然后测试脚本去读取这个状态。// 在你的 Electron 主进程代码中测试环境专用 if (process.env.NODE_ENV test) { global.__testIPCState {}; ipcMain.on(test-action, (event, args) { // ... 处理逻辑 global.__testIPCState.lastAction { success: true, args }; }); } // 在你的 WebdriverIO 测试中 it(应该能触发 IPC 并得到响应, async () { // 1. 在渲染进程触发 IPC await browser.execute(() { window.electron.ipcRenderer.send(test-action, { data: test }); }); // 2. 通过 execute 在主进程上下文中读取状态需要 wdio-electron-service 支持 // 注意这需要 service 提供特殊能力或者通过 preload 脚本桥接。 // 更常见的做法是让 IPC 操作触发一个渲染进程的 UI 变化然后去断言 UI。 // 例如等待某个元素出现 await $(#some-element).waitForExist({ timeout: 5000 }); });5.3 CI/CD 环境中的特殊配置在 GitHub Actions、GitLab CI、Jenkins 等无头环境中运行 Electron 测试需要额外注意虚拟显示服务器Electron 需要图形环境。使用xvfb(X Virtual Framebuffer)。# GitHub Actions 示例 jobs: test: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - uses: actions/setup-nodev3 - name: Install dependencies run: npm ci - name: Start xvfb run: | sudo apt-get install -y xvfb Xvfb :99 -screen 0 1024x768x24 /dev/null 21 echo DISPLAY:99 $GITHUB_ENV - name: Run E2E Tests run: npx wdio run wdio.conf.js更长的超时时间CI 环境可能比本地慢。增加mochaOpts.timeout、waitForTimeout全局等待命令超时和connectionRetryTimeoutWebDriver 连接重试超时。exports.config { // ... mochaOpts: { timeout: 120000 }, // 2分钟 waitforTimeout: 30000, // 全局等待命令超时 30秒 connectionRetryTimeout: 90000, // 连接重试总超时 90秒 connectionRetryCount: 3, };禁用 GPU 和沙盒如前所述在appArgs中添加--disable-gpu和--no-sandbox是 CI 环境的最佳实践。6. 常见错误与解决方案速查表我把遇到过的典型错误和解决方法整理成了表格你可以像查字典一样使用它。错误现象 / 信息可能原因排查步骤与解决方案Error: Failed to create session. ECONNREFUSED 127.0.0.1:95151. WebSocket 服务器未启动。2. 端口被占用。3. 防火墙/安全软件拦截。1. 检查logLevel: trace日志看服务启动是否有报错。2. 运行lsof -i :9515(或netstat) 检查端口占用更换port配置。3. 临时关闭防火墙或添加规则。Error: timeout: Timed out receiving message from renderer1. Electron 渲染进程卡死或无响应。2. 应用启动过慢超时时间太短。1. 独立运行你的 Electron 应用确保其功能正常。2. 大幅增加mochaOpts.timeout、waitforTimeout。3. 在before钩子中添加等待应用就绪的逻辑。Electron 窗口启动后立即关闭1. Electron 主进程代码有未捕获的异常。2.appEntryPoint路径错误导致执行了错误代码。1. 查看 WebdriverIO 日志中捕获的 Electronstderr输出。2. 使用绝对路径require(path).join(__dirname, ...)配置appEntryPoint。3. 直接使用electron your-main.js命令运行你的主文件看是否报错。测试命令卡住无任何输出1. 可能卡在依赖下载或编译某些 native 模块。2. WebdriverIO 与 Electron 版本严重不兼容。1. 检查npm install过程是否有警告或错误。2. 确认wdio-electron-service版本支持你的 Electron 版本。降级到已知稳定的组合。可以连接但browser.execute不执行或返回undefined1. 执行上下文错误可能在主进程而非渲染进程。2. 渲染进程页面尚未加载完成。1. 确保execute中的代码是适合渲染进程的。2. 在执行脚本前使用browser.waitUntil等待页面某个元素加载完成。TypeError: Cannot read property xxx of null(在测试中)1. 页面元素未找到因为页面结构已变或加载未完成。2. 异步操作未正确等待。1. 增加显式等待await $(#elem).waitForExist({ timeout });2. 使用browser.pause(ms)临时调试但正式代码应用waitUntil。在 CI 中通过本地失败或反之1. 环境变量差异。2. 文件路径差异CI 是绝对路径。3. 资源如测试数据文件未正确包含。1. 统一使用path.join(__dirname, relative/path)处理路径。2. 在 CI 配置和本地都明确设置关键环境变量如NODE_ENVtest。3. 使用__dirname定位项目根目录下的资源。7. 性能优化与最佳实践当测试稳定运行后我们可以考虑让它跑得更快、更健壮。复用 Electron 实例默认情况下wdio-electron-service可能会为每个测试文件spec重启一次 Electron 应用这很慢。可以通过配置尝试在单个会话中运行所有测试。确保你的测试是独立的并且每个测试后妥善清理状态如重置模拟数据、关闭多余窗口。并行化对于大型测试套件可以考虑并行运行。但这需要你的应用支持多实例运行且测试之间没有资源冲突如使用同一个用户数据目录。通常 Electron 测试并行化挑战较大需谨慎评估。智能等待代替硬编码browser.pause永远不要使用固定的browser.pause(3000)。使用 WebdriverIO 内置的智能等待命令如waitForExist,waitForDisplayed,waitUntil。它们会在条件满足时立即继续而不是傻等固定时间。使用 Page Object 模式将页面元素定位器和常用操作封装成类。这能极大提高代码的可维护性和复用性当 UI 变动时你只需要修改一个地方。Mock 外部依赖如果你的 Electron 应用需要连接后端 API 或数据库在 E2E 测试中应该使用 Mock Server如msw,nock来模拟这些依赖保证测试的独立性和速度。定期清理日志和报告将outputDir日志目录和 Allure 报告目录加入.gitignore并考虑在 CI 脚本中或使用rimraf在测试前清理旧文件。搭建 WebdriverIO 8 与 Electron 的自动化测试环境就像在两条湍急的河流之间架设一座索桥。WebSocket 配置是那座桥最关键的锚点。一旦你理解了通信的底层逻辑客户端-服务器模型掌握了从日志中寻找线索的方法trace级别日志是你的雷达并熟练运用配置项appEntryPoint,port,appArgs来应对不同环境这座桥就会变得无比稳固。我自己的项目从连接成功率不到 50% 到现在的 99.9%靠的就是这套系统性的排查和配置思路。记住当遇到诡异的问题时回归基础先确保 Electron 应用能独立运行再确保端口是干净的最后用最简单的测试验证连接。剩下的就是享受自动化测试带来的信心和效率提升了。