O caso prático da função palíndromo#

Um palíndromo é uma palavra ou frase idêntica lida de trás para frente ("aba", "racecar", "radar"). Veja duas implementações completamente diferentes para o mesmo problema:

1
package palindrome
2

3
// IsPalindrome verifica se uma string é palíndromo comparando os extremos
4
func IsPalindrome(s string) bool {
5
    n := len(s)
6
    for i := 0; i < n/2; i++ {
7
        if s[i] != s[n-1-i] {
8
            return false // Caracteres das pontas não coincidem
9
        }
10
    }
11
    return true
12
}

1
package palindrome
2

3
// IsPalindromeRefactored inverte a string e compara com a original
4
func IsPalindromeRefactored(s string) bool {
5
    runes := []rune(s)
6
    for i, j := 0, len(runes)-1; i < j; i, j = i+1, j-1 {
7
        runes[i], runes[j] = runes[j], runes[i]
8
    }
9
    return string(runes) == s
10
}

Como ter certeza de que as duas produzem exatamente o mesmo resultado para strings vazias, caracteres Unicode, tamanhos par e ímpar? Sem testes automatizados, você apenas espera que funcione. Com eles, você prova que funciona a cada compilação. A sintaxe exata do arquivo abaixo — o sufixo _test.go, o parâmetro t *testing.T, o método t.Errorf — é formalizada na seção 2; por enquanto, repare só na lógica: uma tabela de casos de entrada e saída esperada, comparados um a um:

1
package palindrome
2

3
import "testing"
4

5
func TestIsPalindrome(t *testing.T) {
6
    tests := []struct {
7
        input    string
8
        expected bool
9
    }{
10
        {input: "aba", expected: true},
11
        {input: "racecar", expected: true},
12
        {input: "radar", expected: true},
13
        {input: "golang", expected: false},
14
        {input: "", expected: true},
15
        {input: "a", expected: true},
16
    }
17

18
    for _, tc := range tests {
19
        got := IsPalindrome(tc.input)
20
        if got != tc.expected {
21
            t.Errorf("IsPalindrome(%q) = %t; esperado %t", tc.input, got, tc.expected)
22
        }
23
    }
24
}

Vale notar também que esse mesmo arquivo _test.go funciona como documentação viva: diferente de um wiki ou README manual, que apodrece silenciosamente quando ninguém atualiza a regra de negócio, o teste é código compilado. Se o comportamento mudar e o teste não acompanhar, o build quebra no CI — é a única documentação que não pode mentir.

O ciclo TDD: Red, Green, Refactor#

TDD (Test-Driven Development) é a prática de escrever o teste antes do código de produção, em ciclos curtos. A ideia é simples: você não escreve uma linha de lógica sem antes ter uma forma automática de provar que ela funciona. O ciclo tem três passos, que se repetem indefinidamente:

flowchart LR
    A[RED — teste que falha] --> B[GREEN — código mínimo que passa]
    B --> C[REFACTOR — melhora a estrutura]
    C --> A

1. RED: escreva um teste para uma função que ainda não existe ou não trata aquele caso. Ele falha, obrigatoriamente.
2. GREEN: escreva a menor quantidade de código de produção necessária para o teste passar. Nada além disso.
3. REFACTOR: com a barra verde garantida, limpe o código — remova acoplamento, renomeie, otimize — sabendo que qualquer regressão vai aparecer na hora.

O checklist do que nunca deixar de testar#

• Valores extremos e bordas: strings vazias e gigantescas, caracteres Unicode/emoji, zero, negativos, MaxInt/MinInt, slices e maps vazios ou nil.
• Validação de inputs: e-mails malformados, JSON truncado, datas inválidas.
• Data races: rode a suíte sob concorrência com go test -race.
• Efeitos colaterais: o estado do banco mudou corretamente? os eventos dependentes saíram na ordem certa?
• Fuzzing: bombardeie a função com entradas aleatórias e caóticas para achar crashes que você não previu.

Testes transparentes (white-box) vs. testes opacos (black-box)#

Pense num restaurante: um teste white-box é como entrar na cozinha e checar cada panela; um teste black-box é como um cliente comum, que só vê o prato chegando na mesa e julga pelo resultado. Em Go, essa distinção é controlada pela própria declaração do package:

• White-box (package auth): o arquivo de teste vive no mesmo pacote do código-fonte e enxerga tudo, inclusive funções privadas. Bom para algoritmos internos complexos.
• Black-box (package auth_test): pacote de teste externo, sufixo _test, só enxerga a API pública. Evita acoplamento com detalhes de implementação e testa exatamente como um cliente real consome o pacote.

Boas práticas de design em Go

Dê preferência quase absoluta a testes opacos (package foo_test). Eles garantem que sua suíte não dependa de implementação interna volátil — você pode refatorar o código privado sem quebrar nenhum teste existente.

Um teste unitário também é, na prática, o contrato formal de comportamento que seu pacote assina com o resto do sistema. Brian Kernighan (co-autor de The Go Programming Language) resume o risco de fazer isso mal:

“Os bugs mais difíceis de resolver são aqueles em que o seu modelo mental da situação está errado. Dessa forma, achar o problema se torna impossível.”

O erro comum é escrever testes só para confirmar que o código que você acabou de escrever funciona — o que apenas repete a mesma ideia (possivelmente errada) que você já tinha na cabeça quando escreveu o código. A postura certa é tentar quebrar o programa: procurar ativamente o caso que sua lógica não previu, antes que o usuário o encontre em produção. Dá pra pensar em graus de “quão correto” um software é, numa escala que vai de “compila e não quebra ao ligar” até “trata 100% dos casos de erro previstos na especificação” — sistemas profissionais de alta criticidade miram no meio-para-cima dessa escala, não nos extremos.

