Docker Machine 贡献者开发指南:构建、测试、覆盖率与集成测试全流程
Docker Machine 贡献者开发指南:构建、测试、覆盖率与集成测试全流程
导读
本文是一份面向 Docker Machine(仓库根目录下本项目)贡献者的完整技术指南,覆盖从环境准备、本地与容器化构建、单元测试与静态验证、代码覆盖率报告,到基于 BATS 的集成测试、依赖管理与驱动(Driver)贡献规范的全套开发工作流。读完本文,你将能够独立搭建可复现的开发环境,熟练使用 make 全套目标完成构建与验证,并为该项目提交高质量的代码与测试。
构建环境要求
要构建 Docker Machine 的 docker-machine 二进制,你需要满足以下三项前置条件:
- 一台正在运行的 Docker 守护进程,或者一个 Golang 1.10 开发环境;
bashshell(构建脚本与 Makefile 均依赖 bash 特性);- Make 构建工具。
这三种方式可以二选一:要么把构建放到 Docker 容器内完成(隔离依赖、可复现),要么直接在本地 Go 环境中编译。仓库的 Makefile 通过 USE_CONTAINER 环境变量在这两种模式之间切换:当 USE_CONTAINER != true 时,直接引入 Makefile.inc 与 mk/main.mk 在宿主机上执行目标;否则所有目标都会被吞掉并转发到容器内执行(见 Makefile)。
方式一:基于 Docker 容器的构建
如果本机已安装 Docker,最简单的方式是使用容器构建,只需两步:
$ export USE_CONTAINER=true
$ make build
当 USE_CONTAINER=true 时,Makefile 会把所有 make 目标转发给 script/build_in_container.sh 处理。该脚本的执行流程如下(可对照 script/build_in_container.sh 源码):
- 先删除可能残留的同名构建容器
docker-machine-build-container; - 用仓库根目录的 Dockerfile 构建镜像
docker-machine-build。该镜像基于golang:1.12.9,额外安装了openssh-client、rsync、fuse、sshfs等工具,并预装了golint、goveralls、golang.org/x/tools/cover,工作目录固定在/go/src/github.com/docker/machine; - 通过
docker run以-e方式透传DEBUG、STATIC、VERBOSE、BUILDTAGS、PARALLEL、COVERAGE_DIR、TARGET_OS、TARGET_ARCH、PREFIX等环境变量,在容器内执行你传入的 make 目标; - 构建结束后,用
docker cp把容器内的bin目录拷贝回宿主机。
这种方式的好处是构建环境与宿主机完全隔离,CI 与本地开发行为一致。注意容器内构建产物默认位于容器的工作目录下,脚本结束时会自动同步回仓库的 bin 目录。
方式二:本地 Go 开发环境构建
如果选择本地编译,必须确保源码位于正确的 GOPATH 目录结构下,否则 go build 无法解析导入路径。Docker Machine 的完整导入路径是 github.com/docker/machine。
方式 A:新建专用 GOPATH
$ mkdir docker-machine
$ cd docker-machine
$ export GOPATH="$PWD"
$ go get github.com/docker/machine
$ cd src/github.com/docker/machine
方式 B:复用已有工作区
$ export GOPATH=/home/yourname/work
$ mkdir -p $GOPATH/src/github.com/docker
$ cd $GOPATH/src/github.com/docker && git clone git@github.com:docker/machine.git
$ cd machine
无论哪种方式,只要源码路径正确,直接运行即可构建:
$ make build
从源码看,mk/build.mk 中 build 目标实际执行 go build -o $(PREFIX)/bin/docker-machine ... ./cmd/docker-machine,即入口是 cmd/docker-machine/machine.go 这个 main 包。构建时还会通过 GO_LDFLAGS 注入版本信息:-X $(go list ./version).GitCommit=$(git rev-parse --short HEAD),配合 version/version.go 中 Version = "dev" 与 GitCommit = "HEAD" 两个可注入变量,最终 docker-machine version 输出的就是形如 dev, build <git-short-sha> 的版本串。
构建产物与清理
构建完成后,仓库的 bin 目录下会生成 docker-machine 可执行文件。如果需要清除构建结果,执行:
$ make clean
clean 目标在 mk/main.mk 中定义为 coverage-clean build-clean 的组合,其中 build-clean 会清空 $(PREFIX)/bin/ 下的所有内容(见 mk/build.mk)。另外 make install 目标(见 mk/main.mk)可以把构建好的二进制复制到 /usr/local/bin,便于日常使用。
测试与静态验证
项目沿用标准的 Go 工具链,其中 make test 与 make validate 是两个核心入口。
在运行前,建议先安装 linter:
$ go get -u golang.org/x/lint/golint
make test 会依次执行 dco、fmt、test-short、lint、vet(见 mk/main.mk),即基础验证(DCO 签名、格式检查)+ 项目单元测试。其中:
test-short(mk/test.mk)执行go test -test.short,跳过那些用if testing.Short() { t.Skip(...) }标记的长耗时用例;fmt(mk/validate.mk)检查gofmt -s -l是否有输出(排除vendor/);lint(mk/validate.mk)调用golint ./...,并过滤掉 vendor、cli、部分驱动目录以及 "should have comment" 类提示,避免历史代码噪声干扰。
如果要做更深入的验证(vet、lint)并开启 race 竞争检测,则执行:
$ make validate
validate 在 mk/main.mk 中定义为 dco fmt lint vet test-long,其中 test-long(mk/test.mk)执行 go test -race,同时跑长用例与短用例。官方建议:如果你提交 Pull Request,强烈建议在同一 PR 中为新增或修改的代码附上对应的测试。
仓库各包都配有大量测试,例如命令层测试可见 commands/commands_test.go、commands/create_test.go,驱动层测试可见 drivers/virtualbox/virtualbox_test.go、drivers/digitalocean/digitalocean_test.go,这些可以作为编写测试的参考范例。
代码覆盖率报告
覆盖率相关目标由 mk/coverage.mk 实现。默认输出目录取自 COVERAGE_DIR 环境变量,未设置时使用系统临时目录;报告会按包分别生成 .cover 文件,再汇总为统一的 profile.out,最终用 go tool cover -html 渲染成 HTML。
在容器构建场景下查看报告:
$ make coverage-serve
然后浏览器访问 http://localhost:8000,按 CTRL+C 即可停止服务。coverage-serve 实际是在覆盖率输出目录里用 Python 起一个 HTTP 服务(见 mk/coverage.mk),非常适合远程/无头构建环境。
本地原生构建时,可以直接生成并打开 HTML 报告:
$ make coverage-html
coverage-html 在 mk/coverage.mk 中用 open 命令打开生成的 index.html。此外还有:
$ make coverage-send # 把结果提交到 Coveralls(需安装 goveralls)
$ make coverage-generate # 仅生成 profile 数据
$ make coverage-clean # 清理覆盖率产物
coverage-send 依赖 github.com/mattn/goveralls,未安装时会直接报错提示安装命令(mk/coverage.mk)。
完整 Makefile 目标速查
高层目标
$ make clean # 清理构建与覆盖率产物
$ make build # 构建当前平台的 docker-machine
$ make test # dco + fmt + test-short + lint + vet
$ make validate # dco + fmt + lint + vet + test-long(race)
高级构建目标与交叉编译
为所有支持的 OS 与架构构建(产物在 bin 子目录下,文件名形如 docker-machine-Linux-x86_64):
$ make build-x
只为指定 OS / 架构列表构建:
$ TARGET_OS=linux TARGET_ARCH="amd64 arm" make build-x
这些变量在 Makefile.inc 中有默认值:TARGET_OS 默认为 darwin linux windows,TARGET_ARCH 默认为 amd64 arm arm64 386。实际的交叉编译逻辑在 mk/build.mk:只有在 VALID_OS_ARCH(darwin/amd64、linux/amd64、linux/arm、linux/arm64、openbsd/amd64、windows/amd64、windows/386)白名单内的组合才会被编译,且交叉编译时强制 CGO_ENABLED=0、-tags "static_build netgo" 并以静态方式链接;Windows 产物会自动追加 .exe 扩展名。
构建环境变量
构建行为可通过以下环境变量进一步控制(见 Makefile.inc 与 mk/main.mk):
| 变量 | 作用 |
|---|---|
DEBUG=true |
启用调试构建:关闭内联与变量寄存器化(-gcflags "-N -l"),保留 DWARF 信息 |
STATIC=true |
生成静态二进制(交叉编译时总是静态) |
VERBOSE=true |
输出详细构建日志(go build -v) |
PREFIX=folder |
指定二进制输出目录,默认是当前工作目录($(shell pwd)) |
BUILDTAGS |
附加 Go build tags |
PARALLEL |
并行构建数量(当前未被实际使用) |
COVERAGE_DIR |
覆盖率产物输出目录 |
非 DEBUG 模式下,mk/main.mk 会给 GO_LDFLAGS 追加 -w -s 以去掉 DWARF 调试信息和符号表,从而显著减小二进制体积。
清理构建结果:
$ make build-clean
覆盖率目标
$ make coverage-html # 生成 HTML 覆盖率报告
$ make coverage-serve # 通过 HTTP 提供覆盖率报告(默认端口 8000)
$ make coverage-send # 提交到 Coveralls
$ make coverage-generate # 生成覆盖率 profile
$ make coverage-clean # 清理覆盖率产物
测试目标
$ make test-short # 只跑短测试(go test -test.short)
$ make test-long # 跑全部测试并开启 race 检测
$ make test-integration # 运行 BATS 集成测试(详见下文)
验证目标
$ make fmt # gofmt 简化格式检查
$ make vet # go vet 静态检查
$ make lint # golint 检查
$ make dco # 校验提交的 DCO 签名
其中 dco 会调用 script/validate-dco,其校验逻辑是:对提交的每一条非空提交检查 message 中是否包含格式为 Signed-off-by: <Name> <email>(兼容 Docker-DCO-1.1- 前缀与可选的 (github: username) 后缀)的签名;纯文档类的小改动(仅改动 docs/ 且增删各不超过 1 行)享受 DCO 小型补丁豁免。
依赖管理:vendor 与 golang/dep
克隆仓库后,vendor/ 目录已包含全部第三方依赖,因此构建无需先拉取依赖。项目使用 golang/dep 作为 vendor 管理工具,依赖声明文件为根目录的 Gopkg.toml,锁定文件为 Gopkg.lock。新增或升级依赖时,应遵循 dep 的工作流(dep ensure 等命令),并保证 vendor/ 目录与锁定文件保持一致后再提交。
集成测试(BATS)
前置准备
集成测试使用 BATS(Bash Automated Testing System)编写与执行,因此第一步是安装 BATS(从源码安装即可)。测试脚本位于 test/integration,入口是 test/integration/run-bats.sh。
基本用法
首先构建二进制:
$ make build
然后通过 DRIVER 环境变量指定驱动、把测试文件或目录作为 TESTSUITE 参数传入:
$ DRIVER=foo make test-integration TESTSUITE
其中 TESTSUITE 是 test/integration 下的某个子目录(如 test/integration/core),foo 是想要测试的具体驱动。注意 test-integration 目标会先触发 build,再调用 test/integration/run-bats.sh $(TESTSUITE) 执行(见 mk/test.mk)。
以 VirtualBox 驱动运行核心命令测试为例:
$ DRIVER=virtualbox make test-integration test/integration/core/core-commands.bats
✓ virtualbox: machine should not exist
✓ virtualbox: create
✓ virtualbox: ls
✓ virtualbox: run busybox container
✓ virtualbox: url
✓ virtualbox: ip
✓ virtualbox: ssh
✓ virtualbox: docker commands with the socket should work
✓ virtualbox: stop
✓ virtualbox: machine should show stopped after stop
✓ virtualbox: machine should now allow upgrade when stopped
✓ virtualbox: start
✓ virtualbox: machine should show running after start
✓ virtualbox: kill
✓ virtualbox: machine should show stopped after kill
✓ virtualbox: restart
✓ virtualbox: machine should show running after restart
17 tests, 0 failures
Cleaning up machines...
Successfully removed bats-virtualbox-test
这个示例对应的测试用例正是 test/integration/core/core-commands.bats:它先用 use_shared_machine 创建共享测试机,然后依次验证 inspect、ls、create(重名失败)、config 接 docker 运行容器、url、ip、ssh、version、stop/start/kill/restart/upgrade 等命令在真实主机上的行为。这些用例同时是命令语义的权威参考——例如机器停止时 url、env、version 都会报 "Host is not running" 错误。
递归执行一个目录下的全部测试:
$ DRIVER=virtualbox make test-integration test/integration/core/
额外 create 参数
有些场景需要用与默认不同的 create 参数运行公共测试,例如在 Amazon EC2 上测试 RHEL 基础镜像。Docker Machine 的许多 flag 都支持环境变量注入,因此可以直接通过环境变量传参:
$ DRIVER=amazonec2 \
AWS_VPC_ID=vpc-xxxxxxx \
AWS_SECRET_ACCESS_KEY=yyyyyyyyyyyyy \
AWS_ACCESS_KEY_ID=zzzzzzzzzzzzzzzz \
AWS_AMI=ami-12663b7a \
AWS_SSH_USER=ec2-user \
make test-integration test/integration/core
上述命令即用指定的 VPC、凭据、AMI 与 SSH 用户,在 Amazon 上针对 Red Hat Enterprise Linux 运行 core 测试套件(实际凭据请按需替换)。
测试目录布局
test/integration 按测试对象划分目录(test/integration):
core:适用于所有驱动的通用测试,如 core-commands.bats、engine-options.bats、swarm-options.bats、regenerate-certs.bats 等;drivers:仅适用于特定驱动的测试,按云厂商分子目录(如amazonec2、virtualbox),例如 createwithkeypair.bats、upgrade.bats;cli:测试命令行接口本身的功能,与具体驱动细节关系不大(见 its/cli 目录下的driver_help_test.go等 CLI 测试)。
如果不确定新测试该放哪里,维护者很乐意提供引导。
编写集成测试的实践指南
来自维护者的通用准则(见 CONTRIBUTING.md 与 helpers.bash 的实现):
- 单一关注点:理想情况下,每个测试文件只关注一件事;
- 控制机器数量:除非测试本身就需要多台机器(例如多个机器的
ls测试,或创建并验证 Swarm 集群属性的测试),否则不应启动超过一台机器; - 善用失败输出:BATS 在测试失败时会打印测试中执行命令的输出,例如 BATS 提供的
$output变量,可用于调试信息; - 无需手动清理:测试脚本内置了清理钩子。从 test/integration/run-bats.sh 源码可见,
cleanup_machines会遍历docker-machine ls -q列出所有机器并rm -f删除(共享机器除外),cleanup_store会清空/tmp/machine-bats-test-$DRIVER存储路径,每个测试文件执行前后都会做一次清理。
此外,helpers.bash 还提供了 use_disposable_machine、use_shared_machine、only_if_env、require_env 等辅助函数:前者生成一次性机器名,后者复用跨测试文件共享的机器(避免重复创建),环境变量守卫则用于跳过或终止不符合前置条件的用例。
驱动(Driver)贡献要求
Docker Machine 内置了众多驱动(amazonec2、azure、digitalocean、exoscale、generic、google、hyperv、none、openstack、rackspace、softlayer、virtualbox、vmwarefusion、vmwarevcloudair、vmwarevsphere,全部注册于 cmd/docker-machine/machine.go 的 runDriver 分发逻辑中)。如果希望贡献一个新驱动,项目要求维护者做到以下几点,以保证驱动处于一致且稳定的状态:
- 及时响应针对该驱动提交的 issue;
- 审查该驱动的 Pull Request;
- 负责维护在新环境中运行单元测试与集成测试所需的基础设施;
- 每周参加一次驱动维护者会议。
需要特别说明的是:即使满足以上所有条件,也不保证驱动一定会被接受。如果有疑问,可以通过 IRC 联系维护团队。
小结
从环境准备、双通道构建(容器 / 本地 Go)、测试与验证分层(make test 到 make validate),到覆盖率报告、交叉编译、依赖管理、BATS 集成测试与驱动贡献规范,这份贡献者指南勾勒出一条完整且可验证的 Docker Machine 开发链路。所有环节都能在仓库源码中找到对应实现(Makefile、mk 目录、script 目录、test/integration 目录),贡献者可以按此流程放心地提交代码、测试与文档改动。