Devtron 自动化测试集成指南:在 CI 流水线中使用 devtron-ci.yaml 编排测试用例
Devtron 自动化测试集成指南:在 CI 流水线中使用 devtron-ci.yaml 编排测试用例
在 Devtron 中,自动化测试套件可以在 CI(持续集成)步骤中灵活集成:既可以直接通过 Devtron 仪表盘(Dashboard)为流水线配置测试脚本,也可以将测试用例写入源码仓库根目录的 devtron-ci.yaml 文件,随代码一并版本化管理。本文以 devtron-ci.yaml 为核心,详细讲解其字段含义、执行顺序、与 Docker 构建阶段的关系以及测试报告的收集方式,并结合 devtron 开源仓库的源码实现,帮助读者真正掌握在 CI 步骤中编排自动化测试的完整方案。
devtron-ci.yaml 在 CI 流程中的定位
Devtron 的 CI 流水线负责从 Git 源码构建容器镜像。除了仪表盘上可视化的流水线配置,Devtron 还支持"配置即代码"的方式:用户可以在源码仓库中放置一个名为 devtron-ci.yaml 的文件,把测试用例、构建前后需要执行的脚本等声明式地写入其中。这样,测试逻辑与源码保持同仓库、同版本,便于团队统一管理和审计。
在仓库源码中,该 YAML 配置的解析由 pkg/pipeline/types/Task.go 中的结构体定义承载:
type TaskYaml struct {
Version string `yaml:"version"`
CdPipelineConfig []CdPipelineConfig `yaml:"cdPipelineConf"`
}
type CdPipelineConfig struct {
BeforeTasks []*Task `yaml:"beforeStages"`
AfterTasks []*Task `yaml:"afterStages"`
}
type Task struct {
Id int `json:"id,omitempty"`
Index int `json:"index,omitempty"`
Name string `json:"name" yaml:"name"`
Script string `json:"script" yaml:"script"`
OutputLocation string `json:"outputLocation" yaml:"outputLocation"` // file/dir
RunStatus bool `json:"-,omitempty"`
}
可以看到,一个 devtron-ci.yaml 由顶层 version 字段和 cdPipelineConf 列表构成;每个流水线配置包含 beforeStages(构建前阶段)与 afterStages(构建后阶段)两组任务列表,每个任务由 name、script、outputLocation 等字段描述。解析逻辑见 pkg/pipeline/StageServiceUtil.go 中的 ToTaskYaml 函数,它使用 yaml.Unmarshal 将文件内容映射为上述结构体:
func ToTaskYaml(yamlFile []byte) (*types.TaskYaml, error) {
taskYaml := &types.TaskYaml{}
err := yaml.Unmarshal(yamlFile, taskYaml)
return taskYaml, err
}
执行顺序:脚本用例先于 devtron-ci.yaml 用例运行
当 CI 流水线触发时,测试用例的执行遵循明确的先后顺序:
- 仪表盘脚本中配置的测试用例会先执行;
devtron-ci.yaml中配置的测试用例随后执行。
即"脚本中给定的测试用例将先于 devtron-ci.yaml 中给定的测试用例运行"。这一设计让运维/平台团队可以通过仪表盘注入必要的环境准备类脚本(例如设置凭据、初始化测试环境),再运行仓库中随代码维护的正式测试套件。从源码结构看,仪表盘配置的 Pre/Post-Build 任务与 devtron-ci.yaml 中的阶段最终都会汇聚到同一套任务模型上,通过 beforeStages/afterStages 统一编排,只是配置来源不同。
字段详解
devtron-ci.yaml 中的核心字段如下表所示,其中 version、appliesTo、type、value 用于声明该配置的适用范围,script 描述要执行的命令,beforeDockerBuildStages/afterDockerBuildStages 划分执行时机,outputLocation 指定测试报告的产物位置:
| 字段 | 说明 |
|---|---|
version |
指定 YAML 的版本号 |
appliesTo |
将变更应用到指定的分支 |
type |
变更所应用到的分支类型,取值可为 BRANCH_FIXED 或 TAG_PATTERN |
value |
变更所应用到的分支名称,可填具体分支名(如 "master"),也可填正则表达式(如 "%d.%d.%d-rc") |
script |
需要执行的脚本,此处也可以执行 docker 命令 |
beforeDockerBuildStages |
在 docker 构建步骤之前运行的脚本 |
afterDockerBuildStages |
在 docker 构建步骤之后运行的脚本 |
outputLocation |
测试用例报告输出位置的查看路径 |
type 与 value:控制测试脚本的生效范围
type 与 value 配合使用,用于限定 appliesTo 指定的分支范围。BRANCH_FIXED 表示固定分支匹配,value 直接填写分支名(如 master);TAG_PATTERN 表示按标签(Tag)模式匹配,value 使用正则表达式(如 %d.%d.%d-rc)来匹配符合格式的标签。
在 devtron 仓库中,分支/标签的触发类型由统一的 SourceType 枚举管理,见 pkg/bean/app.go:
Type constants.SourceType `json:"type,omitempty" validate:"oneof=SOURCE_TYPE_BRANCH_FIXED SOURCE_TYPE_BRANCH_REGEX SOURCE_TYPE_TAG_ANY WEBHOOK"`
其中 SOURCE_TYPE_BRANCH_FIXED 与文档中的 BRANCH_FIXED 对应,表示对指定固定分支生效;标签模式则对应 TAG 类触发源。触发侧在 pkg/build/trigger/HandlerService.go 中会依据 SOURCE_TYPE_BRANCH_FIXED 判断当前提交是否满足触发条件,只有满足条件的分支/标签才会执行对应的 CI 及测试流程。
beforeDockerBuildStages 与 afterDockerBuildStages:围绕构建阶段的编排
这两个字段将测试脚本锚定在 Docker 构建步骤的前后:
- beforeDockerBuildStages:在镜像构建开始前执行。适合放置单元测试、静态检查、依赖安装验证等"构建前门禁"脚本,若此阶段失败,镜像不会进入构建;
- afterDockerBuildStages:在镜像构建完成后执行。适合放置集成测试、镜像冒烟验证、报告生成等脚本。
这与 Devtron CI 流水线中的 Pre-build 阶段(PRE_CI) 与 Post-build 阶段(POST_CI) 一一对应。在 pkg/pipeline/CiCdPipelineOrchestrator.go 中,创建/更新 CI 流水线时会分别持久化这两类阶段:
err = impl.pipelineStageService.UpdatePipelineStage(createRequest.PreBuildStage, repository5.PIPELINE_STAGE_TYPE_PRE_CI, createRequest.Id, userId)
err = impl.pipelineStageService.UpdatePipelineStage(createRequest.PostBuildStage, repository5.PIPELINE_STAGE_TYPE_POST_CI, createRequest.Id, userId)
阶段内的每个步骤在 YAML 中即表现为一个 Task:script 是要执行的 shell 脚本(StageYamlToPipelineStageAdapter 中将脚本以 SCRIPT_TYPE_SHELL 内联步骤承载,见 pkg/pipeline/StageServiceUtil.go)。
outputLocation:测试报告的产物收集
outputLocation 用于声明测试脚本产出的报告文件或目录路径(file/dir)。运行结束后,Devtron 会在该位置查找测试报告并展示在流水线结果中。在源码的 Task 结构体中,该字段以 json:"outputLocation" yaml:"outputLocation" 定义,注释明确标注其内容为 file/dir。
在 pkg/pipeline/StageServiceUtil_test.go 的测试用例中,可以看到完整的 YAML 形态示例——构建前阶段包含两个脚本任务,各自输出独立报告文件:
version: ""
cdPipelineConf:
- beforeStages:
- id: 0
index: 0
name: test-1
script: |
date > test.report
outputLocation: ./test.report
runstatus: false
- id: 0
index: 0
name: test-2
script: |
date > test2.report
outputLocation: ./test2.report
runstatus: false
afterStages: []
测试中还验证了 afterStages 分支(构建后阶段)的等价写法,二者结构完全对称,仅所在列表不同。这也是实际书写 devtron-ci.yaml 时的最佳参考模板。
实践建议
综合文档说明与源码实现,在 CI 步骤中集成自动化测试时可以参考以下做法:
- 仓库即配置:在源码仓库根目录维护
devtron-ci.yaml,使测试脚本与代码版本同步演进,避免测试逻辑散落在平台配置中; - 按阶段拆分:将快速、低成本的检查放入
beforeDockerBuildStages(构建前),将依赖镜像的测试放入afterDockerBuildStages(构建后),充分利用两个阶段的失败隔离特性; - 限定生效范围:通过
appliesTo+type/value组合,让测试脚本只在指定分支(如master)或符合正则模式的标签(如%d.%d.%d-rc)上执行,避免在每次提交上都重复运行重型测试; - 声明报告路径:为每个测试任务设置
outputLocation,让测试报告能够在流水线结果中集中查看; - 理解执行优先级:若同时通过仪表盘和
devtron-ci.yaml配置了测试,需注意仪表盘脚本中的用例会先执行,可将环境准备类脚本放在仪表盘侧,将核心断言类测试放在devtron-ci.yaml中。
总结
devtron-ci.yaml 为 Devtron CI 流水线提供了"配置即代码"的自动化测试集成方式,其 version、appliesTo、type、value、script、beforeDockerBuildStages、afterDockerBuildStages、outputLocation 八个字段覆盖了脚本内容、执行时机、生效范围与报告收集的完整编排能力。结合 pkg/pipeline/types/Task.go 的结构定义与 pkg/pipeline/StageServiceUtil.go 的解析实现,开发者可以精准地把测试套件嵌入镜像构建流程的前后,让每一次 CI 构建都带上可追溯、可查看的自动化测试结果。关于 CI 流水线的整体创建与配置,可进一步参考 CI 流水线文档。