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. São um campo ausente, um código de status errado, um timeout sob carga, ou uma mudança que quebra o contrato porque ninguém o verificou. Testes ad-hoc pegam alguns desses por sorte. Uma estratégia os pega de propósito.

Uma estratégia de teste de API é um plano para o que você testa, em qual camada, e em que momento do ciclo de entrega. Ela decide quais verificações rodam em cada commit, quais rodam diariamente (noturnamente), e quais rodam antes de um lançamento. Ela diz onde você deve investir esforço para obter a maior cobertura com a menor manutenção.

botão

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

Uma estratégia responde a quatro perguntas antes de você escrever uma única asserção.

O que você testa? Os endpoints e fluxos que agregam valor ao negócio. Uma API de checkout precisa de mais cobertura do que um endpoint de verificação de saúde. Classifique por risco e tráfego, não pela facilidade de acessar o endpoint.

Em qual camada? Algumas verificações pertencem a uma única requisição. Outras precisam de dois ou três serviços conversando entre si. Colocar todas as verificações na camada superior torna sua suíte lenta e frágil.

Quando ela é executada? As verificações rápidas rodam em cada push. As verificações lentas rodam em um cronograma ou antes do lançamento. Misturar as duas significa que seu feedback é lento ou sua cobertura é fina.

O que conta como aprovação? Um teste que verifica apenas uma resposta 200 diz quase nada. Defina o código de status, o esquema, os valores dos campos e o tempo de resposta que você espera.

Uma vez que você consegue responder a essas quatro perguntas para sua API, você tem uma estratégia. O resto deste guia preenche os detalhes.

Por Que Uma Estratégia Supera Testes Ad-Hoc

Testes ad-hoc significam que você envia uma requisição, inspeciona a resposta e segue em frente. Funciona para uma demonstração. Falha em um serviço real por três motivos.

Não se repete. A próxima pessoa não pode reexecutar sua verificação manual, então as regressões voltam. Um teste automatizado e salvo roda da mesma forma todas as vezes.

Inclina-se para o "caminho feliz". Quando você testa manualmente, você testa o que espera que funcione. Raramente envia o payload malformado, o token expirado ou a lista de 10.000 itens. Esses são os casos que quebram em produção.

Não escala. Um serviço com 40 endpoints e 5 ambientes são 200 verificações manuais por lançamento. Ninguém faz isso manualmente, então a cobertura encolhe à medida que a API cresce. Uma estratégia troca um custo de configuração único por cobertura repetível: você escreve os testes uma vez, e eles rodam em cada mudança sem você.

A Pirâmide de Testes de API

A pirâmide de testes é uma regra prática para saber quantos testes escrever em cada camada. Larga na base, estreita no topo.

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

Camada inferior: verificações de requisição única. Cada teste atinge um endpoint e faz asserções na resposta. Estes são rápidos, baratos de escrever e fáceis de depurar. Quando um falha, você sabe exatamente qual endpoint quebrou. A maioria dos seus testes vive aqui.

Camada intermediária: verificações de integração e contrato. Estas verificam se os serviços concordam com a forma dos dados que trocam, e se uma requisição que toca dois ou três sistemas retorna o resultado correto. Eles são mais lentos porque envolvem mais partes móveis, mas pegam as falhas que os testes de requisição única perdem.

Camada superior: fluxos ponta a ponta. Estes executam uma jornada completa do usuário através de vários endpoints: criar um pedido, pagá-lo, verificar o status. Eles dão a maior confiança e custam mais para manter, então mantenha-os poucos e reserve-os para caminhos críticos.

O erro que as equipes cometem é inverter a pirâmide: uma pilha de testes lentos ponta a ponta e quase nenhum teste rápido. Isso lhe dá longos ciclos de feedback e falhas instáveis. Empurre a cobertura para baixo na pirâmide sempre que uma camada inferior puder detectar o mesmo bug.

Os Tipos de Teste e Quando Cada Um se Aplica

Uma estratégia completa usa vários tipos de teste, cada um visando uma classe diferente de falha. Aqui está o que cada um verifica e quando usá-lo.

Teste Funcional

O teste funcional verifica se um endpoint faz o que sua especificação diz. Envia uma requisição válida, faz asserções no código de status, no esquema da resposta e nos valores dos campos. Esta é a base da sua suíte e a primeira coisa a automatizar em qualquer novo endpoint. Para uma análise mais aprofundada, veja teste funcional de API.

