Skip to content

augustonascimentos/go-bdd-api-testing-template

BranchesTags

Repository files navigation

🧪 Go BDD API Testing Template

Go Version Godog License: MIT PRs Welcome

Template robusto e escalável para testes automatizados de APIs utilizando BDD (Behavior-Driven Development) com Golang e Godog.

📖 Sobre o Projeto

Este projeto foi criado com o objetivo de integrar times de QA e Desenvolvimento através de uma stack unificada de testes automatizados.

🎯 Motivação

Tradicionalmente, muitos times de QA desenvolvem testes em Ruby enquanto os desenvolvedores trabalham com Go. Isso cria uma barreira de conhecimento e dificulta a colaboração. Este template resolve esse problema ao:

  • ✅ Permitir que QAs escrevam testes na mesma linguagem que os desenvolvedores
  • ✅ Facilitar a colaboração entre Dev e QA no mesmo código
  • ✅ Aumentar o entendimento mútuo sobre o código e testes
  • ✅ Possibilitar que devs contribuam diretamente nos cenários de testes
  • ✅ Criar sinergia entre os times através de uma linguagem comum

🌟 Features

  • 🥒 BDD com Godog: Escreva cenários de teste em Gherkin (Given-When-Then)
  • 🚀 Performance: Execução paralela de testes com concorrência configurável
  • 📊 Relatórios Allure: Geração automática de relatórios visuais e detalhados
  • 🐳 Docker: Containerização completa para execução consistente
  • 🧩 Extensível: Estrutura modular fácil de estender
  • 📝 Bem documentado: Código comentado e exemplos práticos

📋 Pré-requisitos

  • Go 1.23+
  • Docker (opcional, para execução em container)
  • Allure (opcional, para visualizar relatórios)

🚀 Instalação

1. Clone o repositório

git clone https://github.com/augustonascimentos/go-bdd-api-testing-template.git
cd go-bdd-api-testing-template

2. Instale as dependências

go mod download

3. Configure as variáveis de ambiente

cp .env.example .env
# Edite o arquivo .env com suas configurações

⚙️ Configuração

Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

API_BASE_URL=https://api-under-test.com
API_CLIENT_ID=your-client-id
TIMEOUT=60s

🎯 Como Usar

Executar todos os testes

go test --godog.format=pretty

Executar testes específicos por tag

go test --godog.tags=@health --godog.format=pretty

Executar com concorrência

go test --godog.concurrency=4 --godog.format=pretty

Executar com múltiplos formatos

go test \
    --godog.tags=@smoke \
    --godog.concurrency=2 \
    --godog.format=pretty,cucumber:reports/cucumber.json

🐳 Uso com Docker

Build da imagem

docker build -t go-bdd-api-testing .

Executar testes no container

docker run --rm \
    -e API_BASE_URL=https://api.example.com \
    -e API_CLIENT_ID=your-client-id \
    go-bdd-api-testing \
    go test --godog.format=pretty

Usando Docker Compose (com Mock API)

O projeto inclui um docker-compose.yml configurado com:

  • Container de testes BDD
  • Mock API (json-server) para testes locais
  • Allure Reports visualizador
# Iniciar todos os serviços
docker-compose up

# Apenas testes
docker-compose up bdd-tests

# Visualizar relatórios Allure
open http://localhost:5050

📊 Relatórios Allure

Gerar relatório

Após executar os testes, os resultados estarão em reports/allure-results/.

# Instalar Allure (se ainda não tiver)
# macOS
brew install allure

# Linux
sudo apt-add-repository ppa:qameta/allure
sudo apt-get update
sudo apt-get install allure

# Gerar e visualizar o relatório
allure serve reports/allure-results

📁 Estrutura do Projeto

.
├── config/              # Configurações e variáveis de ambiente
│   ├── base_config.go   # Configurações base para testes
│   ├── config.go        # Carregamento de variáveis de ambiente
│   └── context.go       # Contexto de teste
├── features/            # Arquivos .feature com cenários BDD
│   ├── health.feature   # Exemplo de feature de health check
│   └── users.feature    # Exemplo de feature de CRUD de usuários
├── steps/               # Step definitions (implementação dos passos)
│   ├── base_step_definitions.go
│   ├── common.go        # Steps comuns reutilizáveis
│   ├── context.go       # Helpers de contexto (client-id, trace-id)
│   ├── health.go        # Steps específicos de health
│   ├── suite.go         # Configuração da suite de testes
│   └── users.go         # Steps de CRUD de usuários
├── structs/             # Estruturas de dados (request/response)
│   ├── health.go
│   └── users.go         # Estrutura de dados de usuários
├── utils/               # Utilitários e helpers
│   ├── allure_formatter.go  # Formatador para Allure
│   ├── errors.go        # Tratamento de erros customizado
│   └── utils.go         # Funções auxiliares
├── startup/             # Inicialização e configuração dos testes
│   └── startup.go
├── reports/             # Diretório de relatórios gerados
│   └── allure-results/
├── mocks/               # Mock API para testes locais
│   ├── db.json          # Dados mock (health + usuários)
│   ├── Dockerfile.mock  # Dockerfile do mock server
│   ├── package.json     # Dependências do mock (json-server)
│   ├── README.md        # Documentação do mock
│   └── server.js        # Servidor mock customizado com validações
├── .env.example         # Exemplo de variáveis de ambiente
├── .golangci.yml        # Configuração do linter
├── docker-compose.yml   # Docker Compose setup
├── Dockerfile           # Containerização
├── Makefile             # Automação de build
├── go.mod               # Dependências do projeto
└── main_test.go         # Entry point dos testes

