DEV Community 1h ago

Como Testar APIs: Guia Prático de Estratégias para APIs Confiáveis

A maioria dos bugs de API não são exóticos: um campo ausente, um código de status errado, um timeout sob carga ou uma mudança que quebra o contrato porque ninguém validou. Testes ad-hoc encontram alguns por sorte. Uma estratégia encontra por padrão.

Experimente o Apidog hoje

Uma estratégia de teste de API define o que testar, em qual camada, quando executar e quais critérios determinam sucesso ou falha. Ela separa verificações rápidas para cada commit, suítes mais lentas para execução diária e testes críticos antes de releases.

O Que Uma Estratégia de Teste de API Realmente Significa

Antes de escrever qualquer asserção, responda a quatro perguntas.

1. O que você testa? Priorize endpoints e fluxos por risco e tráfego, não por facilidade. Exemplos:

Checkout, pagamento e autenticação: alta prioridade.
CRUD administrativo pouco usado: prioridade menor.
Health check: cobertura mínima.

2. Em qual camada? Nem tudo precisa ser ponta a ponta. Use camadas:

Requisição única para validações rápidas.
Integração para fluxos entre serviços.
Ponta a ponta para jornadas críticas.

3. Quando executa? Defina frequência por custo:

Testes rápidos: cada push.
Testes médios: cada commit ou execução diária.
Testes lentos: pré-release ou agenda dedicada.

4. O que conta como aprovação? Um 200 OK sozinho não valida quase nada. Inclua:

Código de status esperado.
Schema da resposta.
Campos obrigatórios.
Valores críticos.
Tempo de resposta aceitável.
Mensagem de erro em casos negativos.

Por Que Uma Estratégia Supera Testes Ad-Hoc

Testes ad-hoc funcionam para uma demonstração, mas falham em serviços reais. Eles têm três problemas.

Não são repetíveis – Se você testou manualmente uma requisição hoje, outra pessoa talvez não consiga repetir o mesmo cenário amanhã. Testes automatizados rodam do mesmo jeito a cada execução.

Favorecem o caminho feliz – Em testes manuais, é comum validar apenas o caso esperado: Payload válido. Token correto. Registro existente. Volume pequeno. Mas bugs críticos aparecem em casos como:

Campo obrigatório ausente.
Token expirado.
ID inválido.
Lista com 10.000 itens.
Payload malformado.

Não escalam – Uma API com 40 endpoints em 5 ambientes gera 200 verificações manuais por release. Na prática, ninguém mantém isso manualmente. Uma suíte automatizada transforma esse esforço em cobertura repetível: você escreve uma vez e executa a cada mudança.

A Pirâmide de Testes de API

Use a pirâmide para decidir onde concentrar a cobertura.

        /\
       /  \    Testes ponta a ponta / fluxo de trabalho
      /----\   poucos, lentos, alto valor
     /      \
    /--------\  Testes de integração / contrato
   /          \ alguns, velocidade média
  /____________\ Testes unitários / requisição única
                 muitos, rápidos, baratos

Base: verificações de requisição única – Cada teste chama um endpoint e valida a resposta. Use para:

Status code.
Schema.
Campos obrigatórios.
Validação de entrada.
Casos positivos e negativos simples.

Exemplo:

GET /api/users/42 HTTP/1.1
Host: api.example.com
Authorization: Bearer <token>

Asserções: Status é 200. Corpo segue o schema User. id é 42. email tem formato válido.

A maioria dos testes deve estar aqui.

Meio: integração e contrato – Use quando o comportamento depende de mais de um sistema:

API + banco de dados.
API + provedor de pagamento.
API + serviço downstream.
Provedor e consumidor precisam concordar sobre request/response.

Esses testes são mais lentos, mas capturam falhas que uma requisição isolada não vê.

Topo: fluxos ponta a ponta – Use apenas para jornadas críticas. Exemplo:

Criar pedido.
Pagar pedido.
Consultar status.
Validar confirmação.

Eles dão alta confiança, mas são mais caros de manter. Evite inverter a pirâmide com muitos testes E2E lentos e poucos testes rápidos.

Os Tipos de Teste e Quando Cada Um se Aplica

Uma estratégia completa combina vários tipos de teste.

Teste Funcional

Teste funcional valida se o endpoint faz o que a especificação diz. Ele verifica:

Status code.
Schema.
Campos retornados.
Regras de negócio.
Mensagens de erro.

Teste de Integração

Teste de integração valida se sua API funciona corretamente com dependências reais ou ambientes próximos do real. Use para verificar:

Persistência no banco.
Comunicação com serviços internos.
Integração com filas.
Chamadas a provedores externos.
Fluxos que cruzam múltiplos endpoints.

Veja o método completo em teste de integração de API.

Teste de Regressão

Teste de regressão reexecuta a suíte existente depois de mudanças para garantir que algo que funcionava não foi quebrado. Você não cria uma categoria separada de testes. Você reutiliza os testes funcionais, negativos, de integração e contrato já existentes. Execute:

