在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

apache/echarts

菜单

开发与测试

相关源文件

本文档概述了Apache ECharts项目中使用的开发和测试基础设施。它侧重于构建系统和视觉回归测试框架，这些是为ECharts做出贡献的开发者的基本工具。有关ECharts架构和组件的信息，请参阅 核心系统。

构建系统

ECharts使用复杂的构建系统将TypeScript源代码转换为各种分发格式。构建系统负责TypeScript编译、打包和预发布任务。

构建架构

来源： build/build.js build/config.js build/pre-publish.js

构建流程

构建过程包括几个关键步骤

  1. TypeScript编译：将源文件从TypeScript编译为JavaScript。
  2. 代码转换：移除特定于开发的代码并添加许可证前导。
  3. 打包：Rollup使用不同的选项创建各种分发包。
  4. 类型定义生成：打包TypeScript声明以供分发。

构建系统支持不同的构建目标

构建目标描述输出文件
all完整的ECharts功能dist/echarts.js
common常用的图表和组件dist/echarts.common.js
simple仅包含基本图表dist/echarts.simple.js
extension附加扩展dist/extension/*.js
ssr服务器端渲染客户端ssr/client/dist/index.js

命令行用法

构建系统可以通过npm脚本操作，也可以直接通过命令行操作

来源： build/build.js40-78 build/config.js90-119 build/pre-publish.js84-169

预发布流程

预发布流程准备代码库以供分发

  1. 将`lib`目录下的TypeScript文件转换为JavaScript
  2. 创建所有文件的ESModule版本
  3. 移除特定于开发的代码块
  4. 为所有文件添加许可证前导
  5. 打包类型定义
  6. 生成入口文件

此过程通过`--prepublish`标志执行，或通过npm脚本`npm run prepare`执行。

来源： build/pre-publish.js175-208 .gitignore180-212 package.README.md8-26

视觉回归测试系统

ECharts使用全面的视觉回归测试系统，以确保更改不会引入视觉回归。

概述

视觉回归测试系统允许开发者

  1. 比较不同ECharts版本的视觉输出
  2. 针对本地更改、发布版本或夜间构建进行测试
  3. 捕获和重放用户交互
  4. 生成视觉差异报告

该系统使用Puppeteer进行浏览器自动化和屏幕截图比较。

来源： test/runTest/server.js test/runTest/cli.js test/runTest/client.js test/runTest/runtime/main.js

系统组件

服务器端组件

  • server.js：主服务器，协调测试执行并与客户端UI通信
  • cli.js：通过Puppeteer运行测试的命令行界面
  • store.js：管理测试元数据、结果和配置
  • util.js：用于文件处理、版本获取和环境设置的实用函数

客户端组件

  • client.js/index.html：用于选择测试、配置选项和查看结果的Web UI
  • recorder/index.html：用于记录用户交互以进行测试自动化的工具
  • runtime/main.js：在测试执行期间注入到浏览器中的JavaScript代码

来源： test/runTest/server.js65-85 test/runTest/cli.js19-66 test/runTest/client.js20-121

测试用例结构

ECharts中的测试用例是HTML文件，用于设置特定的图表配置。每个测试用例通常

  1. 导入ECharts库
  2. 创建一个DOM容器
  3. 定义一个选项配置
  4. 创建一个ECharts实例
  5. 可能包含特定的测试条件或断言

测试操作以JSON文件的形式存储在`test/runTest/actions/`目录下，其中包含记录的用户交互，如鼠标移动、点击和滚动。

来源： test/runTest/cli.js114-147 test/runTest/actions/__meta__.json test/graph-case.html test/custom-update.html

测试执行工作流

测试执行过程遵循以下步骤

  1. 初始化：服务器启动并加载测试元数据
  2. 选择：用户通过Web UI选择要运行的测试
  3. 配置：用户配置测试选项（版本、渲染器等）
  4. 执行：服务器启动Puppeteer实例来运行测试
  5. 屏幕截图捕获：Puppeteer在定义的点捕获屏幕截图
  6. 比较：将屏幕截图与预期结果进行比较
  7. 报告：结果显示在Web UI中，并且可以导出为报告

测试配置选项

选项描述
预期来源基准版本的来源（发布版本、夜间构建、PR、本地）
预期版本要比较的特定版本号
实际来源正在测试的版本的来源
实际版本正在测试的版本号
渲染器渲染模式（canvas/svg）
粗指针启用/禁用粗指针模拟
线程并行测试线程数

来源： test/runTest/server.js239-258 test/runTest/cli.js36-59 test/runTest/client/index.html146-216

运行测试

设置测试环境

要运行视觉回归测试，您需要

  1. 在`test/runTest`目录中安装依赖项

  2. 启动测试服务器

这将会在您的浏览器中启动测试仪表板。

使用测试仪表板

测试仪表板允许您

  1. 选择要运行的测试
  2. 配置测试选项（版本、渲染器等）
  3. 单独或批量运行测试
  4. 查看测试结果和视觉差异
  5. 生成测试结果报告

记录测试操作

交互记录器允许您

  1. 打开一个测试用例
  2. 记录用户交互（鼠标移动、点击等）
  3. 保存记录的操作以便自动重放
  4. 重放操作以验证测试行为

来源: test/runTest/client/client.js398-546 test/runTest/server.js395-453 test/runTest/runtime/main.js78-112

分析测试结果

测试结果显示在仪表盘中，其中包含

  1. 预期截图和实际截图之间的视觉差异
  2. 每个截图的差异比例
  3. 测试执行过程中的控制台日志和错误
  4. 总体测试通过/失败状态

对于失败的测试，您可以

  • 检查视觉差异
  • 比较预期和实际截图
  • 生成详细的测试报告以供分享

来源: test/runTest/client/index.html225-316 test/runTest/genReport.js104-151

测试最佳实践

创建有效的测试用例

  1. 让每个测试聚焦于 ECharts 的特定功能或方面
  2. 尽可能使用简单、可预测的数据
  3. 包含常见和边界情况
  4. 确保测试是独立的，并且不依赖于外部资源
  5. 使用 testHelper.create() 函数来简化图表创建

记录可靠的操作

  1. 缓慢而有条理地执行操作
  2. 避免不必要地移动鼠标
  3. 在关键点包含暂停
  4. 通过回放来验证已记录的操作
  5. 使操作聚焦于正在测试的特定功能

维护测试

  1. 在进行有意视觉更改时更新预期截图
  2. 仔细审查测试失败，区分 bug 和有意更改
  3. 保持测试用例的组织性和命名清晰
  4. 移除冗余或过时的测试
  5. 在 API 更改时更新测试

来源: test/runTest/blacklist.js test/runTest/actions/graph-case.json test/lib/config.js

结论

Apache ECharts 的开发和测试基础设施为维护代码质量和防止视觉回归提供了坚实的基础。构建系统能够有效地将 TypeScript 源代码转换为各种分发格式，而视觉回归测试系统则确保更改不会无意中改变图表的视觉输出。

通过理解和利用这些工具，贡献者可以充满信心地进行开发，并保持 ECharts 项目所需的高质量标准。