Uma verificação funcional para um endpoint de usuário se parece com isto:

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

Asserções:

Status é 200.
Corpo corresponde ao esquema User.
id é igual a 42.
email é uma string de email válida.

Teste de Integração

O teste de integração verifica se os endpoints funcionam juntos e se sua API se comunica corretamente com suas dependências: o banco de dados, um provedor de pagamento, um serviço downstream. Um teste funcional pode passar com uma dependência simulada e ainda falhar quando a real é conectada. Testes de integração preenchem essa lacuna. O método completo é abordado em teste de integração de API.

Teste de Regressão

O teste de regressão reexecuta sua suíte existente após cada mudança para confirmar que você não quebrou algo que costumava funcionar. É aqui que uma suíte automatizada e salva mostra seu valor. Você não escreve novos testes de regressão; você executa os testes que já tem, em um cronograma e antes do lançamento. Veja teste de regressão para saber como estruturá-lo.

Teste de Contrato

O teste de contrato verifica se o provedor e o consumidor de uma API concordam com a forma exata da requisição e da resposta. Ele detecta mudanças que quebram (um campo renomeado, uma mudança de tipo, um endpoint removido) antes que cheguem a um consumidor. Se você publica uma API da qual outras equipes ou clientes dependem, o teste de contrato não é opcional. Os detalhes estão em teste de contrato de API.

Teste de Carga e Performance

O teste de carga mede como sua API se comporta sob tráfego concorrente: tempo de resposta no percentil 95, taxa de erro, throughput e o ponto onde se degrada. Execute-o antes de um lançamento, antes de um pico de tráfego conhecido e periodicamente para detectar desvios lentos. Esta é uma disciplina separada do teste funcional e usa ferramentas diferentes; veja ferramentas de teste de carga para opções.

Teste de Segurança

O teste de segurança verifica se sua API rejeita o que deveria rejeitar: requisições sem token, requisições com o escopo errado, tentativas de injeção e acesso a dados de outro usuário. Todo endpoint que toca dados sensíveis precisa de, no mínimo, verificações de autenticação e autorização. O conjunto completo de técnicas está em teste de segurança de API.

Aqui está um guia aproximado de quando cada tipo é executado:

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

Casos Positivos, Negativos e de Borda

Para cada endpoint, cubra três tipos de entrada. Pular o segundo e o terceiro é a lacuna mais comum em uma suíte real.

Casos positivos enviam entrada válida e esperam sucesso. Uma requisição de criação de usuário com um corpo bem formado retorna 201 e o novo registro. Estes confirmam que o endpoint funciona.

Casos negativos enviam entrada inválida e esperam uma falha limpa e correta. Um campo obrigatório ausente deve retornar 400, não 500. Uma requisição sem token deve retornar 401. Uma requisição para um registro que você não possui deve retornar 403 ou 404, nunca o registro. O teste negativo verifica seu tratamento de erros, que é onde as APIs mais frequentemente vazam ou travam.

Casos de borda forçam os limites da entrada válida: uma lista vazia, o comprimento máximo permitido de string, um zero, um número negativo, um nome Unicode, um carimbo de data/hora em um limite de horário de verão. Estes encontram os bugs de "off-by-one" (erro por um) e de estouro (overflow).

Uma regra sólida: para cada teste positivo, escreva pelo menos um teste negativo. Se seu endpoint de criação de pedido tem um teste de caminho feliz e nenhum teste para uma quantidade negativa ou um ID de cliente ausente, sua cobertura é mais fina do que parece.

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

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

Esperado: status 400, corpo contém um erro de validação claro nomeando quantity. Se isso retornar 201 ou 500, você encontrou um bug que o teste de caminho feliz nunca pegaria.

Dados de Teste e Ambientes

Os testes são tão confiáveis quanto os dados e o ambiente em que são executados.

Use dados de teste dedicados. Não teste contra registros de produção e não dependa da existência de uma linha específica. Gere os dados que seu teste precisa ou inicialize um dado fixo conhecido no início da execução. Para entradas realistas e variadas, um gerador de dados economiza horas; veja como criar dados de teste de API realistas.

