httptest — ทดสอบ handler โดยไม่ต้องเปิดเซิร์ฟเวอร์

go version go1.26.5 darwin/arm64
github.com/gin-gonic/gin v1.12.0
github.com/stretchr/testify v1.12.1

1 · ปัญหาก่อน แล้วค่อยดูเครื่องมือ

ลองนึกว่าจะเทส GET /users/:id ด้วยความรู้ที่มีตอนนี้ ทางที่นึกออกคือ: เปิดเซิร์ฟเวอร์ด้วย r.Run(":8080") แล้วยิง http.Get("http://localhost:8080/users/1")
มันทำงานได้จริง แต่ลองไล่ราคาที่ต้องจ่ายดู:

ทั้งหมดนี้เป็นค่าใช้จ่ายของชั้น network ซึ่งเราไม่ได้อยากเทสมันเลย — เราอยากรู้แค่ว่า "ยิง path นี้เข้าไป แล้ว handler ตอบ status/body อะไร"

ทางออกซ่อนอยู่ใน interface ที่คุณเห็นมาตั้งแต่บท 37 แล้วแต่อาจยังไม่ทันสังเกต — http.Handler มี method เดียวเท่านั้น:

type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}

อ่านช้า ๆ อีกรอบ: มันคือฟังก์ชันธรรมดาที่รับสองพารามิเตอร์ ตัวหนึ่งคือ "คำถาม" (*http.Request) อีกตัวคือ "สมุดให้เขียนคำตอบ" (http.ResponseWriter)
ในโลกจริง Go เป็นคนสร้างสองตัวนี้จาก TCP socket แล้วเรียก ServeHTTP ให้
แต่ไม่มีกฎข้อไหนบอกว่ามันต้องมาจาก socket — ถ้าเราประกอบสองตัวนี้ขึ้นมาเองแล้วเรียกตรง ๆ handler ก็ทำงานเหมือนเดิมทุกประการ โดยไม่มี network เข้ามาเกี่ยวเลย

ของจริง
  browser ──TCP──▶ net/http ──สร้าง req + w ให้──▶ router.ServeHTTP(w, req) ──▶ handler

ในเทส  (เราเป็นคนสร้าง req + w เอง แล้วเรียกบรรทัดเดียวกันนั้นตรง ๆ)
  httptest.NewRequest(...) ─▶ req ─┐
                                   ├──▶ router.ServeHTTP(w, req) ──▶ handler
  httptest.NewRecorder()   ─▶ w  ──┘

  (ไม่มี browser · ไม่มี TCP · ไม่มี port — ทุกอย่างอยู่ใน RAM ล้วน ๆ)

net/http/httptest ให้สองอย่างพอดี: NewRequest ปั้น *http.Request ปลอมขึ้นมาจาก method + path และ NewRecorder ให้ ResponseWriter ที่ไม่ส่งอะไรออกไปไหน แต่จดทุกอย่างที่ handler เขียนลงไป แล้วให้เราอ่านย้อนหลังได้

2 · โค้ดที่เราจะเทสกันทั้งบท

นี่คือของที่ต่อยอดตรงจาก บทเรียน 39 — มี c.Param, มี ShouldBindJSON + binding tag ครบ
เซฟเป็น app.go ในโฟลเดอร์เปล่า ๆ ที่ go mod init check ไว้แล้ว (ทุกไฟล์ในบทนี้อยู่โฟลเดอร์เดียวกันหมด · ชื่อ package ต้องตรงกันทุกไฟล์):

package main

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

type User struct {
    ID   string `json:"id"`
    Name string `json:"name"`
}

type CreateUserReq struct {
    Name  string `json:"name"  binding:"required"`
    Email string `json:"email" binding:"required,email"`
}

var db = map[string]User{
    "1": {ID: "1", Name: "Somchai"},
}

func GetUser(c *gin.Context) {
    id := c.Param("id")
    u, ok := db[id]
    if !ok {
        c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
        return
    }
    c.Header("X-Course", "go-day8")
    c.JSON(http.StatusOK, u)
}

