WebdriverIO 中 browser.getPuppeteer() 方法失效问题解析

WebdriverIO 是一个流行的 Node.js 端到端测试框架，它提供了与浏览器交互的强大功能。在最新版本 v9 中，开发团队对 Puppeteer 集成方式进行了调整，这导致了一些开发者在使用 browser.getPuppeteer() 方法时遇到了问题。

问题现象

当开发者尝试调用 browser.getPuppeteer() 方法时，系统会抛出错误提示："Couldn't import 'puppeteer-core'! Do you have it installed?"。这个错误表明 WebdriverIO 无法找到 puppeteer-core 模块，即使该模块已经存在于项目的 node_modules 目录中。

问题根源

在 WebdriverIO v9 版本中，puppeteer-core 从直接依赖变为了 peer dependency（对等依赖）。这种设计变更意味着：

1. WebdriverIO 不再自动安装 puppeteer-core
2. 开发者需要显式地在项目中声明并安装 puppeteer-core
3. 项目需要管理 puppeteer-core 的具体版本

解决方案

要解决这个问题，开发者需要采取以下步骤：

1. 在项目的 package.json 文件中显式添加 puppeteer-core 依赖
2. 运行包管理器命令重新安装依赖（npm install 或 yarn install）
3. 确保依赖被正确写入锁文件（package-lock.json 或 yarn.lock）

最佳实践

为了避免类似问题，建议开发者：

1. 在升级 WebdriverIO 版本时仔细阅读变更日志
2. 了解 peer dependency 的概念及其管理方式
3. 定期清理并重新安装项目依赖，确保依赖关系的一致性
4. 在 CI/CD 环境中使用冻结的锁文件来保证依赖版本的一致性

技术背景

Peer dependency 是 npm/yarn 包管理中的一种特殊依赖关系，它表示一个包需要与宿主项目共享某个依赖。这种设计可以：

1. 避免重复安装相同依赖的不同版本
2. 让宿主项目控制特定依赖的版本
3. 减少包体积和潜在的版本冲突

在 WebdriverIO 的上下文中，将 puppeteer-core 设为 peer dependency 可以让开发者更灵活地选择 Puppeteer 版本，同时保持 WebdriverIO 核心包的轻量化。

通过理解这些变更背后的设计理念，开发者可以更好地管理项目依赖，避免类似问题的发生。