Testes em subpastas Go: análise completa para iniciantes

Testes em subpastas Go: resolvendo o problema que os tutoriais omitem

Você já escreveu testes em Go e se deparou com o fato de que eles funcionam perfeitamente na raiz do projeto, mas quando você os move para uma subpasta — tudo quebra? Familiar? Se sim — você não está sozinho. A pergunta "Golang tests in sub-directory" no Stack Overflow acumulou milhares de visualizações. E não é surpreendente: a documentação do Go aborda isso de forma superficial, e desenvolvedores iniciantes frequentemente se perdem.

Neste artigo, vamos entender como organizar corretamente os testes Go usando pacotes aninhados, por que isso é necessário e como evitar armadilhas. Vamos lá!

Por que testes em subpastas são um problema?

Imagine: você tem um projeto com a seguinte estrutura:

myapp/\n├── main.go\n├── go.mod\n└── utils/\n    ├── math.go\n    └── math_test.go

Você executa Go test na raiz — e tudo funciona. Mas quando tenta executar os testes a partir da pasta utils, o Go reclama: "package myapp/utils is not in GOROOT". Erro familiar?

O problema é que o Go trabalha com pacotes, não com pastas. Quando você cria uma subpasta, está efetivamente criando um novo pacote. E os testes dentro dela precisam ser executados considerando a estrutura modular do projeto. Mas vamos por partes.

Fundamentos: como o Go enxerga os testes

Em Go, testes são arquivos comuns com o sufixo _test.go. Eles podem estar:

\n
• No mesmo pacote (testes brancos) — têm acesso a funções não exportadas.
\n
• Em um pacote separado com o sufixo _test (testes pretos) — testam o pacote como um usuário externo.
\n

Quando você coloca os testes em uma subpasta, você cria um novo pacote. Por exemplo, a pasta utils é o pacote utils. E os testes dentro dela devem pertencer a este pacote.

Exemplo de estrutura correta

myapp/\n├── go.mod\n├── main.go\n└── utils/\n    ├── math.go        // package utils\n    └── math_test.go   // package utils

No arquivo math.go:

package utils\n\nfunc Add(a, b int) int {\n    return a + b\n}

No arquivo math_test.go:

package utils\n\nimport "testing"\n\nfunc TestAdd(t *testing.T) {\n    result := Add(2, 3)\n    if result != 5 {\n        t.Errorf("Expected 5, got %d", result)\n    }\n}

Agora execute os testes a partir da raiz do projeto:

go test ./utils/

Ou a partir da pasta utils:

cd utils\ngo test

Tudo funciona! Mas e se você tiver uma estrutura mais complexa?

Subpastas aninhadas: mais profundo do que parece

Suponha que você tenha um projeto com esta estrutura:

myapp/\n├── go.mod\n├── main.go\n└── services/\n    ├── user/\n    │   ├── user.go\n    │   └── user_test.go\n    └── order/\n        ├── order.go\n        └── order_test.go

Aqui, cada subpasta é um pacote separado. Para executar todos os testes recursivamente, use três pontos:

go test ./...

Este comando encontrará todos os pacotes no projeto e executará seus testes. Muito útil para CI/CD!

E se os testes estiverem na mesma pasta que o código?

Às vezes, desenvolvedores colocam os testes na mesma pasta que o código principal. Isso é normal para projetos pequenos. Mas para projetos grandes, é melhor colocar os testes em subpastas separadas — assim a estrutura fica mais limpa.

Erros típicos e suas soluções

Vamos analisar os problemas mais comuns que iniciantes enfrentam ao trabalhar com Golang tests in sub-directory.

Erro 1: "package is not in GOROOT"

Causa: Você está tentando executar um teste a partir de uma subpasta sem especificar o módulo. O Go não sabe a qual módulo o pacote pertence.

Solução: Certifique-se de ter um arquivo go.mod na raiz do projeto.