Ginkgo 规格过滤完全指南:从 Pending、Focus、Label 到 --sem-ver-filter 的组合优先级详解
Ginkgo 规格过滤完全指南:从 Pending、Focus、Label 到 --sem-ver-filter 的组合优先级详解
Ginkgo 为 Go 测试提供了从“临时调试”到“结构化 CI 筛选”的多层次规格(spec)过滤手段:编译期的 Pending、运行时的 Skip、程序化的 Focus,以及结构化的 Label 标签、SemVer 版本门控和 CLI 文件/描述过滤器。本文以 Ginkgo 源码为据,系统讲解每种过滤方式的语义、组合规则与严格优先级,帮助你准确控制“哪些规格运行、哪些不运行”,并利用 --fail-on-pending、--fail-on-empty 防止过滤失误静默进入 CI。
说明:过滤器细节的装饰器定义可参考
ginkgo:decorators,标签驱动的 CI 策略可参考ginkgo:ci。本文所有命令行参数、装饰器与内部实现均以当前仓库源码为准。
Pending —— 编译期跳过,不可被任何机制强制运行
Pending 用于标记“仍在开发中”的规格或容器。它的语义是强制的:没有任何机制(包括 Focus、标签过滤)可以覆盖 Pending 让它运行。
It("needs work", Pending, func() { ... })
It("placeholder", Pending) // pending 规格可以没有闭包
PDescribe("not ready", func() { ... }) // 等价于 Describe(..., Pending);X 前缀完全相同
PIt(...) / XIt(...) / PEntry(...)
在 decorator_dsl.go 中可以看到 Pending 被定义为与 PIt、PDescribe 完全相同的装饰器常量,而 P / X 前缀与装饰器写法互为等价语法糖。
Pending 规格不会导致套件失败,但可以结合 ginkgo --fail-on-pending 让 CI 因存在 pending 规格而失败——这是“pending 规格不应被提交”这一团队策略的落地手段。Pending 只存在于编译期:你无法在运行时把一个规格动态标记为 pending,这类需求应使用 Skip。
Skip —— 运行时跳过
Skip("reason") 可在任意 subject 或 setup 节点中调用,在运行阶段跳过当前规格。其底层实现与 Fail 同构:调用后触发 panic 以中止规格执行,并记录原因。源码见 core_dsl.go:
func Skip(message string, callerSkip ...int) {
cl := types.NewCodeLocationWithStackTrace(skip + 1)
global.Failer.Skip(message, cl)
panic(types.GinkgoErrors.UncaughtGinkgoPanic(cl))
}
Failer.Skip 只在规格状态仍为 SpecStatePassed 时将其置为 SpecStateSkipped(见 internal/failer.go),因此跳过不会导致套件失败——即使所有规格都被跳过,套件依然通过。
It("if it can", func() {
if !someCondition { Skip("special condition wasn't met") }
...
})
作用域差异至关重要:
- 在
BeforeEach中调用 → 只跳过当前规格; - 在
BeforeAll中调用 → 跳过Ordered容器内的全部规格; - 在
BeforeSuite中调用 → 跳过整个套件。
注意:不能在容器主体(container body)中调用 Skip,它只适用于运行阶段。
Focus —— 程序化聚焦,用于迭代调试(切勿提交)
当存在任意 focused 规格时,Ginkgo 只运行 focused 规格。
FIt("just me", func() { ... }) // 或 It(..., Focus, ...)
FDescribe(...) / FContext(...) / FEntry(...)
Focus 装饰器与 FIt、FDescribe 完全等价(见 decorator_dsl.go)。
子节点聚焦会使父节点的聚焦失效:在 FDescribe 内部的某个 It 上再加 F,则只有那个 It 运行——这正好对应调试时不断收窄范围的习惯。
风险:提交 focus 会让 CI “悄悄而响亮”地失败。一个通过但包含程序化 focus 的套件会以非零状态退出(日志显示成功但会标记 focused 规格),从而被 CI 捕获。清理手段是 ginkgo unfocus 命令,它会递归移除 F 前缀和 Focus 装饰器;其实现(ginkgo/unfocus/unfocus_command.go)通过解析 Go AST 识别 FDescribe、FContext、FIt、FDescribeTable、FEntry、FSpecify、FWhen 等标识符并消除。
Labels 与 --label-filter
Label("a", "b") 为容器/主体节点打标签(见 decorator_dsl.go);一个规格的标签是其节点层级上所有标签的并集。标签内容不允许包含 &|!,()/" 这些字符——该限制在 types/label_filter.go 的 ValidateAndCleanupLabel 中强制校验,同时还禁止空标签和以 : 开头的标签。
使用 ginkgo --label-filter=QUERY 进行过滤,查询语言支持的运算符:
| 运算符 | 含义 |
|---|---|
&& |
AND |
| ` | |
! |
NOT |
() |
分组 |
/regexp/ |
对标签做正则匹配 |
裸词按标签字面量匹配,大小写不敏感、首尾空白会被裁剪(见 types/label_filter.go 中 matchLabelAction 的实现)。该查询表达式由 types/label_filter.go 的 ParseLabelFilter 经 token 化后构造表达式树求值,各运算符优先级为:||(1) < &&(2) < !(3) < set 操作(4)。
ginkgo --label-filter="network && !slow"
ginkgo --label-filter="integration, smoke" # 逗号等价于 ||
ginkgo --label-filter=/library/ # 正则
一致的打标习惯是维护性过滤的最佳实践。
标签集合 —— KEY:VALUE
标签 KEY:VALUE 会把 VALUE 加入名为 KEY 的集合(多个值累积,例如 Label("API:Library", "API:Geo") 得到 API = {Library, Geo})。过滤语法为 KEY: OP <arg>,arg 可以是单个值或 {V1, V2} 形式:
| 操作 | 当集合 KEY … 时匹配 |
|---|---|
isEmpty |
没有任何 KEY:* 标签 |
containsAny |
包含任意一个 arg 元素 |
containsAll |
包含全部 arg 元素 |
consistsOf |
与 args 完全相等 |
isSubsetOf |
是 args 的子集 —— 注意:空集合始终匹配 |
ginkgo --label-filter="integration && !slow && Readiness: isSubsetOf {Beta, RC}"
ginkgo --label-filter="API: consistsOf {Library, Geo}"
集合值按字面量匹配(不支持正则)。对于结构化过滤,优先使用集合而非正则。这些操作的底层实现在 types/label_filter.go:labelSetFor 按冒号切分标签并构建集合,containsAny/containsAll/consistsOf/isSubsetOf/isEmpty 分别对应集合包含、相等与子集判定;isSubsetOf 的实现对空集合恒真。语法错误信息(如缺少 set key、isEmpty 误带参数、集合操作误用正则等)在 types/label_filter_test.go 中有完整用例覆盖。
- 套件级标签:
RunSpecs(t, "Books Suite", Label("books"))将标签应用于整个套件,可据此过滤掉整个套件; - 运行时检查:
Label("perf").MatchesLabelFilter(GinkgoLabelFilter())让规格根据当前--label-filter动态分支(GinkgoLabelFilter()返回该过滤器字符串,见 core_dsl.go); - 发现与迭代:
ginkgo labels列出包内所有标签(实现见 ginkgo/labels/labels_command.go);ginkgo --dry-run -v --label-filter=Q可在不真正运行的情况下预览过滤器选中了哪些规格。
SemVer 过滤
SemVerConstraint(">= 3.2.0") 和 ComponentSemVerConstraint("redis", ">= 8.0.0") 用版本约束为规格做门控,运行时搭配 --sem-ver-filter 使用。约束语法遵循 Masterminds/semver 规范(支持 ~、^、逗号连接的多个 AND 约束)。约束沿节点层级向下收窄(取交集),绝不放宽。当设置了 --sem-ver-filter 时,没有约束的规格始终运行。
ginkgo --sem-ver-filter="2.1.1, redis=8.2.0"
在 types/semver_filter.go 的 ParseSemVerFilter 中可以看到:过滤器字符串按逗号拆分,component=version 形式(如 redis=8.2.0)会单独记录为组件版本,裸版本(如 2.1.1)则作为通用版本;求值时,带 SemVerConstraint 的规格用通用版本校验,带 ComponentSemVerConstraint 的规格用对应组件的版本校验,约束不满足即被过滤。装饰器定义见 decorator_dsl.go,其中 ComponentSemVerConstraint 的组件名不允许为空。
CLI 文件与描述过滤器
--focus=REGEXP/--skip=REGEXP:匹配完整拼接的规格描述(所有容器文本 +It文本)。多个--focus之间取 OR,多个--skip之间取 OR;最终运行的规格是“匹配 focus 且不匹配 skip”的交集。(标签通常是更优选择。)对应的参数声明见 types/config.go。--focus-file=FILTER/--skip-file=FILTER:按源码位置过滤。形式包括FILE_REGEX、FILE_REGEX:LINE、FILE_REGEX:LINE1-LINE2(半开区间,即LINE1 <= line < LINE2,见 types/file_filter.go)。单个 flag 内可用逗号分隔多个行/区间,多个文件则重复使用该 flag。LINE必须是节点(如It())被调用的精确行号,而不是“大致位置”——因为 types/file_filter.go 的Matches是拿节点记录的真实代码位置做逐行匹配。
优先级 —— 各过滤器如何组合
所有过滤机制按如下严格优先级叠加(见文档底部结论,与 types/config.go 中参数解析/校验流程一致):
Pending—— 永远不运行,任何机制都无法覆盖;Skip()—— 运行时无条件跳过,与其他过滤器无关;- 程序化
Focus—— 始终生效并强制非零退出;CLI 过滤器只能在此基础上进一步收窄 focused 子集; - CLI 过滤器(
--label-filter、--focus-file/--skip-file、--focus/--skip)之间是 AND 关系 —— 规格必须同时满足全部条件。
这意味着“越靠前的优先级越硬”:Pending 连 Focus 都拗不过,而 CLI 各过滤项之间则必须全部满足才能运行。
捕获过滤失误
ginkgo --fail-on-pending—— 只要存在 pending 规格即判套件失败(参数定义见 types/config.go);ginkgo --fail-on-empty—— 若零个规格运行则判失败,用于捕获写错的--label-filter或过度激进的 skip。例如ginkgo --fail-on-empty --label-filter mytypo ./...(参数定义见 types/config.go);--silence-skips—— 在嘈杂的输出中抑制S跳过标记(参数定义见 types/config.go)。
实践建议小结
- 开发阶段用
FIt/Focus快速聚焦单条规格,提交前务必ginkgo unfocus清理; - 长期结构化的筛选优先使用
Label与 label set(如API: consistsOf {Library, Geo}),并保持打标约定一致; - 多版本兼容测试用
SemVerConstraint/ComponentSemVerConstraint做版本门控; - CI 中同时开启
--fail-on-pending与--fail-on-empty,把“漏跑”和“多跑”都变成显式失败; - 排查“为什么这条规格没跑/跑了”时,按 Pending → Skip → Focus → CLI 过滤器四层优先级逐层排查即可。