httptest para Testes de Integração de Handlers

O pacote net/http/httptest testa handlers HTTP sem configuração manual de TCP.

ResponseRecorder suporta testes rápidos de handler no estilo unitário; NewServer suporta testes de integração que exercitam viagens de ida e volta reais do http.Client.

Resumo

Testes de handler devem assertar códigos de status, cabeçalhos e corpos contra o comportamento esperado.

httptest.NewRequest constrói valores *http.Request com método, URL e corpo.

httptest.ResponseRecorder implementa http.ResponseWriter e registra o que o handler escreveu.

httptest.NewServer envolve um handler com um http.Server efêmero e retorna uma URL base para chamadas de cliente.

Testes orientados por tabela mantêm matrizes de rotas manuteníveis.

Receita

Cartão de receita de referência rápida - pronto para copiar e colar.

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())
    }
}

Quando usar isso:

• Verificando se os handlers retornam status, tipo de conteúdo e formato JSON corretos.
• Testando caminhos de curto-circuito de middleware (401, 403) sem executar um servidor.
• Exercitando a integração completa cliente/servidor com listeners locais sem TLS.

Exemplo de Trabalho

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)
    }
}

O que isso demonstra:

• Testes orientados por tabela com ResponseRecorder para invocação direta de handler.
• Configuração de corpo JSON via strings.NewReader em NewRequest.
• Cobertura de branch de método não permitido.
• Teste black-box httptest.NewServer usando http.Get contra srv.URL.

Mergulho Profundo

Como Funciona

• NewRecorder retorna um ResponseRecorder com os campos Code, Header e Body preenchidos após ServeHTTP.
• NewRequest define URL.Path e Host adequados para código de handler que lê r.URL e r.Host.
• NewServer seleciona uma porta livre, começa a escutar em uma goroutine e bloqueia o desligamento em Close().
• NewTLSServer fornece TLS para testar caminhos de validação de certificado.

Padrões de Teste

Notas Go

// Assert JSON sem comparações de string frágeis:
var got item
if err := json.Unmarshal(rec.Body.Bytes(), &got); err != nil {
    t.Fatal(err)
}
 
// Execute testes de servidor em paralelo com seu próprio srv:
t.Parallel()
srv := httptest.NewServer(handler)
t.Cleanup(srv.Close)

Armadilhas

• Não chamar Close() em NewServer - Vazamentos de goroutines e portas em execuções de teste repetidas. Correção: defer srv.Close() ou t.Cleanup(srv.Close).
• Reutilizar mux global entre testes - Registro de rotas entra em conflito com t.Parallel. Correção: Crie um http.NewServeMux() novo por teste ou use t.Parallel apenas com handlers isolados.
• Comparar strings JSON inteiras - A ordem dos campos não é estável. Correção: Deserializar para structs ou usar comparações de json.RawMessage.
• Esquecer Content-Type em POST - Erros do decodificador mascaram bugs na lógica do handler. Correção: Defina cabeçalhos nos testes exatamente como os clientes fariam.
• Usar http.DefaultClient sem timeout em testes - Testes travam se o servidor parar. Correção: http.Client{Timeout: ...} curto em testes de integração.
• Assumir que rec.Code é 200 por padrão - Zero significa não definido até WriteHeader ou o primeiro Write. Correção: Verifique Code após o retorno do handler; o padrão é 200 apenas após a escrita.

383k393a3c3q3e393a3o1r3e3k3x383c3e3k1x20213x1v1t1v1z1t20

Alternativas

FAQs

Relacionados

• Noções Básicas de net/http - exemplo introdutório de recorder
• Servidores HTTP, Handlers e Padrões ServeMux - testes de roteamento de mux
• Cadeias de Middleware e Contexto de Requisição - padrões de teste de middleware
• Testando Código Que Aceita context.Context - ctx em handlers
• Clientes HTTP, Transporte e Pooling de Conexão - timeouts de cliente em testes

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão GC Green Tea, go fix modernizers - verifique o patch na compilação), chi (última - verifique na compilação), gin (última - verifique na compilação), echo (última - verifique na compilação), google.golang.org/grpc (última - verifique na compilação), sigs.k8s.io/controller-runtime (última - verifique na compilação), kubebuilder (última - verifique na compilação), tinygo (última - verifique os alvos de placa na compilação), wazero (última - verifique na compilação) e golangci-lint (última - verifique o conjunto de linters na compilação).