A falácia dos 100% de code coverage#

Muita equipe exige 100% de cobertura no CI acreditando que isso garante zero bugs. Não garante, por três razões:

1. Cobertura mede linhas executadas, não comportamento correto — um teste pode passar por 100% do código sem fazer nenhum assert semântico relevante.
2. Você pode cobrir 100% do código implementando a regra de negócio errada. Cobertura não sabe se a lógica está certa, só se ela rodou.
3. Código que você esqueceu de escrever não pode ser coberto. Se faltou uma validação de segurança, a cobertura continua em 100% e a vulnerabilidade continua ativa.

Faixa saudável da indústria

75% a 85% de cobertura, com foco no core de negócio, algoritmos críticos e bordas. O esforço para ir de 85% a 100% custa caro e geralmente só testa getters triviais e boilerplate inócuo — retorno decrescente.

Convenções de nomenclatura#

O compilador e o test runner impõem três regras:

1. Arquivo: precisa terminar em _test.go (ex: tasks_handlers.go → tasks_handlers_test.go). O compilador de produção ignora esses arquivos por completo.
2. Função: precisa começar com Test maiúsculo seguido de nome descritivo (func TestHandleCreateTask(t *testing.T)).
3. Parâmetro: único, obrigatoriamente t *testing.T.

*testing.T: Errorf, Fatalf e Logf#

Você já viu t.Errorf em ação no teste do palíndromo (seção 1). A tabela abaixo mostra os três métodos de *testing.T que fazem o trabalho de reportar o resultado de um teste:

Comandos essenciais#

1
# Executa todos os testes do projeto, recursivamente:
2
go test ./...
3

4
# Saída detalhada de logs (t.Logf):
5
go test -v ./...
6

7
# Executa apenas uma função de teste específica (por regex):
8
go test -v -run TestHandleCreateTask ./internal/api/...
9

10
# Checa condições de corrida concorrente (data races):
11
go test -race ./...
12

13
# Exibe a porcentagem de cobertura de código:
14
go test -cover ./...

O Teste Escrito Antes do Handler (Fase RED)#

Seguindo TDD rigoroso, escrevemos o teste — e o contrato de resposta esperado — antes de existir qualquer implementação. Os handlers vivem como métodos de uma struct Application, que por enquanto não precisa de mais nada além de existir — ela vai ganhar campos reais (como a camada de serviço da próxima seção) só quando o handler realmente precisar deles:

1
package api
2

3
// Application centraliza as dependências dos handlers HTTP
4
type Application struct{}

1
package api
2

3
import (
4
    "bytes"
5
    "encoding/json"
6
    "net/http"
7
    "net/http/httptest"
8
    "testing"
9
)
10

11
func TestHandleCreateTask(t *testing.T) {
12
    // 1. SETUP: Instancia a aplicação em memória
13
    app := Application{}
14

15
    // 2. ARRANGE: Prepara o payload JSON de entrada
16
    payload := map[string]any{
17
        "title":       "Aprender TDD em Go",
18
        "description": "Praticar testes com net/http/httptest",
19
        "priority":    9000,
20
    }
21

22
    bodyBytes, err := json.Marshal(payload)
23
    if err != nil {
24
        t.Fatalf("falha ao serializar payload: %v", err)
25
    }
26

27
    // 3. Cria a requisição HTTP em memória
28
    req := httptest.NewRequest(http.MethodPost, "/api/v1/tasks", bytes.NewReader(bodyBytes))
29
    req.Header.Set("Content-Type", "application/json")
30

31
    // 4. Cria o gravador de resposta (ResponseRecorder)
32
    rec := httptest.NewRecorder()
33

34
    // 5. ACT: Invoca diretamente o handler usando ServeHTTP
35
    handler := http.HandlerFunc(app.HandleCreateTask)
36
    handler.ServeHTTP(rec, req)
37

38
    // 6. ASSERT: Valida o Status Code (esperado: 201 Created)
39
    if rec.Code != http.StatusCreated {
40
        t.Errorf("Status Code incorreto: obteve %d; esperava %d", rec.Code, http.StatusCreated)
41
    }
42

43
    // 7. ASSERT: Valida o corpo JSON da resposta retornada
44
    var resBody map[string]any
45
    if err := json.Unmarshal(rec.Body.Bytes(), &resBody); err != nil {
46
        t.Fatalf("falha ao decodificar JSON de resposta (%q): %v", rec.Body.String(), err)
47
    }
48

49
    if resBody["title"] != payload["title"] {
50
        t.Errorf("Título incorreto: obteve %q; esperava %q", resBody["title"], payload["title"])
51
    }
52
}

O Handler Inicial (Vazio)#

O handler começa deliberadamente vazio, só para observarmos a falha:

1
package api
2

3
import (
4
    "net/http"
5
)
6

7
// HandleCreateTask processa a criação de uma nova task
8
func (app *Application) HandleCreateTask(w http.ResponseWriter, r *http.Request) {
9
    // Função deliberadamente vazia para observar o teste falhar na fase RED
10
}

A Prova da Falha#

Rodando go test -v ./internal/api/..., a falha é cirúrgica:

1
=== RUN   TestHandleCreateTask
2
    tasks_handlers_test.go:34: Status Code incorreto: obteve 200; esperava 201
