Ginkgo 规格过滤完全指南:从 Pending、Focus、Label 到 --sem-ver-filter 的组合优先级详解

原创2026-09-24 13:22:001,908 阅读
文章标签:测试CLI

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 中参数解析/校验流程一致):

  1. Pending —— 永远不运行,任何机制都无法覆盖;
  2. Skip() —— 运行时无条件跳过,与其他过滤器无关;
  3. 程序化 Focus —— 始终生效并强制非零退出;CLI 过滤器只能在此基础上进一步收窄 focused 子集;
  4. 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 过滤器四层优先级逐层排查即可。
登录后查看全文
ginkgo