Docker Engine(Moby)代码测试指南:单元测试、API 集成测试与测试套件运行实践

原创2026-10-13 22:50:161,893 阅读
文章标签:容器运行时云原生

Docker Engine(Moby)代码测试指南:单元测试、API 集成测试与测试套件运行实践

本篇技术指南基于 Docker Engine(Moby 内核)仓库的官方测试文档(components/engine/TESTING.md)展开,全面讲解其两套(外加一套遗留)测试体系的定位与编写规范、make test-unit / make test-integration 等测试目标的使用方法,以及 TESTDIRS、TESTFLAGS、TEST_FILTER、GO_VERSION 等关键环境变量的实战用法。读完本文,你将能够按照 Moby 社区标准为 Docker Engine 编写单元测试与 API 集成测试,并熟练驱动仓库内的测试基础设施完成验证。


一、测试套件总览:三套测试体系的分工与定位

Moby 代码库中包含两套现行测试套件,以及一套已弃用的遗留测试套件。理解它们的分工是正确编写与运行测试的前提。

测试套件 目录位置 测试类型 状态
单元测试(Unit tests) 与被测包同目录(如 pkg/、daemon/ 内部) 使用标准 go test 与 gotest.tools/assert 断言 现行
API 集成测试(API integration tests) integration/<component>/,如 container、image、volume 使用标准 go test 与 gotest.tools/assert 断言,通过 HTTP 请求真实 API 端点 现行
遗留测试套件(integration-cli) integration-cli/ 基于 CLI 命令的端到端测试 已弃用

1. 单元测试:快速、隔离、只测自己的包

单元测试与它测试的 Go 包放在同一目录中,使用 go test 直接驱动。其核心约束是:必须快速运行,并且只测试自身包,不依赖外部守护进程或网络环境。例如 pkg/ 下的选项解析、镜像处理等纯逻辑代码,都以单元测试为第一道防线。

2. API 集成测试:真实调用 HTTP 端点并校验守护进程状态

集成测试位于 integration/<component>/ 目录下,component 对应 API 的资源维度:container、image、volume、network、service、secret、plugin、session、system、distribution 等(见 components/engine/integration/ 目录结构)。这些测试向真实运行的 dockerd 发起 HTTP 请求,随后同时校验 HTTP 响应本身以及调用完成后守护进程的内部状态。

例如 integration/container/container_test.go 中的 TestContainerInvalidJSON,向 /containers/foobar/exec 与 /exec/foobar/start 两个端点发送非法 JSON 与空请求体,断言返回 http.StatusBadRequest,并校验响应正文中是否包含 Go 解析器产生的错误片段——这正是“HTTP 响应 + 守护进程行为”双重校验的典型示范。测试通过 testutil/request 包的 request.Post / request.Get / request.Delete 等辅助函数发出请求,底层根据 DOCKER_HOST 环境变量决定连接 unix socket 还是 TCP(components/engine/testutil/request/request.go)。

3. 遗留套件 integration-cli:已弃用,不再新增

integration-cli/ 是历史遗留的 CLI 级测试套件,官方明确声明:不再为其添加任何新测试;凡是需要更新的既有测试,都应迁移到单元测试套件或新的 API 集成测试套件。仓库中的 hack/make/test-integration-cli 脚本第一行即输出:

WARNING: test-integration-cli is DEPRECATED. Use test-integration.

并直接将请求转发给 test-integration。在提交新代码时,向 integration-cli 添加的新测试会被 CI 直接拒绝。


二、编写新测试:面向不同改动类型的规范

文档针对代码改动的常见类型给出了明确的测试编写策略。

1. 新功能:单元测试打底,接口设计为可注入依赖

新代码应当被单元测试覆盖。如果一段代码难以用单元测试测试,说明它应该被重构以提升可复用性与可维护性——例如优先接受“非导出的接口”(unexported interfaces)而非具体结构体(structs),这样依赖项可以被注入 fake 实现,测试无需真实外部服务。

