Melhores Práticas de Teste

Orientação da pirâmide de testes para serviços e bibliotecas Go.

Estas regras mantêm os testes Go rápidos, legíveis e confiáveis, desde o go test local até os portões de merge do CI.

Como Usar Esta Lista

• Aplique durante o design e a revisão quando os testes são um pensamento posterior ou o tempo do CI explode.
• Execute go test -race ./... e golangci-lint nos mesmos pacotes que você bloqueia no CI.
• Prefira adicionar uma linha de tabela em vez de uma função de teste única quando o comportamento for parametrizado.
• Revise corpora de fuzzing e arquivos golden sempre que o formato de saída mudar intencionalmente.

A - Estrutura e legibilidade

• Use testes orientados por tabela com subtestes nomeados por padrão. Revisores veem casos como dados; falhas nomeiam a linha via t.Run.
• Mantenha os testes ao lado do código de produção em *_test.go. Mesmo módulo, mesmo refatoramento, mesmos erros de compilação quando as APIs mudam.
• Use t.Helper() em helpers de asserção compartilhados. Falhas apontam para a linha de teste, não para os internos da utilidade.
• Teste o comportamento exportado de package foo_test ao modelar consumidores. Testes internos permanecem em package foo para helpers não exportados.
• Um caminho de asserção lógico por subteste, quando possível. Verificações mistas tornam as falhas mais difíceis de diagnosticar.

B - Velocidade e determinismo

• Tenha como alvo go test ./... em segundos a poucos minutos em laptops. Divida suítes de integração com tags de build ou módulos separados quando necessário.
• Evite time.Sleep para sincronização. Use canais, sync.WaitGroup ou manipuladores httptest controláveis.
• Mock de limites de IO, não de cada função privada. Fakes escritos à mão por trás de interfaces pequenas superam mocks gerados para APIs estreitas.
• Execute go test -count=1 ao depurar falhas. Passes em cache ocultam bugs de ordenação até que o CI seja executado novamente.
• Eleve a configuração do benchmark para fora de b.Loop(). Meça o caminho quente, não a construção de fixtures.

C - HTTP, bancos de dados e serviços

• Use httptest.NewRecorder para testes de unidade de manipuladores. Reserve NewServer quando a pilha do cliente precisar ser executada de verdade.
• Feche resp.Body após cada chamada de cliente em testes. Vazamentos falham sob -count=100 e carga semelhante no CI.
• Limite testes de banco de dados reais a uma fina camada de fumaça. Mantenha testes de lógica de negócios em fakes; use contêineres para integração SQL com moderação.
• Passe r.Context() através de manipuladores em testes. Middleware de cancelamento e prazo só funcionam quando os manipuladores respeitam o contexto.
• Documente quais testes exigem Docker ou rede. Marque com tags de build para que o go test padrão permaneça offline.

D - Sinais de qualidade do CI

• Execute -race em pacotes que geram goroutines ou compartilham caches. Aceite o custo da CPU em agentes de CI Linux.
• Acompanhe a cobertura em pacotes críticos, não em porcentagem global de vaidade. Emparelhe a cobertura com asserções em ramos de erro.
• Confirme crashers de fuzzing e arquivos golden em testdata/. Trate diffs como fixtures de regressão que exigem revisão humana.
• Agende trabalhos de fuzzing limitados (-fuzztime) noturnos ou semanais. Reproduza corpora em cada PR sem fuzz de tempo ilimitado em pipelines de merge.
• Ordem do CI: format/vet/lint, testes unitários, build de race, fumaça de integração. Alinhe com os modelos de portão de qualidade de linting.

E - Documentação e evolução

• Adicione funções Example para uso de API pública copiar e colar. Mantenha os comentários // Output: precisos para que o godoc permaneça verificado.
• Atualize exemplos quando o comportamento exportado mudar. go test falha quando a documentação se desvia.
• Prefira errors.Is / errors.As em linhas de tabela de erro. Erros encapsulados quebram comparações ==.
• Revise a política de require vs assert do testify por equipe. require para pré-condições; assert para verificações independentes.
• Profile antes de micro-otimizar apenas com base em benchmarks. Use pprof em cargas de trabalho realistas após benchstat mostrar uma vitória.

FAQs

Relacionados

• Cultura de Teste Go: Simples, Rápido, Orientado por Tabela - visão geral da seção
• Noções Básicas de Teste Go - exemplos executáveis de introdução
• Cobertura, Detector de Race e Arquivos Golden - sinais de CI em profundidade
• Testes de Fuzzing com testing.F - corpora e fuzzing agendado
• Portões de Qualidade do CI: Lint, Teste, Race, Vuln - ordem completa do pipeline

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