func CreateUser(c *gin.Context) {
    var req CreateUserReq
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }
    c.JSON(http.StatusCreated, gin.H{"name": req.Name, "email": req.Email})
}

// จุดที่สำคัญที่สุดของไฟล์นี้: แยก "สร้าง router" ออกจาก "รัน server"
func NewRouter() *gin.Engine {
    r := gin.New()
    r.GET("/users/:id", GetUser)
    r.POST("/users", CreateUser)
    return r
}

func main() {
    NewRouter().Run(":8080")   // เทสไม่แตะบรรทัดนี้เลย — ดูกล่องข้างล่าง
}

3 · สามบรรทัดที่ต้องจำ

เซฟเป็น basic_test.go ข้าง ๆ app.go — package เดียวกัน จึงเรียก NewRouter() ได้เลยโดยไม่ต้อง import อะไรเพิ่ม:

package main

import (
    "net/http/httptest"
    "testing"

    "github.com/stretchr/testify/assert"
)

func TestGetUser_Basic(t *testing.T) {
    router := NewRouter()

    w := httptest.NewRecorder()                              // 1) กล่องรับคำตอบ
    req := httptest.NewRequest("GET", "/users/1", nil)      // 2) คำถามปลอม
    router.ServeHTTP(w, req)                                // 3) ยิงเข้า router ตรง ๆ

    assert.Equal(t, 200, w.Code)
    assert.JSONEq(t, `{"id":"1","name":"Somchai"}`, w.Body.String())
    assert.Equal(t, "application/json; charset=utf-8", w.Header().Get("Content-Type"))
}

รันจริงแล้วได้แบบนี้ (ผมใส่ t.Logf เพิ่มเพื่อพิมพ์ค่าดิบออกมาให้ดูด้วย):

$ go test -v -run TestGetUser_Basic .
=== RUN   TestGetUser_Basic
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /users/:id                --> check.GetUser (1 handlers)
[GIN-debug] POST   /users                    --> check.CreateUser (1 handlers)
    basic_test.go:17: w.Code            = 200
    basic_test.go:18: w.Body.String()   = "{\"id\":\"1\",\"name\":\"Somchai\"}"
    basic_test.go:19: w.Header()        = map[Content-Type:[application/json; charset=utf-8] X-Course:[go-day8]]
    basic_test.go:20: Content-Type      = "application/json; charset=utf-8"
    basic_test.go:21: X-Course          = "go-day8"
    basic_test.go:22: w.Result().Status = "200 OK"
--- PASS: TestGetUser_Basic (0.00s)
PASS
ok  	check	0.322s

0.322 วินาที รวมเวลาคอมไพล์ — และไม่มี port ไหนถูกจองเลยแม้แต่พอร์ตเดียว นี่คือทั้งหมดของบทนี้จริง ๆ ที่เหลือคือรายละเอียดว่าจะอ่านผลลัพธ์ให้ถูกได้ยังไง

4 · กับดักตัวแรก: recorder เป็นของใช้ครั้งเดียว

// func TestReuseRecorder(t *testing.T) {  router := NewRouter()
w := httptest.NewRecorder()

router.ServeHTTP(w, httptest.NewRequest("GET", "/users/1", nil))
t.Logf("ครั้งที่ 1: code=%d body=%s", w.Code, w.Body.String())

router.ServeHTTP(w, httptest.NewRequest("GET", "/users/999", nil))
t.Logf("ครั้งที่ 2 (recorder เดิม): code=%d body=%s", w.Code, w.Body.String())

// แล้วยิงเคสเดิมซ้ำอีกรอบ คราวนี้สร้าง recorder ใหม่ ไว้เทียบกัน
w2 := httptest.NewRecorder()
router.ServeHTTP(w2, httptest.NewRequest("GET", "/users/999", nil))
t.Logf("ครั้งที่ 2 (recorder ใหม่): code=%d body=%s", w2.Code, w2.Body.String())

// func TestDefaultCode(t *testing.T) {
w := httptest.NewRecorder()
t.Logf("recorder ที่ยังไม่ถูกเขียน: w.Code = %d", w.Code)

