客户端一致性测试架构概念封面图

最近给 subconverter-ng 增加 sing-box 1.12+ 和 Clash provider 模式支持,接连踩出两个 P0。

83% 单元测试覆盖率,CI 全绿。两个 P0 都通过了全部单元测试。

第一个是 sing-box 用户导入配置后内核起不来。第二个是 Clash 用户打开配置,发现每个分组里只有一个 DIRECT。

这篇记录这两次事故,以及为了不再重演而补上的东西。

P0 之一:字段放错了层级

sing-box 1.12 把规则集引用从根级字段移到了 route 下面。我的生成器按 1.12 的 schema 输出,但把 rule_set 放在了配置的根级。

单元测试断言了「输出里有 rule_set」。它确实有。

把输出喂给真实的 sing-box 1.14,第一行就停了:

FATAL decode config at /tmp/sb.json: rule_set: json: unknown field "rule_set"

改成 route.rule_set 之后,又报第二个错:

FATAL missing route.default_domain_resolver: a domain resolver is required

1.12 起 DNS 解析器不再隐式推导,1.14 直接把它变成致命错误。两个错误叠在一起,才能让配置真正启动。

P0 之二:分组里没有节点

第二个更隐蔽。Clash 的 provider 模式只输出骨架,节点由客户端自己拉。分组通过 use: 引用 provider,通过 filter 按正则挑节点。

我给 .* 这个「匹配全部」的选择器只写了 filter,忘了挂 use:。生成的 YAML 完全合法:

proxy-groups:
  - name: 🚀 节点选择
    type: select
    proxies:
      - DIRECT
    filter: .*

mihomo 接受了它。配置能加载,分组是真的,只是没有任何 provider 可以选。用户看到的是一个空分组。

为什么测试没抓到

两个 bug 的共性:代码逻辑没错,错在对外部契约的理解。

单元测试的断言是我自己写的。我断言「输出包含 rule_set」,因为我认为那是对的。我断言「选择器变成了 filter」,因为我认为那就是分组。测试验证的是我的假设,不是客户端的接受度。

这类 bug 用覆盖率解决不了。83% 和 95% 一样会漏,因为漏掉的不是代码行,是一个没被验证的假设。

补上的东西:客户端一致性测试

我给仓库加了一个 internal/conformance 包,用构建标签 conformance 隔离,不进入常规测试。它做一件事:用真实生成器渲染 fixture,再把输出交给真实客户端。

  • sing-box:默认 target、singbox/1.10 到 singbox/1.13、模板渲染,共六个用例。
  • mihomo:内联规则、expand=false 的 rule-providers、provider=true。

版本矩阵有一个细节。用最新的 1.14 去验 1.10 的输出,会因「老格式已移除」而失败,这个失败没有意义。所以每个用例挑「已安装的、且不低于声明版本的最小客户端」:1.11.1 验 1.10 与 1.11,1.14.4 验 1.12 及以后。

核心调用逻辑极其朴素,直接拉起二进制做无副作用的语法与契约校验:

// internal/conformance/runner_test.go
//go:build conformance

func assertValidConfig(t *testing.T, client string, configPath string) {
	var cmd *exec.Cmd
	switch client {
	case "sing-box":
		cmd = exec.Command("sing-box", "check", "-c", configPath)
	case "mihomo":
		cmd = exec.Command("mihomo", "-t", "-d", filepath.Dir(configPath))
	}
	out, err := cmd.CombinedOutput()
	if err != nil {
		t.Fatalf("[%s] 配置被客户端拒绝:\n%s", client, string(out))
	}
}

**破坏性测试(Sabotage)**用来验证守卫本身。我把 route.rule_set 改名成 route.rule_set_SABOTAGE,测试立刻变红:

FATAL decode config: route.rule_set_SABOTAGE: json: unknown field
--- FAIL: TestSingboxClientAcceptsOutput/default

CI 里加了一个 conformance job,装两个 sing-box 版本和 mihomo,跑完整矩阵。另有一个每日任务,用最新发布的客户端重跑同一套用例。客户端发版删掉我们正在用的字段,第二天就能知道,而不是等用户导入失败。

这套测试测不到什么

说清楚边界,比夸大它有用。

它只能发现「客户端拒绝加载」这一类问题。客户端能加载、但路由不到任何东西的配置,它照样放过。mihomo 接受只有 DIRECT 的分组,所以第二个 P0 它也会漏。

那类问题靠两样东西:一是对渲染语义的单元测试,例如断言 provider 模式的每个组都有 use:;二是 &check=true,把「哪些分组没匹配到节点、哪些规则被丢了」直接返回给用户。

{
  "target": "clash",
  "nodes": 42,
  "empty_groups": ["🇯🇵 JP"],
  "dropped_rules": ["IP-CIDR,10.0.0.0/8,no-resolve,extra,DIRECT"]
}

一个可以带走的判断

如果你在写转换器、代码生成器、配置生成器这类工具,先问一个问题:我的测试里,有没有一个用例是「把输出交给真正的消费者」?

没有的话,覆盖率再高也只是在验证自己的假设。

常见问题

为什么两个 P0 没被 CI 拦住?

因为 CI 里的测试都是单元测试。它们断言输出的形状符合预期,但没有调用 sing-box 或 mihomo 去验证接受度。

客户端一致性测试要跑多久?

本地跑完整个矩阵约 13 秒。CI 里整个 job 约 25 秒,含下载两个客户端。因为它不影响常规测试,go test ./... 仍是秒级。

能不能只测最新版本客户端?

不能。生成器按声明版本切换 schema,老版本客户端的输出与新版不同。只用最新版会把「老格式已移除」的失败误判成新 bug,也漏掉老版本才有的问题。

为什么不用 Docker 把客户端真跑起来做端到端流量测试?

因为订阅转换器的契约核心是「配置格式与加载语义合法」。sing-box check 与 mihomo -t 是客户端自带的原生纯校验指令,毫秒级运行、零外部网络依赖。端到端流量测试需要拉取真实节点并走网络,不仅慢,还会因为外部节点网络抖动产生大量误报,不适合放在提交流水线。