API Test Suite Builder

API Test Suite Builder

Nível: POWERFUL Categoria: Engineering Domínio: Testing / Qualidade de API

Visão Geral

Escaneia definições de rotas de API em diferentes frameworks (Next.js App Router, Express, FastAPI, Django REST) e auto-gera suites de testes abrangentes cobrindo autenticação, validação de entrada, códigos de erro, paginação, uploads de arquivo e limitação de taxa. Produz arquivos de teste prontos para execução com Vitest+Supertest (Node) ou Pytest+httpx (Python).

Capacidades Principais

• Detecção de rotas — escanear arquivos-fonte para extrair todos os endpoints de API
• Cobertura de autenticação — tokens válidos/inválidos/expirados, header de auth ausente
• Validação de entrada — campos ausentes, tipos errados, valores de limite, tentativas de injeção
• Matriz de códigos de erro — 400/401/403/404/422/500 para cada rota
• Paginação — primeira/última/vazia/páginas muito grandes
• Uploads de arquivo — válidos, muito grandes, tipo MIME errado, vazio
• Rate limiting — detecção de burst, limites por usuário vs. global

Quando Usar

• Nova API adicionada — gerar scaffold de testes antes de escrever a implementação (TDD)
• API legada sem testes — escanear e gerar cobertura de baseline
• Revisão de contrato de API — verificar se os testes existentes correspondem às definições de rota atuais
• Verificação de regressão pré-release — garantir que todas as rotas tenham pelo menos testes de fumaça
• Preparação para auditoria de segurança — gerar testes de entrada adversariais

Detecção de Rotas

Next.js App Router

# Encontrar todos os handlers de rota
find ./app/api -name "route.ts" -o -name "route.js" | sort

# Extrair métodos HTTP de cada arquivo de rota
grep -rn "export async function\|export function" app/api/**/route.ts | \
  grep -oE "(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)" | sort -u

# Mapa completo de rotas
find ./app/api -name "route.ts" | while read f; do
  route=$(echo $f | sed 's|./app||' | sed 's|/route.ts||')
  methods=$(grep -oE "export (async )?function (GET|POST|PUT|PATCH|DELETE)" "$f" | \
    grep -oE "(GET|POST|PUT|PATCH|DELETE)")
  echo "$methods $route"
done

Express

# Encontrar todos os arquivos de router
find ./src -name "*.ts" -o -name "*.js" | xargs grep -l "router\.\(get\|post\|put\|delete\|patch\)" 2>/dev/null

# Extrair rotas com números de linha
grep -rn "router\.\(get\|post\|put\|delete\|patch\)\|app\.\(get\|post\|put\|delete\|patch\)" \
  src/ --include="*.ts" | grep -oE "(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

# Gerar mapa de rotas
grep -rn "router\.\|app\." src/ --include="*.ts" | \
  grep -oE "\.(get|post|put|delete|patch)\(['\"][^'\"]+['\"]" | \
  sed "s/\.\(.*\)('\(.*\)'/\U\1 \2/"

FastAPI

# Encontrar todos os decoradores de rota
grep -rn "@app\.\|@router\." . --include="*.py" | \
  grep -E "@(app|router)\.(get|post|put|delete|patch)"

# Extrair com path e nome da função
grep -rn "@\(app\|router\)\.\(get\|post\|put\|delete\|patch\)" . --include="*.py" | \
  grep -oE "@(app|router)\.(get|post|put|delete|patch)\(['\"][^'\"]*['\"]"

Django REST Framework

# Extração de urlpatterns
grep -rn "path\|re_path\|url(" . --include="*.py" | grep "urlpatterns" -A 50 | \
  grep -E "path\(['\"]" | grep -oE "['\"][^'\"]+['\"]" | head -40

# Registro de router ViewSet
grep -rn "router\.register\|DefaultRouter\|SimpleRouter" . --include="*.py"

Padrões de Geração de Testes

Matriz de Testes de Autenticação

Para cada endpoint autenticado, gerar:

Matriz de Validação de Entrada

Para cada endpoint POST/PUT/PATCH com corpo de requisição:

Exemplos de Arquivos de Teste

→ Ver references/example-test-files.md para detalhes

Gerando Testes a Partir do Escaneamento de Rotas

Quando dado uma base de código, siga este processo:

1. Escanear rotas usando os comandos de detecção acima
2. Ler cada handler de rota para entender:
   • Schema do corpo da requisição esperado
   • Requisitos de autenticação (middleware, decoradores)
   • Tipos de retorno e status codes
   • Regras de negócio (propriedade, verificações de papel)
3. Gerar arquivo de teste por grupo de rotas usando os padrões acima
4. Nomear testes descritivamente: "retorna 401 quando o token está expirado" não "teste de auth 3"
5. Usar factories/fixtures para dados de teste — nunca codificar IDs diretamente
6. Verificar o shape da resposta, não apenas o status code

Armadilhas Comuns

• Testar apenas caminhos felizes — 80% dos bugs vivem nos caminhos de erro; teste esses primeiro
• IDs de dados de teste codificados — use factories/fixtures; IDs mudam entre ambientes
• Estado compartilhado entre testes — sempre limpe em afterEach/afterAll
• Testar implementação, não comportamento — teste o que a API retorna, não como ela faz
• Testes de limite ausentes — erros de um-a-mais são extremamente comuns em paginação e limites
• Não testar expiração de token — tokens expirados se comportam diferente de tokens inválidos
• Ignorar Content-Type — teste que a API rejeita tipos de conteúdo errados (xml quando json é esperado)

Melhores Práticas

1. Um bloco describe por endpoint — mantém falhas isoladas e legíveis
2. Semeie dados mínimos — não carregue o banco inteiro; crie apenas o que o teste precisa
3. Use beforeAll para configuração compartilhada, afterAll para limpeza — não beforeEach para operações caras
4. Verifique mensagens/campos de erro específicos, não apenas status codes
5. Teste que campos sensíveis (senha, secret) nunca aparecem nas respostas
6. Para testes de autenticação, sempre teste o caso de "header ausente" separadamente de "token inválido"
7. Adicione testes de rate limit por último — podem interferir com outras suites de testes se executados em paralelo