对于新功能,单元测试的覆盖原则是:业务逻辑全覆盖、错误分支尽可能在单测层处理。从 hack/test/unit 脚本可以看到,单元测试默认排除 /vendor/ 与 /integration 路径(exclude_paths='/vendor/|/integration'),从机制上保证了单元测试与集成测试的边界。

2. 新 API 端点 vs. 新 API 字段:测试粒度的关键决策

文档给出了非常具体的粒度规范:

  • 如果新功能包含一个全新的 API 端点,则应新增一个 API 集成测试,覆盖该端点的成功路径;
  • 如果新功能没有引入全新端点,只往现有端点增加新字段,则应当把新字段的断言补充到该端点已有的测试中,不要为每一个新字段或每一个 API 错误分支都新建集成测试;
  • 错误分支一律交由单元测试处理,集成测试只在成功路径上验证契约。

这一原则避免了集成测试无限膨胀,同时把昂贵、依赖真实守护进程的验证控制在最小必要范围内。

3. Bug 修复:先写一个能复现 bug 的单元测试

修复 bug 时必须附带一个能够复现该 bug 的单元测试用例。这是对回归防护的最低要求。在此基础上,如果该 bug 涉及某个 API 端点的行为,也可以在该端点的既有集成测试中补充新的断言,确保修复同时得到单元层与集成层的验证。

4. 新增集成测试的落点

所有新的集成测试都应落在 integration/ 目录下。仓库中 integration/ 之下按组件分子目录(components/engine/integration/),每个组件包内含 main_test.go,负责建立测试环境。例如 integration/container/main_test.go 的 TestMain 通过 environment.New() 从环境变量构造 API 客户端、拉取冻结的测试镜像,并提供 setupTest 辅助函数在每个用例前后执行环境保护与清理。


三、集成测试的环境考虑:用 skip.If 处理平台差异

运行集成测试时,测试环境千差万别:守护进程可能在本地也可能在远端,宿主可能是 Linux、Windows 或不同 CPU 架构,还可能启用 rootless、用户命名空间等特性。Moby 提供了 gotest.tools/skip 包的 skip.If 让测试按条件跳过。

完整的测试环境条件定义位于 components/engine/testutil/environment/environment.go。其中 Execution 结构体封装了当前测试执行与守护进程的关键信息,包括:

  • IsLocalDaemon() / IsRemoteDaemon():守护进程是否与测试进程在同一宿主(通过 DOCKER_REMOTE_DAEMON 环境变量判定,见 environment.go);
  • IsRootless():是否启用 rootless 模式;
  • IsUserNamespace():是否启用用户命名空间重映射;
  • DaemonAPIVersion():守护进程协商后的 API 版本;
  • OSType / PlatformDefaults:守护进程的操作系统类型与平台默认值。

典型场景:当测试需要与本机同一个守护进程交互(例如需要操作本地 daemon 配置或网络命名空间)时,应在测试代码中先做如下检查:

skip.If(t, testEnv.IsRemoteDaemon())
// your integration test code

一旦检测到远端守护进程(DOCKER_REMOTE_DAEMON 被设置),该测试就会被跳过。这在仓库中随处可见,例如 integration/build/build_cgroupns_linux_test.go 与 integration/container/pidmode_linux_test.go 都以此守卫 cgroup、PID 模式等只能在本机 daemon 上验证的用例。

除 daemon 位置外,还常用以下条件组合:

这样的条件跳过机制让同一套测试可以安全地在本地、CI、不同架构与不同宿主拓扑下运行。


四、运行单元测试:make test-unit 与 TESTDIRS/TESTFLAGS

1. 基本命令

在引擎根目录(components/engine/)下运行:

make test-unit

或者在 BINDDIR=. make shell 进入的构建容器(或配置完备的本地环境)中运行:

hack/test/unit

make test-unit 目标在 Makefile 中的定义是 $(DOCKER_RUN_DOCKER) hack/test/unit(见 components/engine/Makefile),即它会先构建 docker-dev 开发容器镜像,再在容器内执行单元测试脚本。