3
    tasks_handlers_test.go:40: falha ao decodificar JSON de resposta (""): unexpected end of JSON input
4
--- FAIL: TestHandleCreateTask (0.00s)
5
FAIL
6
FAIL    github.com/user/taskify/internal/api    0.003s

O valor do estado RED

A falha comprova que o teste é honesto e não está passando por engano (falso positivo). No próximo passo, implementamos o código mínimo de produção para chegar à fase GREEN.

O Contrato de Persistência: store.TaskStore#

No pacote store, definimos a entidade de domínio e o contrato de métodos — a “lista de plugues” que qualquer implementação precisa oferecer. Regra de ouro: toda operação de I/O recebe ctx context.Context como primeiro parâmetro, para poder ser cancelada ou receber um timeout de fora, vindo do handler HTTP.

1
package store
2

3
import (
4
    "context"
5
    "time"
6
)
7

8
// Task representa a entidade de domínio de uma tarefa no sistema
9
type Task struct {
10
    ID          int32     `json:"id"`
11
    Title       string    `json:"title"`
12
    Description string    `json:"description"`
13
    Priority    int32     `json:"priority"`
14
    CreatedAt   time.Time `json:"created_at"`
15
    UpdatedAt   time.Time `json:"updated_at"`
16
}
17

18
// TaskStore define o contrato de persistência independente do driver ou banco utilizado
19
type TaskStore interface {
20
    CreateTask(ctx context.Context, title, description string, priority int32) (Task, error)
21
    GetTaskByID(ctx context.Context, id int32) (Task, error)
22
    ListTasks(ctx context.Context) ([]Task, error)
23
    UpdateTask(ctx context.Context, id int32, title, description string, priority int32) (Task, error)
24
    DeleteTask(ctx context.Context, id int32) error
25
}

Quem implementa o plugue não importa para o teste#

Alguma implementação concreta de TaskStore vai existir em produção — hoje pode ser Postgres, amanhã outro banco, sem que TaskService precise mudar uma linha. Como ela funciona por dentro (driver, biblioteca de acesso a dados, mapeamento de colunas) é um assunto de infraestrutura, não de testes, e fica fora do escopo deste guia. O que importa aqui é só isso: para testar TaskService, você nunca precisa dessa implementação real — só de algo que satisfaça a interface, o que nos leva à versão falsa usada em teste.

A Camada de Serviço: TaskService#

O TaskService recebe o ctx propagado pelo handler e o repassa direto para a store, aplicando as validações de domínio no meio do caminho:

1
package services
2

3
import (
4
    "context"
5
    "errors"
6
    "strings"
7

8
    "github.com/user/taskify/internal/store"
9
)
10

11
var (
12
    ErrInvalidTitle    = errors.New("o título da tarefa não pode ser vazio")
13
    ErrInvalidPriority = errors.New("a prioridade deve ser maior ou igual a zero")
14
)
15

16
type TaskService struct {
17
    store store.TaskStore
18
}
19

20
func NewTaskService(store store.TaskStore) *TaskService {
21
    return &TaskService{
22
        store: store,
23
    }
24
}
25

26
func ValidateTask(title string, priority int32) error {
27
    if strings.TrimSpace(title) == "" {
28
        return ErrInvalidTitle
29
    }
30
    if priority < 0 {
31
        return ErrInvalidPriority
32
    }
33
    return nil
34
}
35

36
func (s *TaskService) CreateTask(ctx context.Context, title, description string, priority int32) (store.Task, error) {
37
    if err := ValidateTask(title, priority); err != nil {
38
        return store.Task{}, err
39
    }
40
    return s.store.CreateTask(ctx, title, description, priority)
41
}
42

43
func (s *TaskService) GetTask(ctx context.Context, id int32) (store.Task, error) {
44
    return s.store.GetTaskByID(ctx, id)
45
}
46

47
func (s *TaskService) ListTasks(ctx context.Context) ([]store.Task, error) {
48
    return s.store.ListTasks(ctx)
49
}
50

51
func (s *TaskService) UpdateTask(ctx context.Context, id int32, title, description string, priority int32) (store.Task, error) {
52
    if err := ValidateTask(title, priority); err != nil {
53
        return store.Task{}, err
54
    }
55
    return s.store.UpdateTask(ctx, id, title, description, priority)
56
}
57

58
func (s *TaskService) DeleteTask(ctx context.Context, id int32) error {
59
    return s.store.DeleteTask(ctx, id)
60
}

Testes Unitários vs. Testes de Integração#

Essa separação em camadas resolve o dilema clássico dos testes automatizados. Testes unitários puros — a função ValidateTask, o TaskService com um mock — rodam em menos de 1 milissegundo e cobrem dezenas de cenários de borda sem tocar em banco nenhum. Testes de integração validam se a implementação real do TaskStore realmente funciona contra um banco de verdade, e por isso exigem infraestrutura rodando. Os dois têm seu lugar: muitos testes unitários rápidos, e uma suíte menor de integração para o que só o banco real pode confirmar.

Quanto Mockar: o Debate “I Mock, You Mock”#

O artigo clássico I Mock, You Mock resume bem quando usar mocks: para isolar a unidade sob teste de dependências lentas ou externas (bancos, APIs de terceiros, gateways de pagamento), e para simular cenários difíceis de forçar de verdade (banco fora do ar, timeout de conexão, chave primária duplicada). O risco é o over-mocking — mockar tudo acaba testando a implementação do mock, não o comportamento do software. Regra prática: use mocks nos testes unitários de handlers e serviços, e mantenha uma suíte menor de integração com banco real para validar o schema SQL.