A cada commit para testes rápidos.
Antes do release para suítes completas.
Em agenda diária para cobertura ampliada.

Veja teste de regressão.

Teste de Contrato

Teste de contrato garante que provedor e consumidor concordam sobre a interface da API. Ele detecta mudanças como:

Campo renomeado.
Tipo alterado.
Campo obrigatório removido.
Endpoint removido.
Estrutura de resposta incompatível.

Se outras equipes ou clientes consomem sua API, esse teste é essencial. Detalhes em teste de contrato de API.

Teste de Carga e Performance

Teste de carga mede o comportamento da API sob tráfego concorrente. Valide métricas como:

Tempo de resposta p95.
Taxa de erro.
Throughput.
Ponto de degradação.
Timeouts sob carga.

Execute antes de releases, antes de picos conhecidos e periodicamente para detectar degradação. Veja opções em ferramentas de teste de carga.

Teste de Segurança

Teste de segurança verifica se a API rejeita o que deveria rejeitar. Cubra pelo menos:

Requisição sem token.
Token expirado.
Escopo incorreto.
Acesso a dados de outro usuário.
Payloads de injeção.
Exposição indevida de dados.

Veja técnicas em teste de segurança de API.

Tipo de teste	Detecta	Executa
Funcional	Status, schema ou valores errados	A cada commit
Integração	Fluxos serviço-a-serviço quebrados	A cada commit ou diariamente
Regressão	Comportamento existente recém-quebrado	A cada commit e pré-release
Contrato	Mudanças que quebram a interface	A cada commit no provedor
Carga	Lentidão e falha sob tráfego	Pré-release e agendado
Segurança	Autenticação, injeção, exposição de dados	Pré-release e agendado

Casos Positivos, Negativos e de Borda

Para cada endpoint, cubra três grupos de entrada.

Casos positivos – Enviam entrada válida e esperam sucesso. Exemplo: Criar usuário com payload válido. Esperar 201. Validar o registro criado.

Casos negativos – Enviam entrada inválida e esperam erro controlado. Exemplos:

Campo obrigatório ausente retorna 400.
Token ausente retorna 401.
Usuário sem permissão retorna 403.
Registro inexistente retorna 404.
Payload inválido não deve retornar 500.

Casos de borda – Testam limites de entradas válidas. Exemplos:

Lista vazia.
String no tamanho máximo.
Valor 0.
Número negativo.
Nome com Unicode.
Timestamp em limite de horário de verão.

Regra prática: para cada teste positivo, escreva pelo menos um teste negativo.

Exemplo:

POST /api/orders HTTP/1.1
Content-Type: application/json

{
  "customerId": "c_123",
  "quantity": -5
}

Esperado: Status 400. Corpo contém erro de validação. Mensagem identifica o campo quantity. Se isso retornar 201 ou 500, o teste encontrou um bug que o caminho feliz não encontraria.

Dados de Teste e Ambientes

Testes confiáveis dependem de dados e ambientes previsíveis.

Use dados de teste dedicados – Evite:

Registros de produção.
IDs fixos que podem ser apagados.
Dados compartilhados entre testes.

Prefira:

Criar os dados no setup do teste.
Usar fixtures conhecidas.
Gerar dados realistas por execução.

Para entradas variadas, veja como criar dados de teste de API realistas.

Torne os testes independentes – Cada teste deve:

Preparar seu próprio estado.
Executar a ação.
Validar o resultado.
Limpar os dados criados, quando necessário.

Evite depender da ordem de execução. Se precisar usar um valor de uma requisição anterior, como userId ou token, passe esse valor explicitamente dentro do cenário.

Isole ambientes – Mantenha ambientes separados:

Local.
CI.
Staging.
Produção.

Armazene por ambiente:

Base URL.
Tokens.
Credenciais.
IDs de recursos.
Configurações específicas.

Veja a diferença entre sandbox vs ambiente de teste.

Parametrize com variáveis – Não faça hardcode de host ou segredo. Em vez disso, use variáveis:

{{baseUrl}}/api/users/{{userId}}

Assim, o mesmo teste roda em local, CI ou staging apenas trocando o ambiente.

Shift Left: Teste Mais Cedo, Não Apenas Mais

Shift left significa mover testes para mais perto do momento em que o código é escrito. Quanto mais cedo um bug aparece, mais barato é corrigir.

1. Projete o contrato primeiro – Defina request, response e schemas antes da implementação. Com isso, você consegue:

Revisar a interface antes do código.
Gerar mocks.
Criar testes baseados no contrato.
Alinhar consumidores e provedores cedo.

2. Teste contra mock enquanto o backend está incompleto – Um mock permite que frontend e integrações avancem sem esperar o endpoint real. Isso reduz bloqueios entre times.

