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

问题背景

在Apache ECharts项目的视觉测试过程中，我们发现了一个影响测试稳定性的关键问题：当在不同客户端环境下运行基于页面坐标的视觉测试时，测试结果会出现不一致的情况。具体表现为，在录制测试用例时捕获的页面元素坐标（如pageY值）与回放时获取的实际坐标存在偏差，导致自动化测试无法准确复现预期的交互操作。

问题现象

测试人员观察到，在两种不同环境下打开相同的测试页面时：

1. 测试用例录制环境（如本地开发服务器）
2. 测试用例执行环境（如CI/CD流水线）

页面中相同文本元素的高度测量值出现了差异（166.5px vs 162px）。这种差异直接导致了后续基于坐标的鼠标操作无法准确定位到预期位置，使得自动化测试失败。

根本原因分析

经过深入排查，我们发现问题的根源来自以下几个方面：

1. 浏览器渲染差异：当CSS中未明确指定line-height属性时，浏览器会使用默认值"normal"，这个值在不同浏览器版本或不同操作系统下可能产生不同的计算值。

2. Puppeteer版本限制：项目当前使用的Puppeteer v9存在一个已知问题——它会将分数像素值（如18.56px）强制四舍五入为整数像素值（18px）。这个行为在较新版本的Puppeteer（如v23）中已经得到修复。

3. 测试框架设计缺陷：现有的视觉测试方案过度依赖绝对坐标值，缺乏对动态布局变化的适应能力。当测试页面内容发生微小变化（如修改标题文本）时，整个页面的布局流可能发生变化，导致所有后续记录的坐标操作失效。

解决方案

短期解决方案

1. 升级Puppeteer版本：将Puppeteer升级到v23或更高版本，解决分数像素计算问题。这是最直接的修复方式，能够消除因浏览器引擎差异导致的渲染不一致。

2. 明确CSS样式：为测试页面中的关键元素指定明确的line-height值，避免依赖浏览器的默认计算。例如：

   body {
     line-height: 1.5; /* 使用无单位值，基于当前字体大小的倍数 */
   }
   

长期解决方案

我们提出了一种更健壮的"基于锚点"的测试方案：

1. 锚点标记机制：

   • 在录制阶段，为每个ECharts DOM元素添加隐藏的锚点标记
   • 记录这些锚点在页面中的相对位置信息
   • 将锚点坐标与测试操作一起保存到测试用例中

2. 动态校准机制：

   • 在执行测试时，首先验证当前锚点位置与录制时的差异
   • 如果发现偏移，自动调整后续操作的坐标值
   • 提供警告信息通知测试人员存在的差异

3. 相对定位测试：

   • 重构测试操作记录方式，基于相对位置而非绝对坐标
   • 例如，记录"点击图表右上角10px处"而非"点击(500,300)位置"

实施建议

1. 分阶段实施：

   • 首先升级Puppeteer解决最紧迫的渲染一致性问题
   • 然后逐步引入锚点机制，增强测试的鲁棒性

2. 测试用例维护：

   • 建立测试用例版本控制系统
   • 当页面布局发生重大变化时，提供便捷的重录机制

3. 监控机制：

   • 建立测试稳定性监控
   • 跟踪跨环境测试结果的一致性

总结

Apache ECharts作为数据可视化领域的知名项目，其测试稳定性直接关系到项目的开发效率和最终质量。通过解决这个视觉测试中的坐标偏移问题，我们不仅能够提高当前测试套件的可靠性，还为未来更复杂的可视化测试场景奠定了基础。建议开发团队优先实施Puppeteer升级方案，同时规划长期的结构化测试框架改进。