O Padrão AAA (Arrange - Act - Assert)#

Sem uma estrutura, um teste vira facilmente uma mistura confusa de preparação, chamada e verificação — difícil de ler seis meses depois, e ainda mais difícil de saber o que exatamente quebrou quando ele falha. O AAA resolve isso separando qualquer teste em três blocos bem demarcados, sempre na mesma ordem:

• Arrange (preparar): instancia o mock, injeta no serviço, define a entrada e o resultado esperado.
• Act (agir): invoca o método sob teste — só essa uma linha é o que está de fato sendo testado.
• Assert (verificar): checa se não houve erro inesperado e se o retorno bate com a expectativa.

O ganho é simples: qualquer pessoa lendo o teste — inclusive você, no futuro — sabe exatamente onde termina o “contexto” e começa a “coisa testada de verdade”. É o mesmo esqueleto dos comentários numerados no teste RED da seção 3, agora aplicado à camada de serviço.

Construindo Mocks Manuais (MockTaskStore)#

Em Go, qualquer struct que implemente todos os métodos de store.TaskStore satisfaz o contrato automaticamente (duck typing estrutural) — não existe palavra-chave especial para “mock” na linguagem. Um mock é exatamente isso: uma struct escrita à mão que implementa a mesma interface da versão real, mas devolve valores fixos e previsíveis em vez de consultar um banco de verdade. O mock abaixo é uma implementação fake em memória, com suporte a context.Context:

1
package services
2

3
import (
4
    "context"
5
    "testing"
6
    "time"
7

8
    "github.com/stretchr/testify/assert"
9
    "github.com/user/taskify/internal/store"
10
)
11

12
// mockTaskStore é a implementação fake da interface store.TaskStore em memória
13
type mockTaskStore struct{}
14

15
func (m *mockTaskStore) CreateTask(ctx context.Context, title, description string, priority int32) (store.Task, error) {
16
    return store.Task{
17
        ID:          1,
18
        Title:       title,
19
        Description: description,
20
        Priority:    priority,
21
        CreatedAt:   time.Now(),
22
        UpdatedAt:   time.Now(),
23
    }, nil
24
}
25

26
func (m *mockTaskStore) GetTaskByID(ctx context.Context, id int32) (store.Task, error) {
27
    return store.Task{
28
        ID:          id,
29
        Title:       "Mock Task",
30
        Description: "Mock Description",
31
        Priority:    1,
32
        CreatedAt:   time.Now(),
33
        UpdatedAt:   time.Now(),
34
    }, nil
35
}
36

37
func (m *mockTaskStore) ListTasks(ctx context.Context) ([]store.Task, error) {
38
    return []store.Task{
39
        {
40
            ID:          1,
41
            Title:       "Task 1",
42
            Description: "Description 1",
43
            Priority:    1,
44
            CreatedAt:   time.Now(),
45
            UpdatedAt:   time.Now(),
46
        },
47
        {
48
            ID:          2,
49
            Title:       "Task 2",
50
            Description: "Description 2",
51
            Priority:    2,
52
            CreatedAt:   time.Now(),
53
            UpdatedAt:   time.Now(),
54
        },
55
    }, nil
56
}
57

58
func (m *mockTaskStore) UpdateTask(ctx context.Context, id int32, title, description string, priority int32) (store.Task, error) {
59
    return store.Task{
60
        ID:          id,
61
        Title:       title,
62
        Description: description,
63
        Priority:    priority,
64
        CreatedAt:   time.Now(),
65
        UpdatedAt:   time.Now(),
66
    }, nil
67
}
68

69
func (m *mockTaskStore) DeleteTask(ctx context.Context, id int32) error {
70
    return nil // Simula deleção com sucesso
71
}

Testando o TaskService com Mocks#

1
// Teste de Criação de Tarefa
2
func TestTaskService_CreateTask(t *testing.T) {
3
    // 1. ARRANGE
4
    mockStore := &mockTaskStore{}
5
    service := NewTaskService(mockStore)
6
    ctx := context.Background()
7

8
    expectedTitle := "Aprender TDD"
9
    expectedDesc := "Escrever testes com mocks em Go"
10
    expectedPriority := int32(10)
11

12
    // 2. ACT
13
    task, err := service.CreateTask(ctx, expectedTitle, expectedDesc, expectedPriority)
14

15
    // 3. ASSERT
16
    assert.NoError(t, err)
17
    assert.Equal(t, expectedTitle, task.Title)
18
    assert.Equal(t, expectedDesc, task.Description)
19
    assert.Equal(t, expectedPriority, task.Priority)
20
    assert.Equal(t, int32(1), task.ID)
21
}
22

23
// Teste de Busca por ID
24
func TestTaskService_GetTask(t *testing.T) {
25
    // 1. ARRANGE
26
    mockStore := &mockTaskStore{}
27
    service := NewTaskService(mockStore)
28
    ctx := context.Background()
29

30
    // 2. ACT
31
    task, err := service.GetTask(ctx, 1)
32

33
    // 3. ASSERT
34
    assert.NoError(t, err)
35
    assert.Equal(t, int32(1), task.ID)
36
    assert.Equal(t, "Mock Task", task.Title)
37
}
38

