WebdriverIO：Node.js 下一代浏览器与移动端自动化测试框架｜部署与使用全指南

WebdriverIO 是基于 W3C WebDriver 与 WebDriver Bidi 协议、并兼容 Appium 的 Node.js 测试自动化框架，支持 E2E、单元与组件测试。本文按官方 README 与文档站梳理安装、wdio 配置向导、最小用例与常用服务/报告器。

1. 项目简介与定位

WebdriverIO（常缩写为 WDIO）是一个测试自动化框架，可在浏览器里跑 E2E、单元与组件测试。它基于 WebDriver 与 WebDriver Bidi 协议，并兼容 Appium，从而同时覆盖 Web 与移动端。它支持你喜欢的 BDD/TDD 测试框架（Mocha、Jasmine、Cucumber），可以本地跑，也可以通过 Sauce Labs、BrowserStack、TestingBot、TestMu AI 等云厂商跑。

1.1 核心信息一览

1.2 适用场景

• Web 端到端测试，跨 Chrome / Edge / Firefox / Safari
• 移动端原生 / 混合 App 测试（走 Appium）
• 组件测试（配合 @wdio/browser-runner，跑在真实浏览器里）
• 在 Sauce Labs / BrowserStack 等云上跑兼容性矩阵
• 需要 Allure / JUnit / HTML / Video 等报告器的团队

1.3 能力边界（官方口径）

WebdriverIO 是完整测试框架：自带 runner、配置、报告器、服务。它不是简单的浏览器驱动库——底层 webdriver 包才是 W3C WebDriver 协议的 Node.js 绑定。如果只想要脚本式浏览器控制而不需要测试编排，Puppeteer / Playwright 更轻。

2. 开源协议

WebdriverIO 采用 MIT License。

3. 官方仓库链接

• 仓库：https://github.com/webdriverio/webdriverio
• 开发者指南：https://webdriver.io/docs/gettingstarted.html
• API 参考：https://webdriver.io/docs/api.html
• 贡献指南：https://github.com/webdriverio/webdriverio/blob/main/CONTRIBUTING.md
• 更新日志：https://github.com/webdriverio/webdriverio/blob/main/CHANGELOG.md
• 路线图：https://github.com/webdriverio/webdriverio/blob/main/ROADMAP.md
• 社区资源列表：https://github.com/webdriverio-community/awesome-webdriverio
• Discord：https://discord.webdriver.io

4. 前置要求

5. 安装部署

5.1 最简方式：用官方向导初始化

npm init wdio .
# 或
npx create-wdio@latest ./your-project

向导会交互式询问：用哪个测试框架、本地还是云、需要哪些报告器 / 服务、语言是 TS 还是 JS，并自动生成 wdio.conf.js 与示例用例。

5.2 手动安装

npm install webdriverio @wdio/cli
npx wdio configuration        # 等价于交互式生成配置
npx wdio run ./wdio.conf.js   # 跑测试

5.3 核心包（按 README 拆分）

6. 最小示例代码

下面是一个 Mocha 风格的最小 WDIO 用例（./test/example.e2e.js）：

describe('webdriver.io page', () => {
  it('should have the right title', async () => {
    await browser.url('https://webdriver.io/');
    await expect(browser).toHaveTitle(
      expect.stringContaining('WebdriverIO')
    );
  });

  it('should be able to search', async () => {
    await browser.url('https://webdriver.io/');
    const searchInput = await $('input.DocSearch-Input');
    await searchInput.setValue('selector');
    await browser.keys('Enter');
  });
});

对应的 wdio.conf.js 关键片段：

export const config = {
  runner: 'local',
  specs: ['./test/**/*.e2e.js'],
  maxInstances: 10,
  capabilities: [{
    browserName: 'chrome',
    'goog:chromeOptions': { args: ['--headless=new', '--no-sandbox'] }
  }],
  logLevel: 'info',
  framework: 'mocha',
  reporters: ['spec'],
  mochaOpts: { ui: 'bdd', timeout: 60000 },
};

运行：

npx wdio run ./wdio.conf.js

7. 配置项（wdio.conf.js 常用字段）

8. 常见问题

Q1：npx wdio 找不到命令？ A：本地装的话需要 npx wdio 或 ./node_modules/.bin/wdio；全局装 npm i -g @wdio/cli。

Q2：Chrome / Edge 版本和 driver 不匹配？ A：WDIO 自带 chromedriver / edgedriver / geckodriver 服务，会按浏览器版本自动选 driver。不要在系统里再单独装 driver 导致冲突。

Q3：服务器无显示器怎么跑？ A：在 goog:chromeOptions.args 加 --headless=new --no-sandbox --disable-dev-shm-usage，或用 selenium/standalone-chrome Docker 镜像后把 hostname 指向容器。

Q4：如何接 Sauce Labs / BrowserStack？ A：在 wdio.conf.js 里把 user / key 配好，并加 services: ['sauce'] 或 ['browserstack']。

Q5：组件测试怎么跑？ A：把 runner: 'browser'，并在 Vite / Webpack 配置里加载 @wdio/browser-runner 适配。

9. 与同类工具对比

WDIO 的差异点：原生一套 API 同时覆盖 Web + 移动（Appium），插件生态（service / reporter）极其丰富，适合已经在 Node 技术栈、同时要做 Web 与 App 的团队。

10. 许可

MIT License。详见 https://github.com/webdriverio/webdriverio/blob/main/LICENSE 。

11. 责任使用声明

使用 WebdriverIO 自动化访问任何站点时，请遵守目标站点的 robots.txt 与服务条款（ToS）。请合理控制并发与并行实例数，在用例间加入延时，避免对目标服务器造成压力。请勿用 WDIO 绕过登录验证、付费墙、验证码或反爬系统。请勿批量抓取、存储或传播个人隐私数据。本工具主要应用于自身产品的端到端测试、授权范围内的兼容性验证与公开数据的合法研究。请尊重网页内容的版权，二次发布抓取结果需获得权利人许可。