Go / 系统课时
测试 HTTP Handler
测试 HTTP Handler
本节用 net/http/httptest 在进程内构造请求与响应记录器,直接调用 Handler,并同时校验状态码、响应头和响应体。完成后,你可以在不启动真实端口的情况下,为 HTTP 接口建立快速、稳定且可重复的单元测试。
学习目标
- 使用
httptest.NewRequest和httptest.NewRecorder构造一次完整的 Handler 调用 - 对状态码、响应头和响应体编写明确断言
- 理解直接测试 Handler 能覆盖什么,以及它与真实 HTTP 服务测试的边界
Handler 测试的核心对象
httptest.NewRequest 会创建适合测试的 *http.Request,httptest.NewRecorder 则实现 http.ResponseWriter,把 Handler 写出的状态码、响应头和响应体保存在内存中。测试只需调用一次 handler.ServeHTTP(recorder, request),无需监听端口,也不会产生真实网络连接。
这种方式特别适合验证纯 Handler 行为:给定请求后,是否返回正确状态、内容类型和正文。若目标是验证客户端传输、连接、TLS 或真实服务器路由,则应使用 httptest.Server,而不是只调用 Handler。
编写一个可运行的 Handler 测试
下面的测试文件同时包含被测 Handler 和测试函数。把它保存为 Go 模块中的 handler_test.go,即可直接运行。Handler 只接受 GET,成功时返回 JSON;其他方法返回 405 Method Not Allowed。
package httpdemo
import (
"io"
"net/http"
"net/http/httptest"
"testing"
)
func pingHandler(w http.ResponseWriter, r *http.Request) {
if r.Method != http.MethodGet {
http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
return
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(http.StatusOK)
_, _ = io.WriteString(w, `{"message":"pong"}`)
}
func TestPingHandler(t *testing.T) {
req := httptest.NewRequest(http.MethodGet, "/ping", nil)
rec := httptest.NewRecorder()
// 直接调用 Handler,测试过程不启动真实 HTTP 服务器。
http.HandlerFunc(pingHandler).ServeHTTP(rec, req)
res := rec.Result()
defer res.Body.Close()
if res.StatusCode != http.StatusOK {
t.Fatalf("status = %d, want %d", res.StatusCode, http.StatusOK)
}
if got := res.Header.Get("Content-Type"); got != "application/json" {
t.Fatalf("Content-Type = %q, want %q", got, "application/json")
}
body, err := io.ReadAll(res.Body)
if err != nil {
t.Fatal(err)
}
if got, want := string(body), `{"message":"pong"}`; got != want {
t.Fatalf("body = %q, want %q", got, want)
}
}预期结果:测试函数没有触发 t.Fatal 或 t.Fatalf,说明三类断言全部通过。
运行指定测试:
go test -run TestPingHandler -v预期输出:
=== RUN TestPingHandler
--- PASS: TestPingHandler (<TIME>)
PASS
ok <MODULE_PATH> <TIME>其中 <MODULE_PATH> 和 <TIME> 会随模块路径与运行环境变化。
正确读取 Recorder 的结果
httptest.ResponseRecorder 本身暴露了 Code、Header() 和 Body,但在测试接近真实响应语义时,更推荐调用 rec.Result() 得到 *http.Response。这样读取状态、响应头和响应体的方式与客户端侧代码一致,也便于显式关闭 Body。
不要只断言状态码。一个 Handler 即使返回 200,也可能遗漏 Content-Type,或输出了错误的 JSON。对外契约包含哪些字段,测试就应检查哪些字段;同时避免断言与契约无关的实现细节,例如内部函数调用次数。
什么时候需要更高一层测试
直接调用 Handler 不会覆盖真实监听端口、客户端传输层、代理行为或 TLS 握手,也不会自动证明生产中的完整中间件链已接入。如果问题属于“Handler 给定请求后如何响应”,优先使用 NewRequest 加 NewRecorder;如果问题属于“客户端发出的 HTTP 请求经过服务器后如何返回”,再升级到 httptest.Server。