Torne os testes independentes. Cada teste deve configurar seu próprio estado e limpar-se depois. Um teste que depende de um teste anterior ter sido executado é um teste que falha em uma ordem aleatória. Quando você precisa passar um valor de uma requisição para a próxima (um ID, um token), faça-o explicitamente dentro do cenário, não através de um estado global compartilhado.

Isole ambientes. Mantenha ambientes separados para desenvolvimento local, CI, staging e produção. Armazene a URL base, tokens e outras configurações por ambiente para que o mesmo teste seja executado em qualquer lugar, trocando uma variável. Entender a diferença entre um sandbox e um ambiente de teste completo ajuda você a escolher o alvo certo; veja sandbox vs ambiente de teste.

Parametrize com variáveis. Nunca codifique (hardcode) um host ou um segredo em um teste. Referencie uma variável de ambiente para que o mesmo cenário seja executado contra o ambiente local, staging e CI sem edições.

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

Shift left significa mover os testes para mais cedo no ciclo de entrega, mais próximo do momento em que o código é escrito. Quanto mais tarde um bug é encontrado, mais caro é para corrigir. Uma incompatibilidade de esquema detectada na fase de design é uma edição de cinco minutos. A mesma incompatibilidade detectada em produção é um incidente.

Três movimentos práticos movem seus testes para a esquerda:

Projete o contrato primeiro. Defina os esquemas de requisição e resposta da API antes de construir o endpoint. Agora você pode gerar testes e mocks a partir desse contrato e começar a testar a interface antes que a implementação exista.

Teste contra um mock enquanto o backend está inacabado. O trabalho de front-end e integração não precisa esperar pelo endpoint real. Um servidor de mock construído a partir do esquema permite que os consumidores testem seu lado em paralelo.

Execute verificações rápidas em cada commit. Testes funcionais e de contrato que são executados em segundos pertencem ao ciclo interno do desenvolvedor, não a um lote noturno. Quanto mais cedo um desenvolvedor vê um teste vermelho, mais barata é a correção.

O argumento completo para isso está em teste shift-left no desenvolvimento de API. A recompensa é simples: bugs custam menos quando você os encontra mais cedo.

Automatizando Testes na CI

Uma estratégia só é real se for executada sem você. O objetivo é um pipeline que execute sua suíte a cada push, bloqueie um merge em caso de falha e produza um relatório que você possa ler.

Um pipeline de CI típico para testes de API tem três estágios:

A cada push: execute os testes funcionais e de contrato rápidos. Falhe a build se alguma asserção falhar. Esta é sua porta.
Diariamente (noturnamente) ou pré-lançamento: execute as suítes de integração e ponta a ponta mais lentas, além das verificações de carga e segurança.
Sempre: publique um relatório legível por máquina (JUnit XML é o formato comum) para que seu painel de CI mostre as contagens de aprovação e falha.

Um trabalho mínimo de GitHub Actions que executa uma suíte de testes de API em cada push se parece com isto:

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 exato depende da sua ferramenta. O padrão é o mesmo em todos os lugares: faça checkout do código, configure o ambiente de execução, execute a suíte e deixe um código de saída diferente de zero falhar a build. Para o tratamento completo de CI, incluindo cache, segredos de ambiente e relatórios, veja como automatizar testes de API em CI/CD.

Como o Apidog se Encaixa na Estratégia

A estratégia acima é agnóstica a ferramentas. Você pode montá-la a partir de ferramentas separadas para design, teste, mocking e documentação. O custo disso é o desvio: a especificação, os testes e o mock ficam dessincronizados, e você gasta tempo reconciliando-os.

Apidog condensa isso em um só lugar. Você projeta o contrato da API, escreve cenários de teste contra ele, gera um mock do mesmo esquema e publica a documentação, tudo a partir de uma única fonte de verdade. Como os testes e o mock vêm do mesmo contrato, o teste de contrato e o teste "shift-left" deixam de ser trabalho extra: eles são o padrão.

Para a metade CI da estratégia, a CLI do Apidog executa seus cenários e suítes de teste salvos de forma *headless* (sem interface gráfica). É um pacote Node, então ele se encaixa em qualquer etapa de CI que possa executar Node.

Instale-o:

npm install -g apidog-cli

