httptest para Pruebas de Integración de Handlers

El paquete net/http/httptest prueba handlers HTTP sin configuración manual de TCP.

ResponseRecorder soporta pruebas rápidas de handlers estilo unitario; NewServer soporta pruebas de integración que ejercitan viajes de ida y vuelta reales de http.Client.

Resumen

Las pruebas de handlers deben verificar códigos de estado, cabeceras y cuerpos contra el comportamiento esperado.

httptest.NewRequest construye valores *http.Request con método, URL y cuerpo.

httptest.ResponseRecorder implementa http.ResponseWriter y registra lo que el handler escribió.

httptest.NewServer envuelve un handler con un http.Server efímero y devuelve una URL base para llamadas de cliente.

Las pruebas basadas en tablas mantienen las matrices de rutas mantenibles.

Receta

Tarjeta de receta de referencia rápida - lista para copiar y pegar.

func TestHandler(t *testing.T) {
    req := httptest.NewRequest(http.MethodPost, "/items", strings.NewReader(`{"name":"a"}`))
    req.Header.Set("Content-Type", "application/json")
    rec := httptest.NewRecorder()
 
    handler(rec, req)
 
    if rec.Code != http.StatusCreated {
        t.Fatalf("status=%d body=%s", rec.Code, rec.Body.String())
    }
}

Cuándo usar esto:

• Para verificar que los handlers devuelven el estado correcto, el tipo de contenido y la forma JSON.
• Para probar rutas de acceso directo de middleware (401, 403) sin ejecutar un servidor.
• Para ejercitar la integración completa cliente/servidor con listeners locales sin TLS.

Ejemplo Funcional

package main
 
import (
    "encoding/json"
    "io"
    "net/http"
    "net/http/httptest"
    "strings"
    "testing"
)
 
type item struct {
    Name string `json:"name"`
}
 
func itemsHandler(w http.ResponseWriter, r *http.Request) {
    switch r.Method {
    case http.MethodGet:
        w.Header().Set("Content-Type", "application/json")
        _ = json.NewEncoder(w).Encode([]item{{Name: "seed"}})
    case http.MethodPost:
        var in item
        if err := json.NewDecoder(r.Body).Decode(&in); err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        w.Header().Set("Content-Type", "application/json")
        w.WriteHeader(http.StatusCreated)
        _ = json.NewEncoder(w).Encode(in)
    default:
        http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
    }
}
 
func TestItemsHandler_recorder(t *testing.T) {
    tests := []struct {
        name   string
        method string
        body   string
        want   int
    }{
        {"get ok", http.MethodGet, "", http.StatusOK},
        {"post ok", http.MethodPost, `{"name":"x"}`, http.StatusCreated},
        {"post bad json", http.MethodPost, `{`, http.StatusBadRequest},
        {"patch not allowed", http.MethodPatch, "", http.StatusMethodNotAllowed},
    }
 
    for _, tc := range tests {
        t.Run(tc.name, func(t *testing.T) {
            var body io.Reader
            if tc.body != "" {
                body = strings.NewReader(tc.body)
            }
            req := httptest.NewRequest(tc.method, "/items", body)
            if tc.body != "" {
                req.Header.Set("Content-Type", "application/json")
            }
            rec := httptest.NewRecorder()
            itemsHandler(rec, req)
            if rec.Code != tc.want {
                t.Fatalf("got %d want %d body=%q", rec.Code, tc.want, rec.Body.String())
            }
        })
    }
}
 
func TestItemsHandler_newServer(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(itemsHandler))
    defer srv.Close()
 
    resp, err := http.Get(srv.URL + "/items")
    if err != nil {
        t.Fatal(err)
    }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        t.Fatalf("status=%d", resp.StatusCode)
    }
}

Lo que esto demuestra:

• Pruebas basadas en tablas con ResponseRecorder para invocación directa de handlers.
• Configuración de cuerpo JSON a través de strings.NewReader en NewRequest.
• Cobertura de ramas de método no permitido.
• Prueba black-box de httptest.NewServer usando http.Get contra srv.URL.

Análisis Profundo

Cómo Funciona

• NewRecorder devuelve un ResponseRecorder con los campos Code, Header y Body poblados después de ServeHTTP.
• NewRequest establece URL.Path y Host adecuados para el código del handler que lee r.URL y r.Host.
• NewServer elige un puerto libre, comienza a escuchar en una goroutine y bloquea el apagado hasta Close().
• NewTLSServer proporciona TLS para probar rutas de validación de certificados.

Patrones de Prueba

Notas de Go

// Afirma JSON sin comparaciones de cadenas frágiles:
var got item
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
    t.Fatal(err)
}
 
// Ejecuta pruebas de servidor en paralelo con su propio srv:
t.Parallel()
srv := httptest.NewServer(handler)
t.Cleanup(srv.Close)

Errores Comunes

• No llamar a Close() en NewServer - Fugas de goroutines y puertos en ejecuciones de prueba repetidas. Solución: defer srv.Close() o t.Cleanup(srv.Close).
• Reutilizar mux global entre pruebas - Las registraciones de rutas compiten con t.Parallel. Solución: Crear un http.NewServeMux() nuevo por prueba o usar t.Parallel solo con handlers aislados.
• Comparar cadenas JSON completas - El orden de los campos no es estable. Solución: Deserializar a estructuras o usar comparaciones de json.RawMessage.
• Olvidar Content-Type en POST - Los errores del decodificador enmascaran errores de lógica del handler. Solución: Establecer cabeceras en las pruebas exactamente como lo harían los clientes.
• Usar http.DefaultClient sin tiempo de espera en pruebas - Pruebas colgadas si el servidor se detiene. Solución: http.Client{Timeout: ...} corto en pruebas de integración.
• Asumir que rec.Code por defecto es 200 - Cero significa no establecido hasta WriteHeader o la primera Write. Solución: Comprobar Code después de que el handler devuelva; el valor por defecto es 200 solo después de escribir.

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1x20213x1v1t1v1z1t20

Alternativas

Preguntas Frecuentes

Relacionado

• Conceptos Básicos de net/http - ejemplo introductorio de recorder
• Servidores HTTP, Handlers y Patrones de ServeMux - pruebas de enrutamiento de mux
• Cadenas de Middleware y Contexto de Petición - patrones de prueba de middleware
• Pruebas de Código que Acepta context.Context - ctx en handlers
• Clientes HTTP, Transporte y Agrupación de Conexiones - tiempos de espera del cliente en pruebas

Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, go fix modernizers - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación), y golangci-lint (última - verificar conjunto de linters en la compilación).