Apache ECharts 视觉测试中的跨客户端坐标偏移问题分析与解决方案

问题背景

在 Apache ECharts 的自动化视觉测试过程中，我们发现了一个影响测试稳定性的关键问题：当相同的测试用例在不同客户端环境下运行时，页面元素的垂直坐标位置（pageY）会出现不一致的情况。这种现象导致录制好的测试用例在回放时无法准确定位目标元素，产生误判。

现象表现

具体表现为：

1. 测试页面中相同文本内容在不同客户端显示高度存在差异（如166.5px vs 162px）
2. 鼠标操作事件的坐标记录因高度差异而产生偏移
3. 修改测试用例中的文本内容会导致后续所有坐标记录失效

根本原因分析

经过深入排查，发现问题根源在于：

1. 浏览器渲染差异：测试页面未明确指定行高(line-height)属性，默认使用"normal"值，这在不同浏览器/设备上会计算出不同的像素值
2. Puppeteer版本限制：项目使用的Puppeteer v9存在一个已知问题——它会将分数像素值(如18.56px)强制四舍五入为整数像素值(18px)，而现代浏览器实际支持亚像素渲染

解决方案

短期解决方案

1. 升级Puppeteer：将Puppeteer升级至v23或更高版本，该版本已修复分数像素处理问题
2. 明确样式定义：为测试页面添加确定的line-height值，消除浏览器间的渲染差异

长期解决方案

建议实现一套基于锚点的智能测试系统：

1. 锚点记录机制：

   • 在录制阶段，为每个ECharts DOM元素添加隐藏的锚点标记
   • 记录这些锚点的绝对页面坐标到测试用例文件中

2. 智能校准系统：

   • 回放时实时计算当前锚点位置
   • 与录制时的锚点位置进行对比校准
   • 自动调整操作坐标以匹配当前渲染环境

3. 容错处理：

   • 当检测到显著位置偏移时发出警告
   • 提供手动校准选项
   • 记录环境差异信息用于后续分析

实施建议

1. 分阶段实施：

   • 优先升级Puppeteer解决最紧急的像素计算问题
   • 随后实现锚点系统提升长期稳定性

2. 测试覆盖：

   • 新增测试用例验证分数像素场景
   • 增加跨浏览器/跨设备测试矩阵

3. 文档完善：

   • 在测试指南中明确环境要求
   • 添加测试用例编写规范，避免依赖绝对坐标

总结

Apache ECharts作为数据可视化领域的流行框架，其测试稳定性直接影响开发效率和版本质量。通过解决这个视觉测试中的坐标偏移问题，不仅可以提高现有测试用例的可靠性，还能为未来更复杂的可视化测试场景奠定基础。建议开发团队优先实施Puppeteer升级方案，并逐步推进锚点系统的设计与实现。