WebdriverIO v9 中 fetch 请求失败问题的分析与解决方案

问题背景

WebdriverIO 是一个流行的 Node.js 端到端测试框架，在最新发布的 v9 版本中，团队将底层 HTTP 请求库从 got 迁移到了原生的 fetch API。这一变更带来了性能提升，但也引入了一个关键问题：在某些情况下，测试会随机失败并抛出 fetch failed 错误，具体表现为 ECONNREFUSED（连接被拒绝）或 UND_ERR_CONNECT_TIMEOUT（连接超时）错误。

问题现象

在 WebdriverIO v9 环境下运行测试时，会出现以下两种典型错误：

1. 连接被拒绝错误

TypeError: fetch failed
error properties: Object({ cause: Error: connect ECONNREFUSED 127.0.0.1:62837 })

2. 连接超时错误

TypeError: fetch failed
error properties: Object({ cause: ConnectTimeoutError: Connect Timeout Error })

这些错误会随机出现在不同的测试用例中，且出现频率较高（在669个测试用例中可能影响14-25个测试）。错误发生时，浏览器驱动服务似乎暂时不可用，导致测试失败。

问题根源

经过分析，问题主要源于以下两个因素：

1. 请求重试机制失效：在 v8 版本中使用 got 库时，内置了完善的请求重试机制，能够自动处理临时性的连接问题。而切换到原生 fetch 后，这部分逻辑需要重新实现。

2. 错误处理不完整：新的实现未能正确处理底层网络错误（如 ECONNREFUSED 和 UND_ERR_CONNECT_TIMEOUT），导致这些错误直接抛出而没有进行重试。

解决方案

WebdriverIO 团队通过以下改进解决了这个问题：

1. 扩展错误重试逻辑：在请求模块中增加了对网络层错误的捕获和处理，包括：

   • ECONNREFUSED（连接被拒绝）
   • UND_ERR_CONNECT_TIMEOUT（连接超时）

2. 完善错误传播机制：正确处理了错误对象的嵌套结构，确保能够从 fetch 抛出的错误中提取出底层错误代码。

3. 保留重试计数：维持了与之前版本相同的重试次数（默认为3次），确保临时性问题能够自动恢复。

验证效果

改进后的版本中，当出现临时性连接问题时，系统会输出警告日志并自动重试：

[WARN] WebDriverError: Request failed with error code ECONNREFUSED when running "element/.../text" with method "GET"

大多数情况下，重试能够成功恢复测试执行。只有在极端情况下（如服务长时间不可用），才会最终抛出错误。

最佳实践建议

对于使用 WebdriverIO v9 的用户，建议：

1. 升级到最新版本：确保包含了完整的错误重试修复。

2. 监控测试稳定性：关注测试日志中的重试警告，它们可能指示环境或配置问题。

3. 考虑增加重试间隔：对于高负载环境，可以在重试之间增加短暂的延迟（如通过自定义请求中间件实现）。

4. 优化测试环境：确保测试机器有足够资源，避免因资源不足导致浏览器驱动服务不稳定。

总结

WebdriverIO v9 向原生 fetch 的迁移是一个重要的架构改进，虽然在初期遇到了请求重试方面的问题，但通过完善错误处理机制已经得到了解决。这一案例也提醒我们，在进行底层库替换时，需要特别注意原有功能（如错误处理和重试机制）的完整迁移。