2. 过滤测试子集的两个环境变量

hack/test/unit 脚本(components/engine/hack/test/unit)支持两个核心环境变量:

  • TESTDIRS:指定要测试的包目录列表,默认值为 ./...(即整个仓库)。例如只测试终端工具包:

    TESTDIRS='./pkg/term' hack/test/unit
    

    脚本内部会执行 go list $TESTDIRS,并自动排除 /vendor/ 与 /integration 路径,确保单元测试不污染集成测试。

  • TESTFLAGS:透传给 go test 的额外参数。要只运行匹配某个名称前缀的测试,使用:

    TESTFLAGS='-v -test.run TestBuild' hack/test/unit
    

3. 脚本内部的细节

hack/test/unit 的底层逻辑有几个值得注意的实现细节:

  • 编译标签:脚本以 -tags 'netgo seccomp libdm_no_deferred_remove' 构建测试二进制;
  • 超时控制:自动追加 -test.timeout=${TIMEOUT:-5m},默认 5 分钟;
  • 覆盖率:通过 -cover -coverprofile=bundles/profile.out -covermode=atomic 生成覆盖率报告;
  • libnetwork 特殊处理:/libnetwork 下的测试会调用 iptables,不能并行运行,因此脚本将其单独列出并以 -p=1 串行执行,且会预检 docker-proxy 二进制是否存在(见 components/engine/hack/test/unit);
  • 报告产物:使用 gotestsum 生成 bundles/go-test-report.json 与 bundles/junit-report.xml,便于 CI 汇总展示。

五、运行集成测试:make test-integration 与精细控制

1. 基本命令

make test-integration

该 make 目标会同时运行两套套件:integration(API 集成测试)与 integration-cli(遗留 CLI 套件)。底层执行链是 make test-integration → hack/make.sh dynbinary test-integration → hack/make/test-integration 脚本。

test-integration 脚本的执行流程(见 components/engine/hack/make/test-integration)体现了端到端的完整性:

  1. build_test_suite_binaries:为每个集成测试包 go test -c 预编译 test.main 二进制;
  2. 启动专用测试守护进程(.integration-daemon-start / .integration-daemon-setup);
  3. 运行各套件并记录退出码;
  4. 无论成败都执行 .integration-daemon-stop 清理守护进程、清理测试二进制;
  5. 通过 error_on_leaked_containerd_shims 检测是否有遗留的 containerd-shim 进程——如有则输出警告并以失败退出(相关实现见 components/engine/hack/make/.integration-test-helpers)。

2. 指定集成测试目录

通过 TEST_INTEGRATION_DIR 环境变量指定要构建并运行的集成测试目录列表:

TEST_INTEGRATION_DIR='./integration/container ./integration/image' make test-integration

未设置时,脚本会通过 go list -test 自动枚举 ./integration/... 下所有含测试的目录(见 .integration-test-helpers)。

3. 跳过某一套件

分别用 TEST_SKIP_INTEGRATION 和 TEST_SKIP_INTEGRATION_CLI 环境变量(设置任意非空值即生效)显式跳过 API 集成套件或 CLI 遗留套件。若两者都设置,test-integration 会直接输出跳过信息并退出(见 hack/make/test-integration 与 Makefile 中的对应分支)。

4. 各套件专属的 go test 参数

  • TESTFLAGS_INTEGRATION:仅传给 integration 套件的标志;
  • TESTFLAGS_INTEGRATION_CLI:仅传给 integration-cli 套件的标志。

这些变量在 Makefile 的 DOCKER_ENVS 中被显式透传进构建容器(见 components/engine/Makefile)。

5. 最常用的单变量过滤:TEST_FILTER