3. Execute verificações rápidas em cada commit – Testes funcionais e de contrato rápidos devem rodar no ciclo interno do desenvolvedor, não apenas em jobs noturnos.

Leia mais em teste shift-left no desenvolvimento de API.

Automatizando Testes na CI

Uma estratégia só funciona se executar sem intervenção manual. Um pipeline mínimo deve:

Rodar testes rápidos a cada push.
Bloquear merge quando falhar.
Publicar relatório legível.
Separar suítes rápidas e lentas.

Estágios recomendados:

A cada push: testes funcionais e de contrato rápidos.
Diariamente ou pré-release: integração, ponta a ponta, carga e segurança.
Sempre: relatório em formato consumível pela CI, como JUnit XML.

Exemplo com GitHub Actions:

name: api-tests
on: [push]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Run API tests
        run: npm test

O comando depende da ferramenta, mas o padrão é o mesmo:

Fazer checkout do código.
Configurar runtime.
Instalar dependências.
Executar suíte.
Deixar código de saída diferente de zero falhar a build.

Veja o guia completo em como automatizar testes de API em CI/CD.

Como o Apidog se Encaixa na Estratégia

A estratégia é agnóstica a ferramentas. Você pode combinar ferramentas separadas para design, teste, mock e documentação. O risco é o desvio:

A especificação muda, mas os testes não.
O mock fica diferente do contrato.
A documentação fica desatualizada.
A suíte valida um comportamento antigo.

O Apidog centraliza essas partes em uma única fonte de verdade:

Design do contrato da API.
Cenários de teste.
Mock baseado no schema.
Documentação.
Execução de suítes salvas.

Para CI, a CLI do Apidog executa cenários e suítes salvos em modo headless. Como é um pacote Node, ela se encaixa em pipelines que executam Node.

Instale:

npm install -g apidog-cli

Execute uma suíte ou cenário salvo:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioOrSuiteId> \
  -e <environmentId> \
  -r cli,html,junit

Parâmetros principais:

--access-token: autentica a execução. Armazene como segredo da CI.
-t: ID do cenário, pasta ou suíte.
-e: ID do ambiente.
-r: repórteres, como cli, html, json e junit.

Para execução orientada a dados:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioId> \
  -e <environmentId> \
  -d ./data/users.csv \
  -r cli,junit

Você também pode usar:

--upload-report para enviar o relatório para a nuvem.
--branch para executar contra uma branch específica.

A CLI executa cenários e suítes salvos no Apidog. Ela não substitui uma ferramenta dedicada de carga, então mantenha testes de performance em uma camada separada.

Uma Lista de Verificação de Estratégia Inicial

Se você está começando do zero, siga esta ordem:

[ ] Classifique endpoints por risco e tráfego.
[ ] Cubra primeiro os endpoints críticos.
[ ] Escreva um teste funcional positivo por endpoint priorizado.
[ ] Adicione pelo menos um teste negativo por endpoint.
[ ] Cubra autenticação ausente e entrada inválida.
[ ] Adicione casos de borda para listas, números e texto livre.
[ ] Adicione testes de contrato para APIs consumidas por outras equipes ou clientes.
[ ] Adicione testes de integração para fluxos com dois ou mais serviços.
[ ] Configure ambientes separados com variáveis.
[ ] Armazene segredos na CI, não no código.
[ ] Gere ou inicialize dados de teste.
[ ] Mantenha testes independentes.
[ ] Rode testes rápidos a cada push.
[ ] Faça a build falhar quando a suíte falhar.
[ ] Agende suítes lentas para execução diária ou pré-release.
[ ] Publique relatório JUnit.
[ ] Revise a suíte quando a API mudar.
[ ] Remova testes de endpoints descontinuados.

Você não precisa implementar tudo no primeiro dia. Comece por testes funcionais e negativos nos endpoints de maior risco, coloque-os na CI e expanda a cobertura aos poucos.

FAQ

Qual é a diferença entre uma estratégia de teste de API e um plano de teste?
A estratégia define a abordagem geral: tipos de teste, camadas, frequência e critérios. O plano de teste é específico de um release ou funcionalidade: endpoints, casos, dados e critérios de aprovação. A estratégia tende a ser estável. O plano muda a cada entrega.

Quantos testes devem existir em cada camada da pirâmide?
Não há proporção fixa. O importante é o formato: Muitos testes rápidos de requisição única. Menos testes de integração e contrato. Poucos testes ponta a ponta. Se seus testes lentos superam os testes rápidos, reequilibre.

Preciso de teste de contrato se já tenho testes funcionais?
Sim, se outras equipes ou clientes consomem sua API. Testes funcionais verificam comportamento. Testes de contrato verificam compatibilidade da interface. Um endpoint pode continuar retornando 200 e ainda quebrar consumidores.

Read on DEV Community ↗ ← Back to News

Como Testar APIs: Guia Prático de Estratégias para APIs Confiáveis