httptest.NewTLSServer 测试证书校验分支的实践示例

我在给 HTTP 客户端补 HTTPS 测试时，最容易混淆的是“服务启动成功”和“客户端证书校验成功”其实是两件事。httptest.NewTLSServer 会启动带测试证书的本地 HTTPS 服务；默认客户端并不信任这张证书，而 server.Client() 才是配套的可信测试客户端。要覆盖证书校验分支，就把这两个客户端都保留下来分别断言。

官方文档：https://pkg.go.dev/net/http/httptest

先把测试服务和证书边界固定下来

这个 API 返回的 Server 已经开始监听本地回环地址，URL 是 https:// 开头。测试结束时要调用 Close，否则重复运行测试时容易留下连接和端口噪声。下面的处理器只返回一个健康检查文本，故意不把业务逻辑和 TLS 诊断混在一起。

func TestTLSCertificateBranches(t *testing.T) {
	// 使用固定响应，把证书问题与业务响应分离。
	server := httptest.NewTLSServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// 只有健康检查路径进入成功分支。
		if r.URL.Path != "/healthz" {
			http.NotFound(w, r)
			return
		}
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("ok"))
	}))
	defer server.Close() // 释放监听器，并关闭测试客户端的空闲连接

	// 后续分别使用默认客户端和测试服务提供的客户端。
}

如果测试代码要先修改 EnableHTTP2 或 TLS，应在第一次调用 Client、Start 或 StartTLS 之前完成；NewTLSServer 本身已经替你启动了服务。

用默认客户端覆盖证书校验失败分支

第一条分支不是“请求接口失败”，而是 TLS 握手阶段就没有建立可信连接。默认客户端没有 httptest 生成的根证书，因此请求 server.URL 应该失败。用 errors.As 向下拆错误，比比较整段字符串稳定。

// 默认客户端不信任 httptest 的临时证书，应在握手阶段失败。
	_, err := http.Get(server.URL + "/healthz")
	if err == nil {
		t.Fatal("default client unexpectedly trusted the test certificate")
	}

	var unknownCA x509.UnknownAuthorityError
	if !errors.As(err, &unknownCA) {
		t.Fatalf("want x509.UnknownAuthorityError, got %v", err)
	}

这个断言的意义是确认“证书未被信任”这条路径确实被覆盖，而不是把任何网络错误都算成通过。若测试环境对错误链做了额外包装，至少仍应保留“请求必须失败”的主断言，并在日志中打印原始错误。

用 server.Client 覆盖成功分支

Server.Client() 会返回已经配置好信任测试证书的客户端。它不是生产环境客户端，也不应该被抽成全局共享实例；在本测试里直接使用并在响应后关闭 body 即可。

// server.Client 已经把测试证书放进自己的信任配置。
	client := server.Client()
	resp, err := client.Get(server.URL + "/healthz")
	if err != nil {
		t.Fatalf("trusted test client request failed: %v", err)
	}
	defer resp.Body.Close() // 即使只读少量响应，也要释放连接复用资源

	if resp.StatusCode != http.StatusOK {
		t.Fatalf("want status 200, got %d", resp.StatusCode)
	}
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		t.Fatalf("read response body: %v", err)
	}
	if string(body) != "ok" {
		t.Fatalf("want body ok, got %q", body)
	}

把分支断言和业务响应分开

我通常按下面的顺序读失败信息：先看有没有拿到 resp，再看 HTTP 状态码，最后看响应体。没有 resp 时，问题还在 DNS、连接或 TLS；拿到 resp 后，才进入处理器和业务断言。

检查自定义客户端的边界

如果被测函数要求传入自己的 *http.Client，可以从 server.Client().Transport 复制一份 *http.Transport，再设置测试需要的超时或代理。不要直接把 InsecureSkipVerify: true 当作修复，它会让测试绕过正在验证的证书逻辑，最终只能证明“跳过检查后请求能通”。

// 复制 httptest 的可信根配置，再叠加被测客户端的超时策略。
	baseTransport, ok := server.Client().Transport.(*http.Transport)
	if !ok {
		t.Fatal("httptest client does not expose an *http.Transport")
	}
	customTransport := baseTransport.Clone()
	customClient := &http.Client{
		Transport: customTransport,
		Timeout:   2 * time.Second, // 只模拟调用方超时，不改变证书校验
	}

	resp, err = customClient.Get(server.URL + "/healthz")
	if err != nil {
		t.Fatalf("custom trusted client request failed: %v", err)
	}
	defer resp.Body.Close()

这套写法的边界很清楚：NewTLSServer 负责提供测试服务和临时证书，server.Client 负责提供匹配的信任配置，测试本身负责把握手结果与业务结果拆开。需要验证真实 CA、主机名或证书轮换时，应另写集成测试，不要把这条本地测试路径当成生产 TLS 验证的替代品。

相关问题

为什么直接使用 http.Get 会失败？

因为默认客户端的根证书池不包含 httptest.NewTLSServer 使用的测试证书，失败发生在 HTTP 请求进入处理器之前。

server.Client 返回的客户端能否用于生产代码？

不建议。它的信任配置只服务于当前测试服务器，适合注入被测函数，不代表生产环境的 CA、代理和超时策略。

什么时候需要 Clone Transport？

当被测客户端还需要自定义超时、代理或连接策略时再复制；只想请求测试服务时，直接使用 server.Client() 更简单。