🛠️ Comandos Makefile

O projeto inclui um Makefile completo com comandos úteis:

# Setup
make help              # Mostra todos os comandos disponíveis
make setup             # Configura o ambiente de desenvolvimento
make install           # Instala as dependências do projeto
make install-tools     # Instala ferramentas de desenvolvimento
make validate-env      # Valida variáveis de ambiente

# Testes BDD
make test              # Executa os testes BDD (tag padrão: @health)
make test-all          # Executa todos os testes BDD
make test-smoke        # Executa testes @smoke
make test-health       # Executa testes @health
make test-users        # Executa testes @users
make test-crud         # Executa testes @crud
make test-create       # Executa testes @create
make test-read         # Executa testes @read
make test-update       # Executa testes @update
make test-delete       # Executa testes @delete
make test-validation   # Executa testes @validation
make test-list         # Executa testes @list
make test-verbose      # Executa testes com output verbose
make test-coverage     # Executa testes com relatório de cobertura
make test-race         # Executa testes com race detector

# Qualidade de Código
make fmt               # Formata o código
make lint              # Executa o linter
make vet               # Executa go vet
make build             # Verifica se o projeto compila
make check             # Executa fmt + vet + lint + test
make ci                # Executa pipeline CI localmente

# Docker
make mock-up           # Inicia o mock-api
make mock-down         # Para o mock-api
make mock-remove       # Remove o container do mock-api
make mock-logs         # Exibe logs do mock-api
make docker-test       # Executa testes BDD via docker-compose
make docker-build      # Cria a imagem Docker
make docker-up         # Inicia todos os serviços
make docker-down       # Para todos os containers
make docker-remove     # Remove containers e volumes
make docker-shell      # Abre shell no container de testes

# Allure Reports
make allure-up         # Inicia Allure via docker-compose
make allure-down       # Para o Allure
make allure-report     # Gera e serve o relatório localmente
make allure-generate   # Gera relatório Allure estático

# Limpeza
make clean             # Remove arquivos gerados e cache

Exemplos de uso:

# Setup inicial do projeto
make setup

# Executar testes com tag específica
make test GODOG_TAGS=@users

# Executar com mais concorrência
make test GODOG_CONCURRENCY=4

# Pipeline completo
make ci
## 📝 Criando Novos Testes

### 1. Crie uma nova feature

```gherkin
# features/users.feature
# language: pt

@users
Funcionalidade: Gerenciamento de Usuários
  Como um administrador
  Eu quero gerenciar usuários
  Para manter o sistema organizado

  Cenario: Criar um novo usuário
    Dado que eu tenho um payload válido de usuário
    Quando envio uma requisição do tipo "POST" para a rota "/users"
    Então devo receber o status code 201
    E o usuário deve ser criado com sucesso

2. Crie a estrutura de dados

// structs/user.go
package structs

type User struct {
    ID    string `json:"id"`
    Name  string `json:"name"`
    Email string `json:"email"`
}

3. Implemente os steps

// steps/users.go
package steps

import (
    "github.com/cucumber/godog"
)

func InitializeUserScenario(ctx *godog.ScenarioContext) {
    u := NewUserTest()
    ctx.Step(`^que eu tenho um payload válido de usuário$`, u.preparePayload)
    ctx.Step(`^o usuário deve ser criado com sucesso$`, u.validateCreation)
}

4. Registre no suite

// steps/suite.go
func InitializeScenarios(ctx *godog.ScenarioContext) {
    InitializeHealthScenario(ctx)
    InitializeUserScenario(ctx)  // Nova linha
}

🤝 Contribuindo

Contribuições são muito bem-vindas! Por favor:

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
  3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
  4. Push para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

Veja CONTRIBUTING.md para mais detalhes.

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👨‍💻 Autor

Augusto Nascimento

🙏 Agradecimentos

  • Cucumber/Godog - Framework BDD
  • Allure - Framework de relatórios
  • Comunidade Go - Por todo o suporte e ferramentas incríveis

📚 Recursos Adicionais

⭐ Se este projeto foi útil para você, considere dar uma estrela no GitHub!

⚠️ Importante sobre Persistência de Dados

O mock-api usa um Dockerfile customizado que copia o db.json para dentro do container.

Isso significa que:

  • ✅ Funciona em macOS, Windows e Linux
  • ✅ Sem problemas de permissões ou locks de arquivo
  • ⚠️ Alterações via POST/PUT/DELETE NÃO são persistidas entre restarts

Como resetar os dados

Os dados são automaticamente resetados ao reiniciar o container:

docker-compose restart mock-api

🧪 Testando a API Mock

# Iniciar serviços
docker-compose up -d mock-api

# Aguardar API estar pronta
docker-compose logs -f mock-api

# Testar health check
curl http://localhost:8080/health

# Criar usuário (dados não persistem após restart)
curl -X POST http://localhost:8080/users \
  -H "Content-Type: application/json" \
  -d '{"name":"João Silva","email":"joao@example.com","role":"developer"}'

# Listar usuários
curl http://localhost:8080/users

About

🧪 Template robusto e escalável para testes automatizados de APIs usando BDD com Golang e Godog

Topics

golang bdd test-automation gherkin cucumber allure golang-library allure-report golang-examples cucumber-reports bdd-tests godog test-automation-project allure-reports

Resources

Readme

License

MIT license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 1

v1.0.0 - Initial Release 🎉 Latest
Feb 15, 2026

Packages

 
 
 

Contributors

Languages