=== RUN   TestReuseRecorder
    traps_test.go:14: ครั้งที่ 1: code=200 body={"id":"1","name":"Somchai"}
    traps_test.go:18: ครั้งที่ 2 (recorder เดิม): code=200 body={"id":"1","name":"Somchai"}{"error":"user not found"}
    traps_test.go:23: ครั้งที่ 2 (recorder ใหม่): code=404 body={"error":"user not found"}
--- PASS: TestReuseRecorder (0.00s)

=== RUN   TestDefaultCode
    traps_test.go:40: recorder ที่ยังไม่ถูกเขียน: w.Code = 200
--- PASS: TestDefaultCode (0.00s)

5 · assert.JSONEq ไม่ใช่ของหรู มันคือของจำเป็น

body ที่ handler ตอบมาเป็นสตริง แต่สิ่งที่เราสนใจจริง ๆ คือข้อมูล
ระหว่าง {"id":"1","name":"Somchai"} กับ { "name": "Somchai", "id": "1" } — สำหรับ client สองอันนี้เหมือนกันทุกประการ แต่สำหรับ == มันคนละเรื่อง

got := w.Body.String()   // = {"id":"1","name":"Somchai"}
expected := `{ "name": "Somchai", "id": "1" }`
assert.Equal(t, expected, got)

    Error:      	Not equal:
                	expected: "{ \"name\": \"Somchai\", \"id\": \"1\" }"
                	actual  : "{\"id\":\"1\",\"name\":\"Somchai\"}"

                	Diff:
                	--- Expected
                	+++ Actual
                	@@ -1 +1 @@
                	-{ "name": "Somchai", "id": "1" }
                	+{"id":"1","name":"Somchai"}
--- FAIL: TestCompareJSON (0.00s)

got := w.Body.String()   // ก้อนเดียวกันเป๊ะกับฝั่งซ้าย
expected := `{ "name": "Somchai", "id": "1" }`
assert.JSONEq(t, expected, got)

(ไม่มี error รายงานออกมาเลย = ผ่าน)

ทั้งสองบล็อกข้างบนรันกับ body ก้อนเดียวกันคือ {"id":"1","name":"Somchai"} ต่างกันแค่ฟังก์ชันที่ใช้เทียบเท่านั้น
ทำไมเรื่องนี้สำคัญกว่าที่คิด: ลำดับ key ใน JSON ไม่ใช่สิ่งที่คุณควบคุมได้
gin.H คือ map ซึ่ง Go ไม่รับประกันลำดับ วันที่คุณเปลี่ยน handler จากตอบ struct มาเป็นตอบ gin.H (หรือกลับกัน) ลำดับ key ก็เปลี่ยนตาม — เทสที่ใช้ Equal จะพังทั้งแผงทั้งที่ API ตอบข้อมูลเดิมเป๊ะ
สรุปสั้น ๆ: body ที่เป็น JSON ให้ใช้ JSONEq เสมอ · Equal เก็บไว้ใช้กับ w.Code และ header ซึ่งเป็นค่าเดี่ยว ๆ ไม่มีเรื่องลำดับ

6 · table-driven: 200 / 400 / 404 ในลูปเดียว

ตอนนี้ต่อจิ๊กซอว์ได้แล้ว — เอาโครง table-driven จาก บทเรียน 16 มาครอบ: แต่ละแถวคือ "หนึ่ง request หนึ่งคำตอบที่คาดไว้"

// ในไฟล์ table_test.go — package เดียวกับ app.go
// import เพิ่มจากหัวข้อ 3 อีกสองตัว: "net/http" และ "strings"
router := NewRouter()   // สร้างครั้งเดียว ใช้ได้ทุกเคส (เหตุผลอยู่ในกล่องถัดไป)

tests := []struct {
    name       string
    method     string
    path       string
    body       string
    wantCode   int
    wantJSON   string
    wantSubstr string
}{
    {name: "200 เจอ user", method: http.MethodGet, path: "/users/1",
        wantCode: http.StatusOK, wantJSON: `{"id":"1","name":"Somchai"}`},
    {name: "404 ไม่เจอ user", method: http.MethodGet, path: "/users/999",
        wantCode: http.StatusNotFound, wantJSON: `{"error":"user not found"}`},
    {name: "400 body ไม่ผ่าน validation", method: http.MethodPost, path: "/users",
        body:     `{"name":"","email":"ไม่ใช่อีเมล"}`,
        wantCode: http.StatusBadRequest, wantSubstr: "Field validation"},
}