39
// Teste de Listagem de Tarefas
40
func TestTaskService_ListTasks(t *testing.T) {
41
    // 1. ARRANGE
42
    mockStore := &mockTaskStore{}
43
    service := NewTaskService(mockStore)
44
    ctx := context.Background()
45

46
    // 2. ACT
47
    tasks, err := service.ListTasks(ctx)
48

49
    // 3. ASSERT
50
    assert.NoError(t, err)
51
    assert.Len(t, tasks, 2)
52
    assert.Equal(t, "Task 1", tasks[0].Title)
53
    assert.Equal(t, "Task 2", tasks[1].Title)
54
}

testify/assert vs. Standard Library#

O pacote github.com/stretchr/testify/assert é o mais popular do ecossistema Go para asserções de teste:

1
go test -v ./internal/services/...
2

3
# === RUN   TestTaskService_CreateTask
4
# --- PASS: TestTaskService_CreateTask (0.00s)
5
# === RUN   TestTaskService_GetTask
6
# --- PASS: TestTaskService_GetTask (0.00s)
7
# === RUN   TestTaskService_ListTasks
8
# --- PASS: TestTaskService_ListTasks (0.00s)
9
# PASS
10
# ok      github.com/user/taskify/internal/services    0.002s

Não deixe o mock ficar esperto demais

Colocar validações de string, filtros SQL ou lógica de negócio dentro do mockTaskStore é um erro clássico — você acaba testando o mock, não o TaskService. O mock deve ser burro e previsível: recebe parâmetros, devolve uma struct estática. Toda a inteligência mora no serviço.

O padrão got vs want#

Dentro desse loop, a comunidade padronizou dois nomes de variável: got é o que a função realmente retornou, want é o que ela deveria ter retornado. Comparar os dois e reportar a diferença é o coração de qualquer teste manual:

1
if got != want {
2
    t.Errorf("got %q, want %q", got, want)
3
}

Use sempre %q (e não %s) para strings em mensagens de erro. %q adiciona aspas e escapa caracteres de controle — se a função retornar "Hello " com um espaço extra, %s esconderia o problema, mas %q mostraria got "Hello ", want "Hello" imediatamente.

Anatomia com structs anônimas#

A tabela é um slice de structs anônimas:

1
tests := []struct {
2
    name  string // nome descritivo do caso
3
    input string // dado de entrada
4
    want  string // saída esperada
5
}{
6
    {name: "saudação em português", input: "pt", want: "Oi"},
7
    {name: "saudação em inglês", input: "en", want: "Hello"},
8
}

Com a tabela pronta, o loop prometido lá em cima fica direto: para cada linha, chama a função testada e reaplica a mesma comparação got/want:

1
for _, tc := range tests {
2
    got := saudacao(tc.input)
3
    if got != tc.want {
4
        t.Errorf("%s: got %q, want %q", tc.name, got, tc.want)
5
    }
6
}

Funciona, mas todas as falhas caem no mesmo t.Errorf — para saber qual linha da tabela quebrou, é preciso ler o tc.name embutido na mensagem à mão. A seção 7 resolve isso.

A pasta testdata/#

Quando os dados de um caso de teste crescem além do que cabe numa struct — um JSON de payload, uma resposta HTTP gravada, um certificado —, embuti-los como string literal na tabela fica ilegível. Qualquer diretório chamado testdata/ dentro de um pacote é ignorado pelo go build, mas fica disponível para os arquivos *_test.go. É o lugar certo para essas fixtures:

1
internal/parser/
2
├── parser.go
3
├── parser_test.go
4
└── testdata/
5
    ├── valid_payload.json      <- os.ReadFile("testdata/valid_payload.json")
6
    └── corrupted_payload.json

Cache de testes#

Outra conveniência do go test, útil à medida que a suíte cresce: ele mantém cache dos resultados. Se nada mudou desde a última execução, o pacote aparece como (cached) em vez de rodar de novo.

1
go test ./...
2
# ok  github.com/user/project/pkg  (cached)
3

4
go clean -testcache        # limpa o cache manualmente
5
go test -count=1 ./...     # força execução sem cache

Subtestes isolados com t.Run#

Basta envolver o corpo do loop com t.Run, usando tc.name como identificador:

1
for _, tc := range tests {
2
    t.Run(tc.name, func(t *testing.T) {
3
        got := saudacao(tc.input)
4
        if got != tc.want {
5
            t.Errorf("got %q, want %q", got, tc.want)
6
        }
7
    })
8
}

Agora uma falha já aparece na saída identificada pelo nome do subteste (--- FAIL: NomeDoTeste/NomeDoCaso), sem precisar embutir tc.name na mensagem manualmente. O nome também serve para filtrar execuções pela CLI e rodar um único caso, sem disparar a suíte inteira — como no exemplo HelloName que fecha esta seção:

1
go test -v -run "TestHelloName/SpanishGreet" ./internal/greet/...

Execução concorrente com t.Parallel()#

Numa suíte com dezenas de subtestes, rodar cada um em sequência desperdiça tempo se eles não dependem uns dos outros. Chame t.Parallel() dentro do t.Run e o subteste passa a rodar concorrentemente com os demais marcados da mesma forma — a suíte inteira termina mais rápido. Isso só é seguro se os subtestes forem independentes e não compartilharem estado mutável; aliás, rodar em paralelo também é uma forma de expor bugs de concorrência que já existiam no código testado e ficavam escondidos enquanto tudo rodava em sequência.

