Skill de Testes e Benchmarks em Go

Scaffolding de testes baseados em tabelas e fuzzing para agentes - uma Agent Skill no estilo cookbook para geração de testes em Go 1.26 a partir de critérios de aceitação.

O Que Esta Skill Faz

Produz scaffolds de testes: subtestes t.Run baseados em tabelas, casos de httptest, sementes F.Add de fuzzing e stubs de benchmark - com comandos de verificação go test, não reescritas de código de produção.

Quando Invocar

• Agente solicitado a "adicionar testes" sem estrutura
• Novo pacote precisa de cobertura baseada em tabelas a partir de itens de AC
• Alvo de fuzzing necessário para parsers de string/JSON
• Stub de benchmark antes do trabalho de performance (pareia com Skill de Profiling de Performance em Go)
• PR carece de subtestes para branches de erro

Entradas

Saídas

• Scaffold *_test.go com slice de tabela e subtestes
• FuzzXxx opcional com sementes de corpus
• BenchmarkXxx opcional com b.Loop (estilo Go 1.24+) ou loop clássico
• Comandos: go test ./pkg/..., go test -race, go test -fuzz=FuzzParse -fuzztime=30s

Guardrails

1. Teste o comportamento, não helpers não exportados, a menos que a política de white-box do mesmo pacote permita.
2. Não use time.Sleep para sincronização - use canais, synctest ou interfaces.
3. Subtestes paralelos apenas quando isolados - t.Parallel() documentado por caso.
4. Fuzz apenas parsers puros - sem rede/DB no alvo de fuzz sem configuração pesada.
5. Execute os testes antes de entregar o scaffold - deve compilar.
6. Arquivos Golden - atualize com o padrão de flag -update explícito por política da equipe.

Receita

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

func TestParseID(t *testing.T) {
    tests := []struct {
        name    string
        in      string
        want    string
        wantErr bool
    }{
        {name: "valid", in: "abc-123", want: "abc-123"},
        {name: "empty", in: "", wantErr: true},
        {name: "spaces", in: "  ", wantErr: true},
    }
    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            got, err := ParseID(tt.in)
            if tt.wantErr {
                if err == nil {
                    t.Fatal("expected error")
                }
                return
            }
            if err != nil {
                t.Fatalf("unexpected: %v", err)
            }
            if got != tt.want {
                t.Fatalf("got %q want %q", got, tt.want)
            }
        })
    }
}

go test ./internal/parse/... -count=1
go test -race ./internal/parse/...   # se o pacote usa goroutines

Quando usar esta skill:

• Lista de AC do PM precisa de subtestes mapeados antes do merge
• Agente produziu uma única função TestEverything gigante
• Pacote de parser precisa de fuzz antes da revisão de segurança

Exemplo de Trabalho

Passo 0 - Mapear AC para casos

AC:
- UUID válido retorna forma normalizada
- UUID inválido retorna ErrInvalid
- Entrada vazia retorna ErrEmpty

Cada item se torna o nome do t.Run e a linha da tabela.

Passo 1 - Teste de handler com httptest

func TestGetUserHandler(t *testing.T) {
    srv := httptest.NewServer(http.HandlerFunc(getUser))
    t.Cleanup(srv.Close)
 
    resp, err := http.Get(srv.URL + "/users/1")
    if err != nil {
        t.Fatal(err)
    }
    defer resp.Body.Close()
    if resp.StatusCode != http.StatusOK {
        t.Fatalf("status %d", resp.StatusCode)
    }
}

• Prefira testar o handler via httptest.NewRecorder para escopo de unidade
• Veja httptest para Testes de Integração de Handler

Passo 2 - Scaffold de fuzz

func FuzzParseID(f *testing.F) {
    f.Add("abc-123")
    f.Add("")
    f.Fuzz(func(t *testing.T, in string) {
        _, _ = ParseID(in) // não deve entrar em pânico; documentar invariantes
    })
}

go test -fuzz=FuzzParseID -fuzztime=30s ./internal/parse/

Passo 3 - Stub de benchmark

func BenchmarkParseID(b *testing.B) {
    for b.Loop() {
        _, _ = ParseID("abc-123")
    }
}

go test -bench=BenchmarkParseID -benchmem ./internal/parse/ -count=5

Análise Profunda

testify / cmp: se a equipe usa github.com/stretchr/testify, a skill importa require por ADR.

Caso contrário, as asserções apenas da biblioteca padrão mantêm as dependências mínimas.

Exemplos (ExampleXxx): para snippets verificados por godoc - veja Exemplos como Documentação Executável.

Cobertura: go test -cover ./... para relatório; a skill não busca 100% no scaffold gerado.

Tags de Build: testes de integração atrás de //go:build integration - a skill separa tabelas rápidas de unidade de testes de integração lentos.

Armadilhas

• Nome de subteste com / quebra a regex -run - use nomes seguros.
• Variável de loop em subtestes paralelos - capture tt := tt antes de t.Parallel().
• Fuzz em funções que mutam estado global - isole ou pule o fuzz.
• Benchmark sem resetar a entrada - distorce as medições de alocação.

Alternativas

FAQs

Relacionados

• Fundamentos de Agent Skills - estrutura do SKILL.md
• Fundamentos de Testes em Go - introdução a testes
• Testes Baseados em Tabelas e Subtestes - padrões
• Fuzz Testing com testing.F - referência de fuzzing
• Benchmarks com testing.B e b.Loop - benchmarks
• testify, httptest e Test Doubles - doubles

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 (latest - verifique na compilação), gin (latest - verifique na compilação), echo (latest - verifique na compilação), google.golang.org/grpc (latest - verifique na compilação), sigs.k8s.io/controller-runtime (latest - verifique na compilação), kubebuilder (latest - verifique na compilação), tinygo (latest - verifique os alvos de placa na compilação), wazero (latest - verifique na compilação) e golangci-lint (latest - verifique o conjunto de linters na compilação).