for _, tc := range tests {
    t.Run(tc.name, func(t *testing.T) {
        var req *http.Request
        if tc.body == "" {
            req = httptest.NewRequest(tc.method, tc.path, nil)
        } else {
            req = httptest.NewRequest(tc.method, tc.path, strings.NewReader(tc.body))
            req.Header.Set("Content-Type", "application/json")
        }
        w := httptest.NewRecorder()          // recorder ใหม่ทุกเคส (หัวข้อ 4)
        router.ServeHTTP(w, req)
        require.Equal(t, tc.wantCode, w.Code, "body=%s", w.Body.String())

        // แถวไหนกรอก wantJSON ไว้ก็เทียบทั้งก้อน แถวไหนกรอก wantSubstr ก็เทียบแค่ชิ้นส่วน
        if tc.wantJSON != "" {
            assert.JSONEq(t, tc.wantJSON, w.Body.String())
        }
        if tc.wantSubstr != "" {
            assert.Contains(t, w.Body.String(), tc.wantSubstr)
        }
        t.Logf("code=%d body=%s", w.Code, w.Body.String())
    })
}

=== RUN   TestUserHandlers_Table
=== RUN   TestUserHandlers_Table/200_เจอ_user
    table_test.go:69: code=200 body={"id":"1","name":"Somchai"}
=== RUN   TestUserHandlers_Table/404_ไม่เจอ_user
    table_test.go:69: code=404 body={"error":"user not found"}
=== RUN   TestUserHandlers_Table/400_body_ไม่ผ่าน_validation
    table_test.go:69: code=400 body={"error":"Key: 'CreateUserReq.Name' Error:Field validation for 'Name' failed on the 'required' tag\nKey: 'CreateUserReq.Email' Error:Field validation for 'Email' failed on the 'email' tag"}
--- PASS: TestUserHandlers_Table (0.00s)
    --- PASS: TestUserHandlers_Table/200_เจอ_user (0.00s)
    --- PASS: TestUserHandlers_Table/404_ไม่เจอ_user (0.00s)
    --- PASS: TestUserHandlers_Table/400_body_ไม่ผ่าน_validation (0.00s)

7 · gin.SetMode(gin.TestMode) — ทำให้ output อ่านออก

สังเกต output ในหัวข้อ 3: มี [GIN-debug] โผล่มาสี่ห้าบรรทัดทุกครั้งที่สร้าง router ถ้ามี 30 เทสก็คูณ 30 — หา --- FAIL ไม่เจอเลย
ทางแก้คือใส่ TestMain ไว้ไฟล์เดียวใน package (Go จะเรียกมันก่อนเทสทุกตัว):

func TestMain(m *testing.M) {
    gin.SetMode(gin.TestMode)
    os.Exit(m.Run())
}

ผมรันไฟล์เดียวกัน 3 โหมดเทียบกัน — ไฟล์นี้ใช้ router จิ๋ว ๆ อีกตัวที่ยิง /users/7 แล้วตอบ {"id":"7"} กลับมา (ไม่เกี่ยวกับ db ในหัวข้อ 2) ที่ต้องดูคือคอลัมน์สุดท้ายสองคอลัมน์ ไม่ใช่ตัวเลข 7:

8 · ต่อยอดจาก mock — เทส handler ที่ต้องใช้ DB โดยไม่มี DB

ตัวอย่างที่ผ่านมาใช้ map เป็นฐานข้อมูล ซึ่งของจริงไม่เป็นแบบนั้น
แต่จำ บทเรียน 28 ได้ไหม — ถ้า handler ไม่ได้เรียก DB ตรง ๆ แต่เรียกผ่าน interface เราก็สลับตัวจริงเป็น mock ได้ทั้งดุ้น:

var ErrNotFound = errors.New("user not found")   // sentinel error ที่ errors.Is เอาไว้เทียบ