如果只关心指定测试过滤条件,无需手工组合上面几个变量,直接设置 TEST_FILTER 即可。它最终会被直接传给 go test -run(对 API 集成套件)或 go test -check-f(对 CLI 遗留套件),并自动推导设置上述相关环境变量。setup_integration_test_filter 函数会扫描 integration*/ 下所有 *_test.go 中匹配该名称的 func Test*,从而自动圈定需要构建的目录并跳过无关套件(见 .integration-test-helpers)。

例如,想只运行名称以 TestBuild 开头的 CLI 级测试:

TESTFLAGS='-test.run TestDockerSuite/TestBuild*' ./hack/make.sh binary test-integration

6. 其他相关目标

  • make test-integration-flaky:对本次改动新增的集成测试做压力验证。脚本用 git diff 筛选出 integration/*_test.go 中新增的 func Test*,设置 TEST_REPEAT=5 与 -test.count 5,让每个新测试在同一守护进程下连跑 5 次、并重复整个套件 5 次,总计每个测试 25 次执行,用于提前暴露偶发失败(见 hack/make/test-integration-flaky)。
  • make test-integration-shell:启动测试守护进程后进入交互式 shell,供手动调试集成测试(见 hack/make/test-integration-shell)。
  • make test:聚合目标,会先跑单元测试,再依次执行 dynbinary、cross、test-integration 与 test-docker-py(见 Makefile)。

7. 测试守护进程的环境隔离

test_env 函数使用 env -i 严格控制注入测试进程的环境变量白名单(.integration-test-helpers),只放行 DOCKER_HOST、DOCKER_API_VERSION、DOCKER_GRAPHDRIVER、DOCKER_ROOTLESS、DOCKER_REMAP_ROOT、DOCKER_REMOTE_DAEMON、TEST_CLIENT_BINARY 等关键变量。这保证了测试在可复现的纯净环境中运行,宿主上无关的环境变量不会泄漏进测试进程。另外,set_platform_timeout 会根据平台自动设定套件超时:arm/arm64 默认 10 分钟、Windows 默认 8 分钟、其余平台默认 5 分钟,且 TEST_REPEAT 大于 1 时超时会按重复次数自动放大。


六、Go 版本控制:GO_VERSION 变量

构建与测试使用的 Go 工具链版本可以通过 GO_VERSION 变量覆盖:

make GO_VERSION=1.12.8 test

引擎的 Dockerfile 以 ARG GO_VERSION=1.17.4 定义默认版本,并据此选取 golang:${GO_VERSION}-${BASE_DEBIAN_DISTRO} 基础镜像(见 components/engine/Dockerfile)。这意味着测试运行在 Docker 构建出的开发容器内,切换 GO_VERSION 实质上是切换该容器的基础镜像层。需要说明的是:仓库当前代码与测试脚本基于较新的 Go 工具链演进而来,示例中的 1.12.8 仅为文档演示用法,实际使用时应选择一个与当前仓库构建脚本兼容的 Go 版本。


七、小结:Moby 测试文化的三条主线

纵观整份测试文档与仓库实现,可以提炼出 Moby 代码测试文化的三条主线:

  1. 分层明确:单元测试负责快速、隔离地验证业务逻辑与错误分支;API 集成测试负责验证端到端的 HTTP 契约与守护进程状态;遗留的 integration-cli 套件只做存量维护,不新增用例。
  2. 以可测试性驱动设计:新代码优先暴露“非导出接口”以便注入 fake,凡是难以单测的代码都应先重构——测试的难易程度是设计质量的晴雨表。
  3. 环境感知的跳过策略:借助 gotest.tools/skip 与 testutil/environment 提供的环境探针,让同一套测试在不同宿主、架构、版本和运行模式下自动适配,既保证覆盖又避免误报。

掌握这些规范后,无论是为 Docker Engine 提交功能、修复 bug,还是在本地或 CI 中驱动其庞大的测试基础设施,你都能循着清晰的路径开展工作。相关的全部测试入口与实现均位于引擎仓库的 hack/ 与 testutil/ 目录,可随时深入阅读。

登录后查看全文
docker-ce