首页
/ Moby 测试体系完全指南：测试套件划分、编写规范与 make 测试命令实战

Moby 测试体系完全指南：测试套件划分、编写规范与 make 测试命令实战

2026-09-03 16:11:11作者：余洋婵Anita
moby
The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems
项目地址：https://gitcode.com/GitHub_Trending/mo/moby

Moby（Docker 引擎的开源仓库）为贡献者提供了一套清晰分层的测试体系：快速的单元测试（unit tests）、面向 HTTP API 的集成测试（integration/），以及已经弃用的遗留套件（integration-cli/）。本文基于仓库根目录的 TESTING.md 展开，结合 Makefile、hack/test/unit、hack/make/test-integration 等脚本源码，系统讲解 Moby 的测试分层原则、新测试编写规范、集成测试环境判断技巧，以及如何用 make 目标和环境变量精确控制测试的运行范围，帮助你在修改 Moby 代码后能够正确选择并运行对应的测试套件。

一、Moby 的测试套件分层

Moby 将测试划分为两套正式套件加一套遗留套件：

套件 位置 工具与断言 定位
单元测试（Unit tests） 与源码同包 go test + gotest.tools/v3/assert 要求快速，只测试自身所在包
API 集成测试 ./integration/<component>（container、image、volume 等） go test + gotest.tools/v3/assert 向 API 端点发起真实 HTTP 请求，校验 HTTP 响应与调用后的 daemon 状态
遗留集成测试（已弃用） integration-cli/ 旧框架 不再接受新测试，需要更新的旧测试应迁移到单元测试或新 API 集成测试套件

从仓库结构看，integration/ 下按组件划分子目录，例如 integration/container/、integration/image/、integration/volume/ 等，每个目录下是对应组件的端到端测试；而 integration/internal/ 存放跨组件共享的测试辅助代码（容器/镜像构建工具、环境要求判断、终端输出校验等）。integration-cli/ 虽仍存在大量 docker_*_test.go 文件，但按 TESTING.md 的明确规定，它已被标记为 deprecated，新提交到该目录的测试会被 CI 直接拒绝。

二、编写新测试的规范

2.1 新功能（New Features）的测试要求

TESTING.md 对新功能提出的核心原则是：新增代码首先应由单元测试覆盖。如果一段代码难以用单元测试测试，这恰恰是它需要重构的信号——文档建议将依赖从具体结构体改为非导出接口（unexported interfaces），以便在测试中注入 fake 实现。

集成测试的边界同样被严格限定：

  • 若新功能引入了全新的 API 端点，则必须新增一个 API 集成测试，覆盖该端点的成功路径（success case）；
  • 若只是为已有端点新增 API 字段，应把新字段加到该端点的现有集成测试中，而不是新建测试；
  • 不要为每一个新 API 字段或 API 错误分支单独添加集成测试——错误分支（error cases）应由单元测试负责。

2.2 Bug 修复（Bug Fixes）的测试要求

  • 修复必须附带一个实际触发该 bug 路径的单元测试用例；
  • 如果 bug 涉及某个 API 端点的行为，可以在该端点的现有集成测试中追加新的断言（new assertions），而非新写一个集成测试。

2.3 新集成测试必须放在 integration/ 下

再次强调：integration-cli 中的新测试会被 CI 拒绝，所有新集成测试都应实现在 integration/ 目录下。

2.4 集成测试的环境条件判断：skip.If

集成测试运行环境千差万别（本地 daemon、远程 daemon、rootless 模式、Windows 等），因此新增或修改 integration/ 下的测试时必须考虑环境适配。TESTING.md 给出的做法是使用 gotest.tools/v3/skip 包的 skip.If 让测试按条件运行。官方示例：

package example

import (
	"testing"

	"gotest.tools/v3/skip"
)

func TestSomething(t *testing.T) {
	skip.If(t, testEnv.IsRemoteDaemon(), "test requires a local daemon")

	// your integration test code
}

当检测到远程 daemon 时测试会被跳过。所有可用的环境条件定义在 internal/testutil/environment/environment.go 中。从该源码可以看到 Execution 类型提供了若干条件判断方法，例如：

  • IsRemoteDaemon()——被测 daemon 是否位于另一台主机（源码注释：“true if the daemon under test is on different host”）；
  • IsRootless()——是否启用了 rootless 模式；
  • RuntimeIsWindowsContainerd()——Windows 上是否使用 containerd 运行时。

仓库内的真实用法可参考 integration/build/build_cgroupns_linux_test.go：

skip.If(t, testEnv.DaemonInfo.OSType != "linux")
skip.If(t, testEnv.IsRemoteDaemon())
skip.If(t, !requirement.CgroupNamespacesEnabled())