type UserService interface {
    GetUser(id string) (User, error)
}

type Handler struct{ svc UserService }

func (h *Handler) GetUser(c *gin.Context) {
    u, err := h.svc.GetUser(c.Param("id"))
    if errors.Is(err, ErrNotFound) {
        c.JSON(http.StatusNotFound, gin.H{"error": "user not found"})
        return
    }
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": "internal error"})
        return
    }
    c.JSON(http.StatusOK, u)
}

ฝั่งเทสสั่ง mock ว่า "ถ้าถูกถามด้วย id นี้ ให้ตอบแบบนี้" แล้วยิงผ่าน recorder เหมือนเดิมทุกอย่าง:

svc := new(MockUserService)
svc.On("GetUser", "1").Return(User{ID: "1", Name: "Somchai"}, nil)
svc.On("GetUser", "999").Return(User{}, ErrNotFound)

router := NewRouter(&Handler{svc: svc})

t.Run("200", func(t *testing.T) {
    w := httptest.NewRecorder()
    router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/users/1", nil))
    require.Equal(t, 200, w.Code)
    assert.JSONEq(t, `{"id":"1","name":"Somchai"}`, w.Body.String())
})

t.Run("404", func(t *testing.T) {
    w := httptest.NewRecorder()
    router.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/users/999", nil))
    require.Equal(t, 404, w.Code)
    assert.JSONEq(t, `{"error":"user not found"}`, w.Body.String())
})

svc.AssertExpectations(t)

FAIL: 1 out of 2 expectation(s) were met.
	The code you are testing needs to make 1 more call(s).

และของแถมที่ทำได้เฉพาะตอนใช้ mock — สั่งให้ "DB ล่ม" ได้ตามสั่ง ซึ่งกับ DB จริงคุณต้องไปถอดสาย:

svc.On("GetUser", "1").Return(User{},
    errors.New("dial tcp 127.0.0.1:5432: connect: connection refused"))

// สร้าง router + recorder แล้วยิง GET /users/1 เหมือนเดิมเป๊ะ ไม่มีอะไรพิเศษ
require.Equal(t, 500, w.Code)
assert.JSONEq(t, `{"error":"internal error"}`, w.Body.String())

$ go test -v -count=1 .
=== RUN   TestGetUser_WithMock
=== RUN   TestGetUser_WithMock/200
=== RUN   TestGetUser_WithMock/404
--- PASS: TestGetUser_WithMock (0.00s)
    --- PASS: TestGetUser_WithMock/200 (0.00s)
    --- PASS: TestGetUser_WithMock/404 (0.00s)
=== RUN   TestGetUser_ServiceDown
--- PASS: TestGetUser_ServiceDown (0.00s)
PASS
ok  	w40	0.493s

svc := new(MockUserService)     // ไม่ได้ .On อะไรเลย

r := gin.New()
r.Use(gin.Recovery())
r.GET("/users/:id", (&Handler{svc: svc}).GetUser)

w := httptest.NewRecorder()
r.ServeHTTP(w, httptest.NewRequest(http.MethodGet, "/users/1", nil))
t.Logf("code=%d body=%q", w.Code, w.Body.String())

=== RUN   TestPanicUnderRecovery

2026/08/20 22:04:22 [Recovery] 2026/08/20 - 22:04:22 panic recovered:

assert: mock: I don't know what to return because the method call was unexpected.
	Either do Mock.On("GetUser").Return(...) first, or remove the GetUser() call.
	This method was unexpected:
		GetUser(string)
		0: "1"
   ...(stack trace อีกยาว)...
    recover_test.go:20: code=500 body=""
--- PASS: TestPanicUnderRecovery (0.00s)
PASS

9 · แล้ว httptest.NewServer ล่ะ ใช้เมื่อไหร่

httptest ยังมีอีกตัวที่คนมักสับสน — NewServer ซึ่งเปิด port จริง:

// NewRouter() ตัวเดิมจากหัวข้อ 2 (แบบไม่รับพารามิเตอร์)
srv := httptest.NewServer(NewRouter())
defer srv.Close()