1
func TestParallelSuite(t *testing.T) {
2
    tests := []struct {
3
        name string
4
    }{
5
        {name: "caso 1"},
6
        {name: "caso 2"},
7
    }
8

9
    for _, tc := range tests {
10
        t.Run(tc.name, func(t *testing.T) {
11
            t.Parallel() // permite que este subteste rode concorrentemente
12
            // asserções...
13
        })
14
    }
15
}

Ao usar tc (a variável do loop) dentro da closure passada para t.Run, é preciso ter cuidado com o escopo dela:

Por que “cuidado com o escopo”?

t.Parallel() faz o subteste pausar e só continuar depois que a função TestParallelSuite inteira já terminou de disparar todos os outros. O problema: antes do Go 1.22, a variável tc do loop era uma única caixa reaproveitada a cada volta — não uma caixa nova por iteração. Se os subtestes só rodam de verdade depois que o loop já acabou, todos acabavam lendo o valor que sobrou na caixa: o da última iteração. Resultado: vários subtestes com nomes diferentes, todos testando o mesmo caso. Desde o Go 1.22, cada volta do for ganha sua própria caixa, e esse cuidado não é mais necessário.

O ciclo TDD na prática: HelloName multi-idioma#

Table-driven tests e subtestes se encaixam perfeitamente no ciclo Red → Green → Refactor. Vamos construir uma função de saudação multi-idioma do zero.

1
package greet
2

3
import (
4
    "testing"
5
)
6

7
func TestHelloName(t *testing.T) {
8
    tests := []struct {
9
        name     string
10
        language string
11
        input    string
12
        want     string
13
    }{
14
        {
15
            name:     "EnglishGreet",
16
            language: "en",
17
            input:    "John",
18
            want:     "Hello, John",
19
        },
20
        {
21
            name:     "PortugueseGreet",
22
            language: "pt",
23
            input:    "Maria",
24
            want:     "Oi, Maria",
25
        },
26
        {
27
            name:     "SpanishGreet",
28
            language: "es",
29
            input:    "Carlos",
30
            want:     "Hola, Carlos",
31
        },
32
        {
33
            name:     "FrenchGreet",
34
            language: "fr",
35
            input:    "Pierre",
36
            want:     "Bonjour, Pierre",
37
        },
38
        {
39
            name:     "EmptyStringName",
40
            language: "pt",
41
            input:    "",
42
            want:     "Oi, Anonymous",
43
        },
44
        {
45
            name:     "EmptyLanguage",
46
            language: "",
47
            input:    "Loran",
48
            want:     "👋, Loran",
49
        },
50
        {
51
            name:     "InvalidLanguage",
52
            language: "ru",
53
            input:    "Loran",
54
            want:     "👋, Loran",
55
        },
56
    }
57

58
    for _, tc := range tests {
59
        t.Run(tc.name, func(t *testing.T) {
60
            got := HelloName(tc.input, tc.language)
61
            if got != tc.want {
62
                t.Errorf("got %q, want %q", got, tc.want)
63
            }
64
        })
65
    }
66
}

1
package greet
2

3
import "fmt"
4

5
func HelloName(name, lang string) string {
6
    if name == "" {
7
        name = "Anonymous"
8
    }
9

10
    if lang == "en" {
11
        return fmt.Sprintf("Hello, %s", name)
12
    }
13
    if lang == "pt" {
14
        return fmt.Sprintf("Oi, %s", name)
15
    }
16
    if lang == "es" {
17
        return fmt.Sprintf("Hola, %s", name)
18
    }
19
    if lang == "fr" {
20
        return fmt.Sprintf("Bonjour, %s", name)
21
    }
22

23
    return fmt.Sprintf("👋, %s", name)
24
}

1
package greet
2

3
import "fmt"
4

5
const (
6
    defaultGreet = "👋"
7
    defaultName  = "Anonymous"
8
)
9

10
// greetings armazena o mapa de saudações por idioma
11
var greetings = map[string]string{
12
    "pt": "Oi",
13
    "en": "Hello",
14
    "es": "Hola",
15
    "fr": "Bonjour",
16
}
17

18
// HelloName formata uma saudação amigável no idioma especificado
19
func HelloName(name, lang string) string {
20
    if name == "" {
21
        name = defaultName
22
    }
23

24
    greet, ok := greetings[lang]
25
    if !ok || lang == "" {
26
        greet = defaultGreet
27
    }
28

29
    return fmt.Sprintf("%s, %s", greet, name)
30
}

1
go test -v ./internal/greet/...
2

3
# === RUN   TestHelloName
4
# === RUN   TestHelloName/EnglishGreet
5
# === RUN   TestHelloName/PortugueseGreet
6
# === RUN   TestHelloName/SpanishGreet
7
# === RUN   TestHelloName/FrenchGreet
8
# === RUN   TestHelloName/EmptyStringName
9
# === RUN   TestHelloName/EmptyLanguage
10
# === RUN   TestHelloName/InvalidLanguage
11
# --- PASS: TestHelloName (0.00s)
12
#     --- PASS: TestHelloName/EnglishGreet (0.00s)
13
#     --- PASS: TestHelloName/PortugueseGreet (0.00s)
14
#     --- PASS: TestHelloName/SpanishGreet (0.00s)
15
#     --- PASS: TestHelloName/FrenchGreet (0.00s)
16
#     --- PASS: TestHelloName/EmptyStringName (0.00s)
17
#     --- PASS: TestHelloName/EmptyLanguage (0.00s)
18
#     --- PASS: TestHelloName/InvalidLanguage (0.00s)
19
# PASS
20
# ok      github.com/user/project/internal/greet    0.002s