Execute um cenário ou suíte salvo em CI. O comando de execução é baseado em flags; você passa o ID do alvo, o ID do ambiente e os repórteres que deseja:

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

--access-token autentica a execução. Armazene o token como um segredo de CI e referencie-o como uma variável de ambiente.
-t é o ID do cenário, pasta ou suíte que você deseja executar.
-e é o ID do ambiente, para que a mesma suíte seja executada contra staging ou CI trocando este valor.
-r escolhe um ou mais repórteres de cli, html, json e junit. A saída junit alimenta seu painel de CI; html fornece um relatório legível por humanos.

Para uma execução orientada a dados, aponte a CLI para um arquivo de dados ou um ID de dados de teste salvo:

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

Adicione --upload-report para enviar o relatório para a nuvem, ou --branch para executar contra uma branch específica. A CLI executa cenários e suítes Apidog salvos. Não é um enviador de requisições interativo nem um gerador de carga, então combine-o com uma ferramenta de carga dedicada para a camada de desempenho da sua pirâmide.

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

Se você está construindo uma estratégia do zero, siga esta lista em ordem.

[ ] Classifique seus endpoints por risco e tráfego. Cubra os principais primeiro.
[ ] Escreva um teste funcional positivo para cada endpoint classificado.
[ ] Adicione pelo menos um teste negativo por endpoint (autenticação ausente, entrada inválida).
[ ] Adicione testes de casos de borda para endpoints que aceitam listas, números ou texto livre.
[ ] Adicione testes de contrato para qualquer API que outras equipes ou clientes consumam.
[ ] Adicione testes de integração para fluxos que cruzam dois ou mais serviços.
[ ] Configure ambientes separados com variáveis e segredos por ambiente.
[ ] Use dados de teste gerados ou inicializados; mantenha os testes independentes.
[ ] Execute os testes rápidos em cada push na CI; falhe a build em caso de falha.
[ ] Agende as suítes lentas (integração, carga, segurança) diariamente (noturnamente) ou pré-lançamento.
[ ] Publique um relatório JUnit para que as contagens de aprovação e falha sejam visíveis.
[ ] Revise a suíte quando a API mudar; exclua testes para endpoints removidos.

Você não precisa de tudo isso no primeiro dia. Comece com testes funcionais e negativos nos seus endpoints de maior risco, faça-os rodar na CI e expanda a suíte a partir daí.

FAQ

Qual é a diferença entre uma estratégia de teste de API e um plano de teste?

Uma estratégia é a abordagem de alto nível: quais tipos de teste você usa, em qual camada e quando eles são executados. Um plano de teste é o documento concreto para um lançamento ou recurso específico: os endpoints exatos, casos, dados e critérios de aprovação. A estratégia é estável; o plano muda a cada lançamento.

Quantos testes devem existir em cada camada da pirâmide?

Não há uma proporção fixa, mas a forma importa mais do que os números. A maioria dos testes deve ser verificações rápidas de requisição única na base, menos testes de integração e contrato no meio, e apenas um punhado de testes de fluxo de trabalho ponta a ponta no topo. Se seus testes lentos da camada superior superam seus testes rápidos da camada inferior, reequilibre.

Preciso de teste de contrato se já tenho testes funcionais?

Sim, se outras equipes ou clientes consomem sua API. Testes funcionais verificam se um endpoint se comporta corretamente. Testes de contrato verificam se sua interface não mudou de uma forma que quebre um consumidor. Uma mudança pode manter um endpoint funcionando enquanto ainda quebra todos que o chamam.

Com que frequência devo executar testes de carga?

Execute-os antes de qualquer lançamento ou pico de tráfego conhecido, e em um cronograma (semanal ou mensal) para detectar desvios de desempenho. Testes de carga são lentos e consomem muitos recursos, então não devem ser executados em cada commit. Mantenha as camadas rápidas na CI e execute a carga separadamente.

Posso automatizar toda a estratégia em CI?

As partes repetíveis, sim. Testes funcionais, de integração, de contrato e de regressão são executados de forma limpa em um pipeline e controlam seus merges. Testes de carga e segurança geralmente são executados em seu próprio cronograma porque são mais lentos ou precisam de infraestrutura dedicada. Um executor de testes *headless* como a CLI do Apidog cobre a metade da CI, executando seus cenários salvos em cada push.