这展示了典型的三层过滤：操作系统类型 → daemon 位置 → 特性能力（requirement 包来自 integration/internal/requirement/）。

三、运行测试：make 目标与环境变量

3.1 单元测试：make test-unit

基本用法：

make test-unit

或者在 make shell 启动的容器 / 配置好的环境中直接运行 hack/test/unit。

两个可控制测试子集的环境变量：

  • TESTDIRS——要测试的目录列表，默认 ./...；
  • TESTFLAGS——传给 go test 的额外参数；按名称模式过滤时写 TESTFLAGS="-test.run TestNameOrPrefix"。

Makefile 中的对应目标确认了这条调用链：

.PHONY: test-unit
test-unit: build ## run the unit tests
	$(DOCKER_RUN_DOCKER) hack/test/unit

即 test-unit 先构建 docker-dev 镜像，再在容器内执行 hack/test/unit。

3.2 集成测试：make test-integration

基本用法：

make test-integration

该 make 目标会同时运行 “integration” 与 “integration-cli” 两套套件。相关控制变量：

环境变量 作用
TEST_INTEGRATION_DIR 指定要构建和运行哪些集成测试目录
TEST_SKIP_INTEGRATION 设置任意值即跳过 integration 套件
TEST_SKIP_INTEGRATION_CLI 设置任意值即跳过 integration-cli 套件
TESTFLAGS_INTEGRATION / TESTFLAGS_INTEGRATION_CLI 分别为两套套件传递专属 flag
TEST_FILTER 测试过滤器，直接透传给 go test -run（integration-cli 对应 go test -check-f），并自动联动设置上述其它变量

Makefile 展示了跳过逻辑的实现：当 TEST_SKIP_INTEGRATION 和 TEST_SKIP_INTEGRATION_CLI 同时非空时，目标直接打印 “Both integrations suites skipped per environment variables” 并退出；否则进入容器执行 hack/make.sh dynbinary test-integration。而 hack/make/test-integration 脚本则负责实际的测试编排：构建测试二进制（build_test_suite_binaries）→ 启动被测 daemon（bundle .integration-daemon-start）→ 循环执行 run_test_integration → 无论成败都执行 .integration-daemon-stop 与二进制清理，并将全过程输出追加到 test.log。

此外 Makefile 还提供 test-integration-flaky 目标，用于对新集成测试做压力重跑，排查不稳定（flaky）用例；Makefile 的总目标 make test 则会串联 build、test-unit、test-integration 与 test-docker-py。

3.3 指定 Go 版本

通过 GO_VERSION 变量可以切换用于构建被测试代码的 Go 版本，例如：

make GO_VERSION=1.24.8 test

四、源码纵深：hack/test/unit 的测试编排细节

hack/test/unit 脚本揭示了 make test-unit 背后的关键工程细节，这些细节直接影响你使用 TESTDIRS / TESTFLAGS 时的行为：

  1. api 与 client 是独立 Go 模块，单独执行。脚本开头（hack/test/unit#L26-L54）会判断 TESTDIRS 是否命中 ./api 或 ./client，命中后分别进入对应模块目录，用 gotestsum ... -mod=readonly 单独运行。原因是仓库存在 vendor/ 目录，若不排除 vendor 模式，api/client 模块的测试文件可能不被识别；注释中特别引用了 Go 官方文档对 -mod=readonly 的解释——忽略 vendor 目录，并在 go.mod 需要更新时报错。
  2. 默认排除 vendor 与 integration。主模块的包列表来自 go list "$TESTDIRS" | grep -vE '(/vendor/|/integration)'（hack/test/unit#L91-L95），确保 make test-unit 不会误跑集成测试。
  3. libnetwork 强制串行执行。由于 libnetwork 测试会调用 iptables，脚本将其拆出并用 -p=1 顺序执行（hack/test/unit#L124-L135）。
  4. flaky 测试单独重跑。第一轮会用 -skip=TestFlaky.* 跳过 flaky 用例，结束后再用 --rerun-fails=4 对 TestFlaky.* 单独重跑（hack/test/unit#L137-L148）；如果你在 TESTFLAGS 中显式传了 -run，则不会进行这轮单独的 flaky 重跑。
  5. 统一使用 gotestsum 产出报告。各模块分别输出 JSON/JUnit 报告到 bundles/ 目录（如 bundles/junit-report.xml、bundles/coverage.out），并固定 -test.timeout=${TIMEOUT:-5m} 超时（hack/test/unit#L16）。
  6. 构建标签固定为 netgo journald（BUILDFLAGS），这与官方构建保持一致。