Gerando um Mock com mockery#

Para não repetir aqui os cinco métodos do TaskStore real da seção 4, considere uma versão enxuta da mesma ideia — persistência de tasks —, só com busca e gravação. Basta anotar o pacote com uma diretiva //go:generate:

1
package taskify
2

3
import "context"
4

5
//go:generate mockery --name=TaskStore --output=mocks --outpkg=mocks
6
type TaskStore interface {
7
    GetTask(ctx context.Context, id string) (*Task, error)
8
    SaveTask(ctx context.Context, task *Task) error
9
}

Rodando go generate ./... (ou mockery --name=TaskStore direto no terminal), a ferramenta gera mocks/TaskStore.go com uma struct MockTaskStore que embute mock.Mock e implementa cada método da interface delegando para m.Called(...). Você nunca edita esse arquivo à mão — ele é reescrito a cada go generate.

Usando o Mock Gerado#

O teste segue o mesmo padrão AAA da seção 5, mas a forma de configurar o mock muda: em vez de fixar um retorno direto no corpo do método, você declara em tempo de teste o que cada chamada deve devolver:

1
package taskify_test
2

3
import (
4
    "context"
5
    "testing"
6

7
    "github.com/example/taskify"
8
    "github.com/example/taskify/mocks"
9
    "github.com/stretchr/testify/assert"
10
    "github.com/stretchr/testify/mock"
11
)
12

13
func TestCompleteTask(t *testing.T) {
14
    // Arrange
15
    store := mocks.NewMockTaskStore(t)
16
    store.On("GetTask", mock.Anything, "task-1").
17
        Return(&taskify.Task{ID: "task-1", Done: false}, nil)
18
    store.On("SaveTask", mock.Anything, mock.MatchedBy(func(tk *taskify.Task) bool {
19
        return tk.Done == true
20
    })).Return(nil)
21

22
    svc := taskify.NewService(store)
23

24
    // Act
25
    err := svc.CompleteTask(context.Background(), "task-1")
26

27
    // Assert
28
    assert.NoError(t, err)
29
    store.AssertExpectations(t) // Garante que GetTask e SaveTask foram chamados
30
}

Cada .On(método, argumentos...) registra uma expectativa: quando aquele método for chamado com esses argumentos, o mock devolve o que estiver em .Return(...). mock.Anything casa com qualquer valor no lugar do argumento — útil para o ctx, que muda a cada chamada e raramente importa validar. Se o código sob teste chamar um método sem expectativa registrada, o teste falha ali mesmo, apontando a chamada não prevista; no fim, store.AssertExpectations(t) cobre o caso oposto, garantindo que toda expectativa registrada foi de fato usada.

mock.MatchedBy permite validar o conteúdo do argumento recebido, não só o tipo — útil para conferir que a task foi realmente marcada como concluída antes de ser salva.

gomock como alternativa

gomock resolve o mesmo problema com outra sintaxe: mockStore.EXPECT().GetTask(gomock.Any(), "task-1").Return(task, nil) em vez de .On(...)/.Return(...). A diferença prática é que gomock é mais rígido por padrão: uma chamada fora da ordem esperada já falha o teste na hora, enquanto mockery/testify só cobra isso se você pedir explicitamente com .Once() ou .AssertExpectations(t). Escolha um dos dois e fique com ele — misturar os dois no mesmo projeto raramente compensa.

Anatomia de um Fuzz Test#

Considere uma função que converte o ID de uma task (string) para int32:

1
func ParseTaskID(s string) (int32, error) {
2
    n, err := strconv.Atoi(s)
3
    if err != nil {
4
        return 0, fmt.Errorf("id inválido: %w", err)
5
    }
6
    return int32(n), nil // BUG: conversão trunca silenciosamente valores grandes
7
}

Aqui está o problema escondido: strconv.Atoi devolve um int de 64 bits, mas a função espreme esse valor num int32 sem checar se ele cabe. É como tentar guardar o número 5 bilhões numa caixa que só aceita até 2 bilhões e pouco — o excesso simplesmente “vaza” e vira outro número, sem nenhum erro avisando. Um input como "99999999999" sai da função como um número negativo qualquer. Ninguém escreveria esse caso de teste por conta própria. É exatamente esse tipo de entrada esquisita que o fuzzer encontra sozinho:

1
func FuzzParseTaskID(f *testing.F) {
2
    // Seed corpus: casos conhecidos para guiar as mutações iniciais
3
    f.Add("42")
4
    f.Add("-1")
5
    f.Add("0")
6

7
    f.Fuzz(func(t *testing.T, input string) {
8
        n, err := ParseTaskID(input)
9
        if err != nil {
10
            return // Input inválido é esperado, não é falha
11
        }
12

13
        // Regra que sempre deve valer: se não houve erro, o valor de volta
14
        // precisa caber em int32 sem ter sido silenciosamente cortado
15
        if big, convErr := strconv.ParseInt(input, 10, 64); convErr == nil {
16
            if big > math.MaxInt32 || big < math.MinInt32 {
17
                t.Errorf("overflow silencioso: input=%q gerou n=%d", input, n)
18
            }
19
        }
20
    })
21
}

Rodando o Fuzzer#

1
# go test normal roda só o seed corpus (f.Add), como um teste comum
2
go test ./...
3

4
# -fuzz ativa a geração de mutações reais, -fuzztime limita a duração
5
go test -fuzz=FuzzParseTaskID -fuzztime=30s

