SkyWalking E2E 端到端测试完全指南:基于 e2e-v2 框架编写与运行集成用例
SkyWalking E2E 端到端测试完全指南:基于 e2e-v2 框架编写与运行集成用例
本篇技术指南系统讲解 Apache SkyWalking 的端到端(E2E)测试体系:它如何在真实环境中拉起 OAP、存储、协调器与被监控服务,并校验完整的数据流与查询结果。读者将掌握 e2e-v2 框架(skywalking-infra-e2e + skywalking-cli)的用例结构、e2e.yaml 配置编写、Go 模板期望文件的校验语义,以及本地运行与 CI 排障的完整实战方法,可直接用于在 SkyWalking 仓库中新增或维护 E2E 用例。
E2E 测试在 SkyWalking 质量保障体系中的定位
SkyWalking 高度依赖自动化测试来执行软件质量保证,E2E 测试是其不可或缺的组成部分。端到端测试是一种用于验证应用流程从开始到结束是否符合设计预期的方法论,其目的是识别系统间的依赖,并确保正确的信息能够在各个系统组件与系统之间传递。
与单元测试、集成测试不同,SkyWalking 的 E2E 测试始终在真实环境中完成以下动作:
- 部署 OAP 服务器、存储(storage)、协调器(coordinator)、WebApp 以及被插桩(instrumented)的服务;
- 让被监控服务产生真实流量;
- 验证数据流与最终的查询结果是否符合预期。
E2E 用例会涉及 OAP、存储、协调器、WebApp、被监控服务中的一部分或全部,这些组件统一由 docker-compose 或 KinD(Kubernetes in Docker)编排。这也决定了 E2E 用例覆盖的是"SkyWalking 项目作为一个整体"的行为,而不仅是某个模块的单元行为。
e2e-v2 框架:自 8.9.0 起的 E2E 测试体系
自 SkyWalking 8.9.0 起,项目迁移到 e2e-v2 框架,利用两个外部工具完成整个 E2E 流程:
skywalking-infra-e2e:负责控制 E2E 的整个生命周期——搭建环境、触发流量、执行校验、清理环境;skywalking-cli(即swctl):负责与 OAP 交互,例如向 OAP 发起查询请求并获取指标响应,其底层通过 GraphQL、PromQL、LogQL、TraceQL 等协议对接 OAP 各查询端点。
仓库中所有 E2E 用例统一存放在 test/e2e-v2/cases 目录下,每个特性(feature)一个子目录。以告警(alarm)为例,其用例按存储后端进一步划分为 alarm/banyandb、alarm/es(含 es-sharding 子用例)、alarm/mysql、alarm/postgres 等多个目录,体现了"同一功能、多种存储矩阵"的测试策略。
编写 E2E 用例的完整流程
官方文档将编写流程归纳为两大阶段:搭建环境 与 编排组件,再辅以用例配置、期望数据定义与运行验证。以下结合仓库实际用例逐步展开。
第一步:搭建本地环境
编写用例前需要先安装 E2E 工具链:
- 安装
skywalking-infra-e2e(提供e2e命令); - 安装
skywalking-cli(swctl)与yq(一般这两个就足够),若用例有额外需求再安装其他工具。
仓库提供了现成的安装脚本,位于 test/e2e-v2/script/prepare/setup-e2e-shell,其中包括 install.sh 统一入口以及 install-swctl.sh、install-yq.sh、install-jq.sh、install-kubectl.sh、install-helm.sh、install-istioctl.sh、install-etcdctl.sh、install-cilium.sh 等按工具划分的脚本。以 install.sh 为例,它会创建 /tmp/skywalking-infra-e2e/bin 目录并按参数分发到具体的 install-<name>.sh;install-swctl.sh 则会根据共享环境变量 SW_CTL_COMMIT 从指定 commit 拉取 skywalking-cli 源码并执行 make install DESTDIR=$BIN_DIR 完成编译安装(若已安装的 swctl 版本与期望 commit 不匹配会自动重装)。
各 agent 与依赖的 commit 版本统一钉死在 test/e2e-v2/script/env 中,例如 SW_AGENT_JAVA_COMMIT、SW_CTL_COMMIT、SW_BANYANDB_COMMIT 等,保证测试矩阵可复现。该文件在用例的 e2e.yaml 中通过 init-system-environment 引入。
第二步:编排被测组件
E2E 的目标是测试 SkyWalking 整体,因此第一步要确定用例要验证什么,再据此编排组件。为简化编排,项目使用 docker-compose.yml 描述所需容器及其依赖关系。
编排要点如下:
- 决定需要哪些容器、各多少个。例如集群模式测试通常需要 2 个以上 OAP 节点、协调器(如 zookeeper)、存储(如 ElasticSearch)以及被插桩服务;
- 在
docker-compose.yml中定义容器,仔细指定依赖关系、启动顺序,最重要的是把它们正确连接起来:Agent 端要设置正确的 OAP 地址,OAP 端要设置正确的协调器地址,等等; - 定义 E2E 用例配置(
e2e.yaml); - 编写用于校验的期望数据(expected 文件,YAML 格式)。
以 test/e2e-v2/cases/alarm/es/docker-compose.yml 为例,它声明了三个服务:
es:Elasticsearch 8.18.8 单节点,通过/dev/tcp/127.0.0.1/9200探活做健康检查;oap:通过extends复用 test/e2e-v2/script/docker-compose/base-compose.yml 中的基础定义,并通过环境变量SW_STORAGE: elasticsearch、SW_SEARCHABLE_ALARM_TAG_KEYS: level,receivers定制存储与可搜索告警标签,同时把../alarm-settings.yml挂载为 OAP 的alarm-settings.yml以注入测试专用告警规则;depends_on的condition: service_healthy确保 OAP 等 ES 就绪后再启动;provider:同样extends基础定义中的 provider 服务(被插桩的 Java 服务),端口 9090 暴露给流量触发与校验,depends_onOAP 健康后启动。
可以看到,容器之间的启动顺序与依赖关系正是通过 depends_on + 健康检查来表达的,这是保证 E2E 稳定性的关键手段。
第三步:定义 e2e.yaml 用例配置
e2e.yaml 是 skywalking-infra-e2e 的用例入口,由 setup、trigger、verify 三大块构成。以 test/e2e-v2/cases/alarm/es/e2e.yaml 为真实示例:
setup:
env: compose # 使用 docker-compose 搭建环境
file: docker-compose.yml # 编排文件
timeout: 20m # 环境搭建超时
init-system-environment: ../../../script/env # 引入共享环境变量(各 commit 版本等)
steps:
- name: set PATH
command: export PATH=/tmp/skywalking-infra-e2e/bin:$PATH
- name: install yq
command: bash test/e2e-v2/script/prepare/setup-e2e-shell/install.sh yq
- name: install swctl
command: bash test/e2e-v2/script/prepare/setup-e2e-shell/install.sh swctl
trigger:
action: http # 触发方式:HTTP 请求
interval: 3s # 触发间隔
times: 45 # 触发次数
url: http://${provider_host}:${provider_9090}/users
method: POST
body: '{"id":"123","name":"skywalking"}'
headers:
"Content-Type": "application/json"
verify:
retry:
count: 30 # 校验失败重试次数
interval: 3s # 重试间隔
cases:
- includes: # 引入共享校验用例文件
- ../alarm-cases.yaml
各部分职责:
setup:定义环境如何搭建(env: compose或env: kind)、编排文件、超时时间、初始化系统环境以及环境准备命令步骤(steps)。这里的init-system-environment指向共享的script/env,其中包含了各 agent 仓库的 commit 固定值;trigger:定义如何产生业务流量。action: http表示通过 HTTP 请求触发,interval/times控制频率与总量,url/method/body/headers定义请求内容;也支持其他触发方式(如generate-traffic等,视用例需要);verify:定义校验策略。retry.count与retry.interval控制"查询-比对"的轮询重试(因为指标聚合需要时间);cases列出校验用例,includes允许将一组查询-期望对抽取成共享文件(如alarm-cases.yaml),供多个存储后端的用例复用,避免重复。
第四步:编写期望校验数据
校验用例文件(如 alarm-cases.yaml)由若干 query + expected 对组成:query 是实际执行的查询命令(通常调用 swctl 或 curl 访问 OAP),expected 指向对应的期望 YAML 文件。以 test/e2e-v2/cases/alarm/alarm-cases.yaml 为例:
cases:
# service list
- query: swctl --display yaml --base-url=http://${oap_host}:${oap_12800}/graphql service ls
expected: expected/service.yml
# 查询告警,按标签过滤
- query: |
sleep 5;
swctl --display yaml --base-url=http://${oap_host}:${oap_12800}/graphql alarm ls --tags level=WARNING,receivers=lisi
expected: expected/silence-before-graphql-warn.yml
# 查询告警标签自动补全
- query: swctl --display yaml --base-url=http://${oap_host}:${oap_12800}/graphql alarm autocomplete-keys
expected: expected/tag-keys.yml
# 通过 GraphQL 调用 queryAlarms 综合查询 API,按实体过滤
- query: |
curl -s -X POST http://${oap_host}:${oap_12800}/graphql \
-H 'Content-Type: application/json' \
-d '{"query":"query ($cond: AlarmQueryCondition!) { queryAlarms(condition: $cond) { msgs { scope name } } }","variables":{"cond":{"duration":{"start":"...","end":"...","step":"MINUTE"},"paging":{"pageNum":1,"pageSize":50},"entities":[{"scope":"Service","serviceName":"e2e-service-provider","normal":true}]}}}' | yq -P '.data.queryAlarms'
expected: expected/queryAlarms-entity-provider.yml
从中可以看到三类典型查询模式:
swctl子命令 +--display yaml --base-url:如service ls、alarm ls --tags、alarm autocomplete-keys,输出 YAML 便于与期望文件比对;curl直接调用 GraphQL:用于queryAlarms这类带复杂条件(duration、paging、entities、ruleNames、layer)的综合查询,并通过yq -P把 JSON 转为规整 YAML;sleep前置等待:由于告警检测、指标聚合存在延迟,查询命令前常带sleep(5s、30s、60s)等待数据就绪,用于验证静默前/后、恢复等时间点行为。
运行 E2E 用例
所有 E2E 用例都应放在 skywalking/test/e2e-v2/cases 下。在 SkyWalking 仓库根目录执行 e2e 命令即可运行指定用例,例如:
e2e run -c test/e2e-v2/cases/alarm/es/e2e.yaml
说明:官方文档原文给出的示例路径为
test/e2e-v2/cases/alarm/h2/e2e.yaml;以当前仓库实际结构为准,alarm 用例已按存储后端组织为alarm/banyandb、alarm/es、alarm/mysql、alarm/postgres等目录,请按实际存在的路径运行。
e2e run -c <config> 会依次执行 setup(拉起环境)→ trigger(产生流量)→ verify(反复查询比对直至成功或重试耗尽)→ 清理环境。
期望文件编写深入:模板函数与校验语义
期望文件(expected 目录下的 .yml)是 E2E 校验的核心,仓库在 test/e2e-v2/CLAUDE.md 中给出了完整的编写规范。其工作机制是:
- 执行查询(
swctl/curl)得到实际 YAML/JSON; - 把期望文件作为 Go 模板渲染,以实际数据作为
{{ . }}上下文; - 将渲染后的期望与实际结果分别反序列化为 YAML;
- 使用
go-cmp做深度结构相等比较——数组按序比较,map 按键匹配。
核心校验策略是:验证数据正确性,而非仅仅验证存在性。对所有有意义的字段(服务名、端点名、指标名、标签键/值、span 名、组件名、layer 名、scope 名等)使用精确字面值;仅对真正动态的值(时间戳、UUID、生成的 ID、时长、IP 地址)使用 notEmpty/gt/ge 这类宽松断言。若无法确定某字段应精确还是宽松,应向开发者确认后再定,避免"过松漏 bug"或"过紧导致 flaky"。
模板函数的共同机制是:校验成功时返回实际值本身(渲染结果等于实际值从而匹配),失败时返回错误字符串(如 <"" is empty, wanted is not empty>),与实际情况不匹配从而在 diff 中暴露问题。
notEmpty:断言值存在且非空
仅接受 nil 或 string 类型。会去除首尾空白后检查,成功时返回原始(未修剪)字符串:
name: {{ notEmpty .name }} # name 为 nil、"" 或纯空白时失败
| 输入 | 结果 |
|---|---|
"hello" |
"hello"(通过) |
"" |
<"" is empty, wanted is not empty>(失败) |
" " |
<" " is empty, wanted is not empty>(失败) |
nil |
<nil is empty, wanted is not empty>(失败) |
123(非字符串) |
<notEmpty only supports nil or string type, but was int>(失败) |
注意:数值字段不能使用 notEmpty(会类型报错),应改用 ge .port 0。
gt / ge / lt / le:数值比较
成功时返回左侧操作数本身。支持 int、uint、float,跨类型(int 与 float)比较会通过 float64 统一转换;字符串与数字比较是错误:
starttime: {{ gt .starttime 0 }} # 必须 > 0
duration: {{ ge .duration 0 }} # 必须 >= 0
value: {{ le .value 10000 }} # 必须 <= 10000
count: {{ lt .count 100 }} # 必须 < 100
regexp:正则匹配
按标准 Go 正则语法匹配,成功时返回原字符串:
name: {{ regexp .name "^service-.*" }}
id: {{ regexp .id "[a-f0-9]{32}" }}
b64enc:实体 ID 编码
SkyWalking 的实体 ID 由 base64 编码的名称与后缀拼接而成,是期望文件中出现频率极高的函数:
# Service ID = base64(name) + ".1"(普通服务)或 ".0"(虚拟服务)
id: {{ b64enc "e2e-service-provider" }}.1
# Instance ID = serviceID + "_" + base64(instanceName)
id: {{ b64enc "e2e-service-provider" }}.1_{{ b64enc "provider1" }}
# Endpoint ID = serviceID + "_" + base64(endpointName)
id: {{ b64enc "e2e-service-provider" }}.1_{{ b64enc "POST:/users" }}
# Dependency ID = sourceServiceID + "-" + targetServiceID
id: {{ b64enc "e2e-service-consumer" }}.1-{{ b64enc "e2e-service-provider" }}.1
此外还有 subtractor(连续减法,如 {{ subtractor 100 10 20 }} 得 70)与 sha256enc/sha512enc(哈希)等工具函数。
contains:无序子集匹配(关键)
普通 YAML 数组比较是有序且精确的;contains 则启用无序子集匹配——期望中的每一项都必须能在实际数组中找到对应项,但顺序无关,且实际数组中的多余项会被忽略:
{{- contains .services }}
- name: service-a
- name: service-b
{{- end }}
算法上:对实际数组的每个元素,以其为上下文渲染块体,检查是否有期望模式与之匹配;所有期望模式都必须找到匹配(即"实际包含全部期望",而非"匹配任一即可")。contains 支持嵌套(用于嵌套数组),且每个期望项必须匹配不同的实际项(保持基数/数量语义)。
常见校验模式
服务列表——精确校验名称与属性:
{{- contains . }}
- id: {{ b64enc "e2e-service-provider" }}.1
name: e2e-service-provider
group: ""
shortname: e2e-service-provider
normal: true
layers:
- GENERAL
- id: {{ b64enc "e2e-service-consumer" }}.1
name: e2e-service-consumer
group: ""
shortname: e2e-service-consumer
normal: true
layers:
- GENERAL
{{- end }}
拓扑——校验节点类型、组件与调用关系:
nodes:
{{- contains .nodes }}
- id: {{ b64enc "e2e-service-provider" }}.1
name: e2e-service-provider
type: Tomcat
isreal: true
layers:
- GENERAL
- id: {{ b64enc "localhost:-1" }}.0
name: localhost:-1
type: H2
isreal: false
layers:
- VIRTUAL_DATABASE
{{- end }}
calls:
{{- contains .calls }}
- source: {{ b64enc "e2e-service-provider" }}.1
sourcecomponents:
- h2-jdbc-driver
target: {{ b64enc "localhost:-1" }}.0
id: {{ b64enc "e2e-service-provider" }}.1-{{ b64enc "localhost:-1" }}.0
detectpoints:
- CLIENT
{{- end }}
Trace——span 名、服务、组件精确;时间戳、ID 用动态断言:
- traceid: {{ .traceid }}
segmentid: {{ .segmentid }}
spanid: 0
parentspanid: -1
refs: []
servicecode: e2e-service-consumer
serviceinstancename: consumer1
starttime: {{ gt .starttime 0 }}
endtime: {{ gt .endtime 0 }}
endpointname: POST:/users
type: Entry
component: Tomcat
iserror: false
layer: Http
tags:
{{- contains .tags }}
- key: http.method
value: POST
- key: http.status_code
value: "200"
- key: url
value: {{ notEmpty .value }}
{{- end }}
指标——标签键/值精确,时间戳与动态值宽松:
type: TIME_SERIES_VALUES
results:
{{- contains .results }}
- metric:
labels:
{{- contains .metric.labels }}
- key: p
value: "50"
{{- end }}
values:
{{- contains .values }}
- id: {{ notEmpty .id }}
value: {{ notEmpty .value }}
owner: null
traceid: null
{{- end }}
{{- end }}
error: null
告警——校验 scope、名称、标签值:
msgs:
{{- contains .msgs }}
- starttime: {{ gt .starttime 0 }}
scope: Service
id: {{ b64enc "e2e-service-provider" }}.1
name: e2e-service-provider
tags:
- key: level
value: WARNING
{{- end }}
其他实用模式还包括:with 作用域嵌套对象校验、$var := 变量赋值与复用、Prometheus 风格 [timestamp, value] 元组校验、指标数据缺口(值为 null)容忍、显式 null 字段校验(error: null、owner: null),以及用重复 N 个 notEmpty 模式断言"至少 N 项满足条件"。
编写陷阱速查
notEmpty只接受字符串或 nil——传整数会类型报错,数值字段用ge/gt;gt/ge/lt/le不能比较字符串与数字——"100"这样的字符串值需先确认类型;- 不用
contains时数组按序精确比较——顺序不确定的列表必须用contains; - 注意模板空白控制——用
{{-与-}}修剪指令周围空白,否则多余空行会破坏 YAML 结构; contains要求全部期望项匹配——是"实际包含全部期望"而非"任一";- 多行值需
println——日志内容等多行字符串要用{{ notEmpty (println ...) }}保留换行; - 许可证头——所有
.yml期望文件必须包含 Apache 2.0 许可证头(.md文件除外),仓库中的每个期望文件(如 test/e2e-v2/cases/alarm/expected/service.yml)均遵循此规范。
故障排查与 CI 注意事项
本地调试:在非 CI(本地)模式下,所有容器的日志都会输出到 stdout,便于直接观察。CI 调试:在 CI 中日志会被保存并上传到 GitHub 服务器,测试失败时可通过页面右上角 "Artifacts/Download artifacts/logs" 下载日志用于排障。
PR 检查失败排查:官方文档特别强调——请先在本地验证新增的 E2E 用例。如果本地通过但 PR 检查状态失败,请确认所有更新/新增的文件(尤其是子模块中的文件)都已提交并包含在 PR 中,或将 git HEAD 重置到远端后再次在本地验证。该提示对应一个常见根因:本地存在未提交的子模块变更或陈旧构建产物,导致"本地绿、CI 红"。
小结
SkyWalking 的 E2E 体系以 e2e-v2 框架为骨架,用 docker-compose/KinD 搭建真实环境、用 skywalking-infra-e2e 驱动 setup→trigger→verify 流程、用 skywalking-cli 完成对 OAP 的查询交互,最终以"Go 模板期望文件 + go-cmp 深度比较"的方式严格校验数据正确性。编写新用例时,可参照 test/e2e-v2/cases 下各特性目录的 e2e.yaml、docker-compose.yml 与 expected/ 文件,复用 test/e2e-v2/CLAUDE.md 中沉淀的模板函数与校验模式,即可快速产出稳定、可复现、可并入 CI 的端到端测试用例。