对于需要 docker-proxy 的 libnetwork/drivers/bridge 包，脚本还会自动调用 hack/make.sh binary-proxy install-proxy 补装依赖（hack/test/unit#L97-L100）。

五、实践清单：按场景选择测试命令

结合上述机制，日常开发中的典型用法如下（均相对仓库根目录）：

# 全量单元测试
make test-unit

# 只测某包（等价于 hack/test/unit 的 TESTDIRS）
make TESTDIRS='./daemon/...' test-unit

# 按名称模式过滤
make TESTFLAGS="-test.run TestContainerCreate" test-unit

# 只跑新集成测试套件，跳过遗留套件
make TEST_SKIP_INTEGRATION_CLI=1 test-integration

# 只跑 integration 下指定组件目录
make TEST_INTEGRATION_DIR="container image" test-integration

# 用过滤器直接筛测试名
make TEST_FILTER="TestLogs" test-integration

# 换 Go 版本跑完整测试
make GO_VERSION=1.24.8 test

适用前提与限制需要留意：这些 make 目标都依赖 build（构建 docker-dev 镜像）并在容器内执行，因此宿主机需要先具备可用的 Docker；TEST_FILTER 对 integration-cli 透传的是 -check-f 而非 -run，两套套件的行为差异在 TESTING.md 中已明确说明。

六、小结

Moby 的测试体系可以归纳为三条主线：

  • 分层清晰：单元测试追求快速且只测本包；集成测试面向真实 daemon 走 HTTP 协议；遗留套件 integration-cli/ 冻结不再扩张（TESTING.md）。
  • 编写有章法：新功能必须有单测覆盖、仅全新 API 端点才新增集成测试、错误分支归单元测试；集成测试用 skip.If + internal/testutil/environment/environment.go 适配环境（TESTING.md）。
  • 运行可控：make test-unit / make test-integration 配合 TESTDIRS、TESTFLAGS、TEST_INTEGRATION_DIR、TEST_SKIP_INTEGRATION*、TEST_FILTER、GO_VERSION 等变量精确控制范围（Makefile），底层由 hack/test/unit 与 hack/make/test-integration 完成多模块、多套件的自动化编排。
moby
The Moby Project - a collaborative project for the container ecosystem to assemble container-based systems
项目地址：https://gitcode.com/GitHub_Trending/mo/moby
登录后查看全文

相关内容推荐

1 Moby 测试体系实战指南：从单元测试到集成测试的完整验证流程（docs/contributing/test）2 用 Delve 调试 Moby 守护进程：DOCKER_DEBUG 与 DELVE_PORT 在开发容器中的完整调试工作流3 Moby 贡献者 Git 配置实战：Fork 克隆、upstream 远程与 DCO 签名全流程4 Moby 开发环境搭建实战：make shell 进入 Docker-in-Docker 开发容器并验证代码迭代流程5 Moby 开发环境准备指南：Linux/macOS 下配置 Git、Make 与 Docker 的必要软件6 Moby 引擎构建与交叉编译实战：基于 Docker Buildx Bake 的 docker-bake.hcl 全解7 Moby 项目导读：模块化容器引擎的架构原则、Go 模块体系与 docker/docker 迁移指南8 Moby 项目路线图深度解读：containerd 融合、BuildKit 构建器与无特权运行模式的技术演进9 Moby Engine API：基于 Swagger 驱动的 Docker Engine HTTP API 设计、文档生成与开发流程10 Moby TarSum 校验和算法规范解析：tar 层文件系统的确定性校验实现
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

qBittorrent WebAPI 变更日志详解：从 2.11 到 2.16 的 API 演进、破坏性变更与源码级实现剖析Godot Engine 的 thirdparty 目录：第三方库 Vendor 化、补丁管理与更新流程全解析fuels-rs Codec 详解：基于 ABIEncoder / ABIDecoder 的类型序列化与反序列化机制Scrapling MCP Server 详解：把三级 Web 抓取能力接入 AI Agent 的完整实践zx ProcessPromise 完全指南：Promise 语义下的进程控制、管道流与输出格式化Adobe 前端面试题全解：从 front-end-interview-handbook 看 JS 算法、UI 组件与系统设计考点Khoj 自定义 Agent 实现指南：从 Admin 创建、权限模型到 API 与知识绑定机制AutoGPT 前端实战：用 useLatest 稳定回调引用，解决 React Effect 重复执行与闭包过期问题Open Notebook 本地私有化部署实战：Docker Compose + Ollama 构建 100% 离线的 NotebookLM 式研究助手MinerU 壁仞（Biren）加速卡部署指南：从镜像加载到服务启动的完整实操

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
588
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
906
1.83 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.53 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
989
508
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
docsdocs
暂无描述
Markdown
892
5.79 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313