Quando o fuzzer encontra um input que quebra a regra, ele imprime a falha, salva a versão mais simples possível desse input em testdata/fuzz/FuzzParseTaskID/<hash> e para. Esse arquivo passa a ser rodado automaticamente em todo go test daí em diante — o bug que o fuzzer achou hoje vira um teste de regressão permanente, sem você precisar transcrever nada à mão.

Corpus é código

Os arquivos em testdata/fuzz/ devem ser commitados no repositório. Eles documentam bugs reais já encontrados e garantem que não voltem a acontecer.

Anatomia de um Benchmark#

O nome da função começa com Benchmark, recebe *testing.B, e o corpo roda dentro de um loop até b.N:

1
func BenchmarkConcatPlus(b *testing.B) {
2
    words := []string{"go", "é", "rápido", "e", "simples", "de", "testar"}
3
    b.ReportAllocs()
4

5
    for i := 0; i < b.N; i++ {
6
        var s string
7
        for _, w := range words {
8
            s += w // Cada '+=' aloca uma nova string
9
        }
10
    }
11
}
12

13
func BenchmarkConcatBuilder(b *testing.B) {
14
    words := []string{"go", "é", "rápido", "e", "simples", "de", "testar"}
15
    b.ReportAllocs()
16

17
    for i := 0; i < b.N; i++ {
18
        var sb strings.Builder
19
        for _, w := range words {
20
            sb.WriteString(w)
21
        }
22
        _ = sb.String()
23
    }
24
}

b.N não é um número fixo que você escolhe: o framework de testes ajusta esse valor automaticamente, rodando a função cada vez mais vezes até ter uma amostra grande o suficiente para uma medição estável de tempo por operação. Já b.ReportAllocs() liga, só para aquele benchmark, a contagem de alocações de heap — são as colunas B/op e allocs/op que aparecem no resultado a seguir. Rodar com a flag -benchmem (usada na próxima seção) faz o mesmo para todos os benchmarks do pacote de uma vez, sem precisar chamar ReportAllocs em cada função.

Rodando e Lendo o Resultado#

1
go test -bench=. -benchmem

1
BenchmarkConcatPlus-8        500000    2841 ns/op    336 B/op    6 allocs/op
2
BenchmarkConcatBuilder-8    2000000     612 ns/op     64 B/op    1 allocs/op

• ns/op: nanossegundos por operação — quanto menor, mais rápido.
• B/op: bytes alocados no heap por operação.
• allocs/op: número de alocações distintas no heap por operação.

O resultado confirma o que a seção 9 do “Guia Definitivo de Go” já explicava sobre += em strings: cada concatenação aloca um novo backing array e copia tudo de novo, enquanto strings.Builder reaproveita um buffer interno e cresce sob demanda, como um slice pré-alocado com make.

b.ResetTimer() para Ignorar Setup#

Quando o benchmark precisa de uma preparação cara antes do loop (carregar um arquivo, popular um mock), use b.ResetTimer() para não contaminar a medição:

1
func BenchmarkProcessLargeFile(b *testing.B) {
2
    data := loadFixture("large_dataset.json") // Setup caro, fora da medição
3

4
    b.ResetTimer() // Zera o cronômetro aqui, o setup acima não conta
5

6
    for i := 0; i < b.N; i++ {
7
        Process(data)
8
    }
9
}

Profiling de um Benchmark com pprof

go test -bench=. -cpuprofile=cpu.out gera um perfil de CPU da execução do benchmark, analisável com go tool pprof cpu.out. O uso avançado de pprof — flame graphs, profiles de memória e de contenção de locks — foi coberto em profundidade no post “Concorrência e Paralelismo em Go”.

Integrando no CI/CD#

Rodar a suíte com cobertura — e com o race detector ligado — a cada push é o mínimo esperado em qualquer pipeline Go sério:

1
name: Go Tests
2

3
on:
4
  push:
5
    branches: [main]
6
  pull_request:
7

8
jobs:
9
  test:
10
    runs-on: ubuntu-latest
11
    steps:
12
      - uses: actions/checkout@v4
13
      - uses: actions/setup-go@v5
14
        with:
15
          go-version: "1.22"
16
      - run: go test -race -coverprofile=coverage.out ./...

Serviços como Codecov ou Coveralls consomem esse coverage.out para plotar tendência histórica de cobertura e comentar automaticamente em Pull Requests quando uma mudança reduz a cobertura de um arquivo — útil como sinal de alerta, mas, como qualquer métrica, não substitui revisão de código.

Testes automatizados em Go custam pouco para começar a escrever, e essa é a razão de fundo pela qual a cultura de testes na linguagem é tão forte — é o que torna viável, na prática, a rede de segurança que abriu este guia. A compilação é rápida, o pacote testing já vem embutido na standard library — sem escolher framework, sem configurar runner, sem instalar dependência nenhuma — e go test ./... já funciona no dia zero de qualquer projeto. Mocks manuais, geração automática com mockery, fuzzing, benchmarks e cobertura são camadas que você adiciona conforme a necessidade aparece, não um pacote obrigatório que você precisa engolir de uma vez. Vale reforçar: nada disso substitui pensar sobre concorrência com cuidado — quando os testes exercitam código concorrente, rode-os com -race e considere goleak para pegar goroutines vazadas, como detalhado no post “Concorrência e Paralelismo em Go”. Para revisitar os fundamentos da linguagem que sustentam tudo isso — zero values, ponteiros, slices, generics — o “Guia Definitivo de Go” continua sendo a referência desta série.