go test, list & generate

go test executa testes de pacotes, go list introspecta o que o sistema de build vê, e go generate aciona hooks de geração de código que você define ao lado dos arquivos de origem.

Resumo

Testes são de primeira classe na toolchain: nenhum runner externo é necessário para testes unitários, benchmarks, exemplos ou alvos de fuzzing.

go list expõe pacotes, dependências, tags e versões de módulos como JSON legível por máquina para scripts e CI.

go generate executa diretivas //go:generate, geralmente chamando ferramentas instaladas com go install.

Juntos, eles formam o loop diário: listar o que existe, gerar o que está desatualizado, testar o que mudou.

Receita

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

# Executa todos os testes com detector de race e cobertura
go test -race -cover ./...
 
# Executa um teste por nome com saída verbosa
go test -run TestParseConfig -v ./internal/config
 
# Lista pacotes como JSON para scripting
go list -json ./...
 
# Executa todos os geradores no módulo
go generate ./...

Quando usar isso:

• Use go test ./... como o portão padrão de CI antes do merge.
• Use templates go list -f para construir relatórios de SBOM ou de propriedade.
• Use go generate após alterar definições de protobuf, stringer ou mock.
• Use go test -bench ao otimizar caminhos críticos com números reproduzíveis.

Exemplo de Trabalho

// mathutil/sum.go
package mathutil
 
func Sum(nums []int) int {
    total := 0
    for _, n := range nums {
        total += n
    }
    return total
}

// mathutil/sum_test.go
package mathutil
 
import "testing"
 
func TestSum(t *testing.T) {
    got := Sum([]int{1, 2, 3})
    if got != 6 {
        t.Fatalf("got %d want 6", got)
    }
}
 
func BenchmarkSum(b *testing.B) {
    data := make([]int, 1000)
    for i := range data {
        data[i] = i
    }
    b.ResetTimer()
    for i := 0; i < b.N; i++ {
        Sum(data)
    }
}

// api/doc.go
package api
 
//go:generate go run golang.org/x/tools/cmd/stringer@latest -type=Kind
 
type Kind int
 
const (
    KindHTTP Kind = iota
    KindGRPC
)

go test -cover ./mathutil
go test -bench=. -benchmem ./mathutil
go list -f '{{.ImportPath}} tags={{.BuildTags}}' ./...
go generate ./api

O que isso demonstra:

• Teste unitário sem tabela com t.Fatalf para falha rápida.
• Benchmark com b.ResetTimer() excluindo o trabalho de configuração.
• go list -f template customizado para scripts de inventário.
• //go:generate colocado ao lado do tipo que ele mantém.

Mergulho Profundo

Como Funciona

• go test compila um main de teste que vincula arquivos _test.go, em seguida, executa o binário e transmite os resultados.
• As chaves de cache de teste incluem hashes de origem, flags e versão do Go; resultados passados são reutilizados, a menos que -count=1.
• go list carrega pacotes sem necessariamente vincular; -json emite structs para automação.
• go generate escaneia linhas //go:generate e executa comandos na ordem dos arquivos; ele não rastreia a obsolescência por si só.

Flags de go test em Resumo

Templates de go list

Regras de go generate

• Diretivas devem começar com //go:generate (sem espaço antes de go).
• Comandos são executados com o diretório do pacote como diretório de trabalho.
• Geradores devem ser idempotentes; comite os outputs ou imponha verificações de git diff na CI.
• Prefira go run tool@version em vez de binários locais não documentados para reprodutibilidade.

Armadilhas

• Assumir que go test sem ./... executa tudo - . nu é apenas o pacote atual. Correção: go test ./... da raiz do módulo.
• Passagem instável em cache para sempre - o cache padrão esconde falhas intermitentes. Correção: go test -count=1 durante a depuração; corrija a causa raiz antes de mesclar.
• Benchmarking sem -benchmem - regressões de alocação permanecem invisíveis. Correção: adicione -benchmem e compare com benchstat.
• go generate na CI sem verificar diffs - o drift mescla silenciosamente. Correção: execute generate em um job que falha com git diff não vazio.
• Confusão de pacote de teste externo - package foo_test não pode acessar símbolos não exportados. Correção: teste a API exportada ou use o pacote de teste interno package foo.
• Análise JSON de list manualmente - fácil de perder novas linhas incorporadas. Correção: use jq na saída de go list -json em scripts.

Alternativas

FAQs

Relacionado

• O Comando go: Ciclo de Vida de Build, Teste e Módulo - pipeline de carregamento compartilhado
• Noções Básicas da Toolchain Go - primeiros exemplos de go test e go list
• Modernizadores go fix & Analisadores go vet - verificações estáticas antes dos testes
• Tags de Build e Compilação Condicional - por que a saída de list difere por tags
• Melhores Práticas da Toolchain Go - hábitos de teste de CI

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