resp, err := http.Get(srv.URL + "/users/1")
require.NoError(t, err)          // ตกบรรทัดนี้ = คอมไพล์ไม่ผ่าน "declared and not used: err"
defer resp.Body.Close()

body, _ := io.ReadAll(resp.Body)  // ไม่มี w.Body.String() ให้ใช้แล้ว ต้องอ่านเอง
require.Equal(t, 200, resp.StatusCode)
assert.JSONEq(t, `{"id":"1","name":"Somchai"}`, string(body))

=== RUN   TestNewServer
    server_test.go:17: srv.URL = http://127.0.0.1:54791
    server_test.go:18: srv.Listener.Addr().Network() = tcp
    server_test.go:24: resp.Status="200 OK" body={"id":"1","name":"Somchai"}
    server_test.go:25: resp.Proto="HTTP/1.1" Content-Type="application/json; charset=utf-8"
--- PASS: TestNewServer (0.00s)

เลือกยังไง — ถามว่า "สิ่งที่ผมกำลังเทสคือฝั่งไหนของสาย"
เทส handler ของเราเอง (ราว 95% ของเคส) → NewRecorder เพราะเร็วกว่าและ assert ง่ายกว่า
ใช้ NewServer เมื่อ: อยากเทส client ที่เราเขียนเอง · ทำ fake external API ให้โค้ดเราเรียก (พอร์ตสุ่ม แต่ srv.URL บอกให้เอง จึงเอาไปยัดใส่ config ของ client ได้) · หรือเทสเรื่องที่ http.Client เป็นคนจัดการอย่าง redirect กับ cookie

10 · กับดักที่เหลือ (ทุกข้อรันเจอมาแล้วจริง)

$ go test -v -run TestGetUser_Basic ./...
# check
.../testify@v1.12.1/assert/yaml/yaml_default.go:31:8: missing go.sum entry for module
providing package go.yaml.in/yaml/v3 (imported by github.com/stretchr/testify/assert/yaml);
to add:
	go get github.com/stretchr/testify/assert/yaml@v1.12.1
FAIL	check [setup failed]

    traps_test.go:30: code=404 body="404 page not found" Content-Type="text/plain"
    traps_test.go:34: method ผิด: code=404 body="404 page not found"

=== RUN   TestCallHandlerDirectly/ไม่ผ่าน_router,_ไม่ใส่_Params
    direct_test.go:16: c.Param("id") = "" (len=0)
    direct_test.go:18: code=404 body={"error":"user not found"}
=== RUN   TestCallHandlerDirectly/ไม่ผ่าน_router_แต่ยัด_c.Params_เอง
    direct_test.go:26: c.Param("id") = "1"
    direct_test.go:28: code=200 body={"id":"1","name":"Somchai"}

w := httptest.NewRecorder()
c, _ := gin.CreateTestContext(w)   // ตัวที่ 2 ที่ทิ้งไปคือ *gin.Engine เปล่า ๆ
c.Request = httptest.NewRequest("GET", "/users/1", nil)
c.Params = gin.Params{{Key: "id", Value: "1"}}   // <- บรรทัดนี้ขาดไม่ได้
GetUser(c)

ทดสอบความเข้าใจ

go mod init check
go get github.com/gin-gonic/gin github.com/stretchr/testify
go mod tidy

{"error":"Key: 'CreateUserReq.Name' Error:Field validation for 'Name' failed on the 'required' tag\nKey: 'CreateUserReq.Email' Error:Field validation for 'Email' failed on the 'email' tag"}

อ้างอิง

• pkg.go.dev — net/http/httptest — NewRecorder, NewRequest, NewServer อยู่ครบในหน้าเดียว
• pkg.go.dev — ResponseRecorder — เอกสารระบุเองว่า Code เริ่มต้นที่ 200
• pkg.go.dev — http.Handler — interface method เดียวที่ทำให้ทั้งบทนี้เป็นไปได้
• Gin — Testing · pkg.go.dev — gin.CreateTestContext
• testify — assert.JSONEq · testify — mock
• บทเรียน 16 — table-driven test · บทเรียน 28 — mockery — สองบทที่บทนี้เอามาต่อกัน