Prometheus Operator 测试体系实战指南:单元测试、Golden 文件与端到端测试全解析
Prometheus Operator 测试体系实战指南:单元测试、Golden 文件与端到端测试全解析
Prometheus Operator 是在 Kubernetes 之上创建、配置与管理 Prometheus 集群的利器,其代码库的健壮性依赖于一套覆盖从单个函数到完整集群行为的测试体系。本文以仓库根目录 TESTING.md 为核心骨架,结合 Makefile 中的真实测试目标定义、scripts/update-golden-files.sh 与 test/e2e/main_test.go 等源码实现,系统讲解 Prometheus Operator 的单元测试、Golden 文件机制与端到端(E2E)测试,并给出本地开发场景下最快、最精准的运行命令,帮助你脱离对 CI 的依赖,在本地获得即时反馈。
为什么需要这套测试体系
向 Prometheus Operator 提交代码时,每一个 Pull Request 都会跑一套庞大的测试套件。测试给项目整体健康度和可靠性带来的收益是显而易见的,而从开发者体验角度看,它的价值同样突出:
- 测试即文档:测试用例是软件预期行为的最佳说明书,新贡献者可以通过阅读测试快速理解某个函数或组件"应该"怎么工作。
- 防止回归:测试验证新改动不会破坏已有功能,保障了持续演进的稳定性。
- 加速本地反馈循环:在本地运行测试,贡献者不必每次改动都等待 CI 结果,开发体验大幅提升。
测试类别总览
Prometheus Operator 的测试大致分为两大类别,覆盖不同粒度的验证目标:
| 类别 | 验证粒度 | 是否依赖真实 Kubernetes 集群 | 典型耗时 |
|---|---|---|---|
| 单元测试(Unit tests) | 单个代码片段、函数、配置生成逻辑 | 否 | 秒级到分钟级 |
| 端到端测试(E2E tests) | 完整集群行为、多控制器协同 | 是(KinD / MiniKube 等) | 数十分钟级别 |
从 Makefile 可以看到,一个聚合目标 make test 会依次执行 test-unit test-long test-e2e,即完整跑一遍"短模式单元测试 + 长模式测试 + 端到端测试"。
单元测试(Unit tests)
单元测试用于在隔离环境中测试特定代码片段,是追求快速反馈时的最佳工具。
典型场景:验证 CRD 新字段是否进入 ConfigMap
假设你在做一个为 ScrapeConfig CRD 添加新字段的 PR,想验证改动是否正确反映到生成的 ConfigMap 中。如果走完整流程,你需要:创建 Kubernetes 集群 → 安装所有 CRD → 运行 Prometheus Operator → 部署带 ScrapeConfigSelectors 的 Prometheus 资源 → 再检查 live 对象。这显然过于繁琐。
更聪明的做法是直接编写或扩展现有的 ConfigMap 生成单元测试。文档中提到的示例测试(见 pkg/prometheus/promcfg_test.go)正是检查 ScrapeConfigs 生成的字符串与预期文件是否一致——不需要集群,一次 go test 即可完成验证。
运行单元测试
最简单的方式是使用 Makefile 目标:
make test-unit
也可以针对特定包运行:
go test ./pkg/prometheus/server
甚至只跑某个特定函数:
go test -run ^TestPodLabelsAnnotations$ ./pkg/prometheus/server
从 Makefile 的源码可以看到 test-unit 目标实际执行的完整命令:
test-unit: test-prometheus-goldenfiles ## Run unit tests (short mode).
go test -race $(TEST_RUN_ARGS) -short $(pkgs) -count=1 -v
这里有几个值得注意的细节:
-race:启用 Go 竞态检测器,帮助发现并发问题。-short:短模式,跳过耗时的长测试。-count=1:禁用测试缓存,确保每次都真正执行。$(TEST_RUN_ARGS):允许你向go test透传额外参数(例如-run指定测试函数)。- 目标还依赖
test-prometheus-goldenfiles,即每次跑单元测试前都会自动用promtool校验所有 Prometheus Golden 文件(详见下文)。
对应的长模式目标为:
test-long: test-prometheus-goldenfiles ## Run all tests (including long-running).
go test $(TEST_RUN_ARGS) $(pkgs) -count=1 -v
区别在于 test-long 不传 -short,会执行包括长时间运行测试在内的全部用例。
Golden 文件:多行字符串比较的利器
什么是 Golden 文件
Golden 文件是纯文本文档,专门用于校验冗长的字符串输出。在 Prometheus Operator 中,最常见的用途是:把 Go 结构体 marshal 成 YAML 形式的 Prometheus 配置,再与一份静态参考文件比对,确认二者一致。它避免了把上百行的静态配置硬编码进测试代码,保持了测试的可读性。
以 pkg/prometheus/promcfg_test.go 中的测试为例:该测试为每个用例生成 Prometheus 配置(单条用例很容易超过 100 行),然后与 Golden 文件比对。如果没有 Golden 文件,同样的测试大约需要 1000 行硬编码字符串;而有了 Golden 文件,测试代码只需约 150 行,就能维护大量多行字符串比较。
Golden 文件在源码中的实际用法
在 pkg/prometheus/promcfg_test.go 中,Golden 断言普遍采用 gotest.tools/v3/golden 库,典型调用形如:
golden.Assert(t, string(cfg), tc.Golden)
即把生成的配置字符串 cfg 与对应名称的 Golden 文件内容做严格比对。该测试文件全篇有上百处这样的断言(覆盖 ScrapeConfig、ServiceMonitor、PodMonitor、Probe、RemoteWrite、TSDB 配置等各类配置生成场景),每一个 .golden 文件都代表一种期望的 Prometheus 配置形态。
更新 Golden 文件
当你的改动需要同时更新多个 Golden 文件时(例如给已有配置新增一个必填字段),无需手工逐个修改,直接运行:
make test-unit-update-golden
该目标调用 scripts/update-golden-files.sh 完成批量更新。脚本的实现思路很巧妙:
- 用
go list ./...列出项目中所有包; - 通过
go list -f '{{join .TestImports "\n"}}{{"\n"}}{{join .XTestImports "\n"}}'检查每个包的外部测试导入中是否包含gotest.tools/v3/golden依赖; - 只对包含该依赖的包执行
go test "$pkg" -update -timeout 30s,自动重写其 Golden 文件。
注意:-update 标志只有在测试代码确实调用了 golden.Assert 并传入了 -update 参数时才会生效,普通包不会被动到。
用 promtool 校验 Prometheus Golden 文件
pkg/prometheus/testdata/ 下存放着大量 Prometheus 配置的 Golden 文件(本仓库中约有 500 余个 .golden 文件,覆盖各种功能开关与 Prometheus 版本组合,例如 RemoteWriteConfig_v2.43.0_ProxyConfig.golden、TopologySharding_ServiceMonitor_6shards_3zones.golden 等)。这些文件不仅是期望输出,更应该是语法合法的 Prometheus 配置。
因此项目引入了自动校验机制:使用 promtool check config --syntax-only 逐一对这些 Golden 文件做语法检查。该机制:
- 作为
make test-unit和make test-long的依赖步骤自动执行(见 Makefile); - 一旦某个 Golden 文件包含非法配置,直接导致构建失败;
- 使用的
promtool版本取自 Prometheus 兼容性矩阵中的最新兼容版本。
如需手动单独运行校验:
make test-prometheus-goldenfiles
其底层命令为:
$(PROMTOOL_BINARY) check config --syntax-only pkg/prometheus/testdata/*.golden
注意:pkg/prometheus/testdata/ 下的子目录(如 input/、legacy-versions/、native-histograms/、v2/ 等)被排除在校验之外,因为这些目录里存放的是配置片段或历史遗留配置,本身不构成完整可校验的 Prometheus 配置文件。
端到端测试(E2E tests)
有些行为必须在真实运行的 Kubernetes 集群中才能验证,例如 Operator 对集群资源变化的事件驱动响应、多个控制器之间的协同、升级路径等。这时就需要端到端测试。
准备一个本地 Kubernetes 集群
运行 E2E 测试前,先要启动一个 Kubernetes 集群。项目推荐使用 KinD,因为它轻量(在小笔记本上也能跑)且与项目 CI 使用的环境一致;MiniKube 也是可选项。
手动测试:用 run-external.sh 快速拉起本地 Operator
对于手动测试,可以使用工具脚本 scripts/run-external.sh。它会检查所有前置条件,并在你的 Kind 集群上运行本地构建版本的 Prometheus Operator:
./scripts/run-external.sh -c
其中 -c(--use-default-context)表示使用当前 kubectl context 运行 Operator。脚本内部会依次:应用 CRD 并等待其 Established(kubectl apply --server-side --force-conflicts + kubectl wait --for=condition=Established crds --all)、读取当前 context 的 API Server 与证书信息、以本地进程方式拉起 Operator,并在退出时清理临时文件。
构建镜像并加载进集群
运行自动化 E2E 测试之前,需要先把项目镜像构建好并加载进本地集群。
使用 Docker + Kind
KIND_CONTEXT=e2e make test-e2e-images
从 Makefile 的实现可以看到,该目标会构建 prometheus-operator、prometheus-config-reloader、admission-webhook 三个镜像,并通过 kind load docker-image -n $(KIND_CONTEXT) ... 依次加载进指定 context 的 Kind 集群。
使用 Podman + Kind(macOS)
在 macOS 上使用 podman 运行 Kind 时,建议创建具备 4 个 CPU 和 8 GiB 内存 的 podman machine——资源不足可能导致 E2E 测试因集群资源耗尽而失败:
podman machine init --cpus=4 --memory=8192 --rootful --now
随后加载镜像:
CONTAINER_CLI=podman KIND_CONTEXT=e2e make test-e2e-images
当 CONTAINER_CLI=podman 时,Makefile 会改用 podman save 导出镜像 tar 包,再用 kind load image-archive 加载,避免 Docker/Podman 存储驱动不兼容的问题。
运行自动化 E2E 测试
make test-e2e
make test-e2e 会运行完整的端到端测试套件,与 Pull Request 流水线中跑的是同一套测试,覆盖所有控制器的全部功能需求(Prometheus、Alertmanager、Thanos Ruler、升级路径、Feature Gate 等)。其实际命令为(见 Makefile):
test-e2e: KUBECONFIG?=$(HOME)/.kube/config
test-e2e: test/instrumented-sample-app/certs/cert.pem test/instrumented-sample-app/certs/key.pem
go test -timeout 120m -v ./test/e2e/ $(TEST_RUN_ARGS) --kubeconfig=$(KUBECONFIG) --operator-image=$(IMAGE_OPERATOR):$(TAG) -count=1
值得注意的实现细节:
- 默认从
$HOME/.kube/config读取 kubeconfig,可通过KUBECONFIG环境变量覆盖; - 通过
--operator-image指定要部署的 Operator 镜像; - 测试前会先为
test/instrumented-sample-app生成证书(用于采集带 TLS 的示例应用指标); -timeout 120m给出了整个套件的 120 分钟超时上限;- 测试代码位于 test/e2e/ 目录,包含 prometheus_test.go、alertmanager_test.go、thanosruler_test.go、prometheusagent_test.go、upgradepath_test.go 等针对各控制器的用例文件。
不过,做一次贡献通常很少会同时影响所有控制器。完整套件非常耗时,开发阶段更明智的做法是只运行与改动相关的测试。
跳过不需要的测试套件
E2E 测试支持通过环境变量按套件跳过。示例见 test/e2e/main_test.go,其中每个套件都有对应的 skip 辅助函数,例如:
func skipPrometheusTests(t *testing.T) {
if os.Getenv("EXCLUDE_PROMETHEUS_TESTS") != "" {
t.Skip("Skipping Prometheus tests")
}
}
环境变量与套件的对应关系包括:EXCLUDE_ALERTMANAGER_TESTS、EXCLUDE_PROMETHEUS_TESTS、EXCLUDE_PROMETHEUS_ALL_NS_TESTS、EXCLUDE_THANOSRULER_TESTS、EXCLUDE_OPERATOR_UPGRADE_TESTS、EXCLUDE_PROMETHEUS_UPGRADE_TESTS、EXCLUDE_FEATURE_GATED_TESTS。CI 中会跑全部测试,但开发时跳过无关套件可以显著缩短反馈周期。
Makefile 已把"跳过无关套件"封装成现成的目标(见 Makefile),底层都是通过设置一组 EXCLUDE_*_TESTS=exclude 环境变量只保留目标套件:
make test-e2e-alertmanager—— 只跑 Alertmanager 相关测试make test-e2e-thanos-ruler—— 只跑 Thanos-Ruler 相关测试make test-e2e-prometheus—— 跑 Prometheus 测试(受限命名空间权限场景)make test-e2e-prometheus-all-namespaces—— 跑常规 Prometheus 测试make test-e2e-operator-upgrade—— 验证由上一个版本 Prometheus Operator 管理的监控栈在升级到当前版本后仍能正常工作make test-e2e-prometheus-upgrade—— 验证一系列 Prometheus 版本可以依次顺序升级make test-e2e-feature-gates—— 验证 Feature Gate 背后的功能
只运行单个端到端测试
即使按套件拆分,单个套件也可能需要几十分钟。调试特定用例时,可以借助 TEST_RUN_ARGS 只运行这一个用例。例如,以下命令只运行 TestPrometheusRuleCRDValidation/valid-rule-names 子测试:
TEST_RUN_ARGS="-run TestPrometheusRuleCRDValidation/valid-rule-names" make test-e2e-prometheus
TEST_RUN_ARGS 会被透传到 go test 的 -run 参数(从 Makefile 的命令行可见),Go 的正则匹配机制允许精确锁定某个顶层测试及其子测试。
测试代码结构速览
以下关键路径可以帮助你在仓库中快速定位各类测试资产:
| 用途 | 路径 |
|---|---|
| Prometheus 配置生成单元测试 | pkg/prometheus/promcfg_test.go |
| Prometheus 配置 Golden 文件(含子目录) | pkg/prometheus/testdata/ |
| 单元测试 Golden 文件批量更新脚本 | scripts/update-golden-files.sh |
| E2E 测试入口(环境变量跳过、TestMain) | test/e2e/main_test.go |
| E2E 测试用例集合 | test/e2e/ |
| 测试辅助框架(部署、断言、资源封装) | test/framework/ |
| 手动拉起本地 Operator 的脚本 | scripts/run-external.sh |
| 全部测试目标定义 | Makefile |
小结:按场景选择正确的测试策略
- 改动局限于某个函数或配置生成逻辑:优先写/改单元测试,用
go test -run ^TestXxx$ ./pkg/...获得秒级反馈;涉及配置输出变更时,用make test-unit-update-golden批量更新 Golden 文件,并确保make test-prometheus-goldenfiles的 promtool 语法校验通过。 - 改动涉及集群行为或控制器协同:启动 KinD 集群,用
KIND_CONTEXT=e2e make test-e2e-images加载镜像,再用对应的make test-e2e-<组件>目标运行定向套件,配合TEST_RUN_ARGS="-run ..."精确调试单个用例。 - 合并前最终验证:完整执行
make test(单元 + 长测试 + E2E),这与 CI 流水线的覆盖范围保持一致。
这套"单元测试打底、Golden 文件校验配置、E2E 验证真实集群行为"的阶梯式测试体系,正是 Prometheus Operator 能够在持续演进中保持高度可靠性的基石。掌握本文中的运行命令与源码细节,你就拥有了独立于 CI 的完整本地开发验证闭环。