Testando Código Que Aceita context.Context

Funções que aceitam context.Context precisam de testes para sucesso, deadline excedido e cancelamento manual - não apenas o caminho feliz.

O pacote context do Go e os helpers de testing tornam esses caminhos determinísticos sem dormir em CI.

Resumo

Use context.WithTimeout ou WithCancel em testes para gerar resultados de ctx.Err().

Prefira fakes baseados em canais em vez de time.Sleep ao testar a propagação de cancelamento.

Asserte com errors.Is para context.Canceled e context.DeadlineExceeded.

Receita

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

func TestWorkCanceled(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    cancel()
 
    err := Work(ctx)
    if !errors.Is(err, context.Canceled) {
        t.Fatalf("got %v, want Canceled", err)
    }
}

Quando usar isso:

• Teste em tabela os resultados de ctx juntamente com entradas normais.
• Use timeouts curtos (milissegundos) em vez de sleeps de vários segundos.
• Teste manipuladores HTTP com httptest e contextos de requisição.

Exemplo de Trabalho

package work_test
 
import (
    "context"
    "errors"
    "testing"
    "time"
 
    "example.com/ctxdemo/work"
)
 
func TestFetchDeadline(t *testing.T) {
    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
    defer cancel()
 
    err := work.Fetch(ctx, slowStub{})
    if !errors.Is(err, context.DeadlineExceeded) {
        t.Fatalf("got %v", err)
    }
}
 
func TestFetchCancel(t *testing.T) {
    ctx, cancel := context.WithCancel(context.Background())
    go func() {
        time.Sleep(5 * time.Millisecond)
        cancel()
    }()
 
    err := work.Fetch(ctx, slowStub{})
    if !errors.Is(err, context.Canceled) {
        t.Fatalf("got %v", err)
    }
}
 
type slowStub struct{}
 
func (slowStub) Run(ctx context.Context) error {
    select {
    case <-time.After(200 * time.Millisecond):
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

O que isso demonstra:

• DeadlineExceeded de um WithTimeout curto sem sleeps longos no caminho de asserção.
• cancel() manual de outra goroutine simula desconexão do cliente.
• A dependência stub respeita ctx da mesma forma que I/O de produção faria.
• errors.Is mantém as asserções estáveis se os erros forem encapsulados com %w.

Mergulho Profundo

Como Funciona

• Testes constroem contextos independentemente de servidores de produção - nenhuma API especial apenas para testes é necessária.
• t.Context() (Go 1.24+) fornece um contexto cancelado quando o teste termina - útil para testes de integração.
• httptest.NewRequest anexa um contexto de background; substitua por req.WithContext(ctx) para casos de cancelamento.
• Relógios falsos raramente são necessários; timeouts abaixo de 50ms mantêm os testes rápidos em CI.

Matriz de Testes

Teste de Manipulador HTTP

req := httptest.NewRequest(http.MethodGet, "/", nil)
ctx, cancel := context.WithCancel(req.Context())
cancel()
req = req.WithContext(ctx)
 
rec := httptest.NewRecorder()
handler(rec, req)
// esperar nenhum corpo de resposta em caso de cancelamento

Notas de Go

func wait(ctx context.Context, d time.Duration) error {
    timer := time.NewTimer(d)
    defer timer.Stop()
    select {
    case <-ctx.Done():
        return ctx.Err()
    case <-timer.C:
        return nil
    }
}

Sempre pare os timers em testes e produção para evitar vazamentos.

Armadilhas

• Dormir para atingir deadlines - Falha em runners de CI sobrecarregados. Correção: use cancel() imediato ou timeouts de 1-20ms.
• Comparar erros com == - Erros encapsulados falham em ==. Correção: errors.Is e errors.As.
• Não chamar cancel em testes - Avisos de vazamento de timer em execuções com -race. Correção: sempre use defer cancel().
• Usar Background em testes de manipulador - Perde o comportamento de desconexão. Correção: injete ctx cancelável via WithContext.
• Testar apenas DeadlineExceeded - Caminhos de cancelamento diferem em logs e métricas. Correção: cubra ambos os erros terminais.
• Compartilhar ctx entre subtestes paralelos - Race em cancel(). Correção: contexto por subteste com cuidado em t.Parallel().

Alternativas

FAQs

Relacionado

• Noções Básicas de Contexto - Primitivas da API sob teste
• Propagação de Cancelamento em Manipuladores HTTP - Conexão do httptest
• Deadlines e Timeouts Entre Limites de Serviço - Lógica de orçamento para asserção
• Contexto em database/sql & gRPC - Comportamento de cancelamento de integração
• Antipadrões de Mau Uso de Contexto - bugs que os testes devem capturar

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