Como Escrever Casos de Teste de API: Template e Exemplo

Uma API instável raramente falha porque alguém se esqueceu de testá-la. Ela falha porque o teste executado verificou a coisa errada, ou não verificou nada além de um código de status 200. Um caso de teste de API bem escrito é a diferença entre pegar um contrato quebrado antes do lançamento e explicar a interrupção depois.

Este guia aborda o que é um caso de teste de API, os campos que um bom caso precisa e como escrever um do zero. Você verá um exemplo completo para um endpoint de login, e então construirá o mesmo teste no Apidog sem escrever um script.

O que realmente é um caso de teste de API

Um caso de teste de API é um conjunto definido de entradas, ações e resultados esperados, usado para confirmar que um endpoint se comporta corretamente sob uma condição específica. Ele é mais restrito que um cenário de teste. Um cenário diz “verificar login do usuário”. Um caso de teste diz “POSTar credenciais válidas para /auth/login e confirmar uma resposta 200 com um JWT no corpo em 800 ms.”

Cada caso foca em um único comportamento. Esse foco importa. Quando um teste amplo e multiuso falha, você ainda precisa investigar qual parte quebrou. Quando um caso focado falha, o nome da falha lhe diz a resposta. Se você ainda está mapeando como os casos se relacionam com cenários e scripts, cenário de teste vs caso de teste e caso de teste vs script de teste traçam as linhas claramente.

O teste de API geralmente abrange cinco ângulos, e seus casos devem se espalhar por todos eles:

• Funcional: o endpoint retorna os dados corretos para uma entrada válida?
• Negativo: ele rejeita entradas inválidas com o erro e o código de status corretos?
• Desempenho: ele responde dentro de um orçamento de tempo aceitável?
• Segurança: ele impõe autenticação, autorização e limites de entrada?
• Contrato: a resposta corresponde ao esquema documentado?

Uma suíte de testes que verifica apenas o 'caminho feliz' passará até que um usuário real envie um campo de senha vazio.

Por que você precisa de um modelo de caso de teste

Escrever cada caso a partir de uma página em branco produz uma cobertura inconsistente. Um engenheiro registra os códigos de status esperados; outro registra os corpos de resposta; um terceiro escreve “deve funcionar.” Um modelo corrige isso forçando a mesma estrutura todas as vezes.

Um modelo compartilhado oferece quatro vantagens concretas. A cobertura se torna auditável, porque cada caso possui os mesmos campos e as lacunas são visíveis. A integração é acelerada, porque um novo testador lê um formato em vez de cinco. Os casos se tornam reutilizáveis em diferentes lançamentos, já que um caso estruturado é fácil de clonar e ajustar. E a rastreabilidade se mantém, porque cada caso se vincula a um requisito ou endpoint.

Modelos também tornam a automação realista. Um caso estruturado se mapeia de forma limpa para uma etapa de teste automatizada; um caso vago precisa ser reescrito antes que uma máquina possa executá-lo.

A anatomia de um caso de teste de API robusto

Um modelo completo de caso de teste de API contém estes campos. Você não precisa de todos eles para cada caso, mas o conjunto principal é inegociável.

Os campos que as equipes mais ignoram são o tempo de resposta esperado e o corpo da resposta esperado. Ignorá-los é como um teste “passa” enquanto retorna um 200 com um payload vazio, ou um payload correto três segundos tarde demais.

Como escrever casos de teste de API passo a passo

Leia a documentação da API primeiro. Observe os parâmetros necessários, o método de autenticação, os códigos de status documentados e o esquema de resposta. Cada caso de teste é uma afirmação sobre o comportamento documentado, então a documentação é sua fonte da verdade. Ferramentas que leem uma especificação OpenAPI para gerar coleções de teste podem fornecer um esqueleto inicial.

Liste as condições que valem a pena testar. Para um único endpoint, isso geralmente significa: entrada válida, cada campo obrigatório ausente, cada campo malformado, uma requisição não autorizada, um token expirado e um payload excessivamente grande. Cada condição se torna um caso.

Prepare dados de teste distintos. Casos negativos precisam de dados que estejam errados de uma única maneira. Reutilizar o mesmo payload em vários casos oculta bugs, porque você só exercita um caminho.

Escreva o resultado esperado com precisão. “Retorna sucesso” não é uma asserção. “Retorna 200, corpo contém uma string token não vazia, expires_in é igual a 3600” é. A precisão aqui é o que faz o caso valer a pena ser executado.

Adicione o caso a uma suíte executável. Um caso em uma planilha documenta a intenção. Um caso em uma ferramenta de teste produz um "passou" ou "falhou". Agrupe casos relacionados para que todo o endpoint seja executado com um clique; suítes de teste existem exatamente para isso.

Mantenha os casos atualizados. Quando a API muda, os casos mudam com ela. Um caso obsoleto que afirma um esquema antigo é pior do que nenhum caso, porque falha pelo motivo errado e treina a equipe a ignorar compilações em vermelho.

Um exemplo prático: testando um endpoint de login

Considere um endpoint de autenticação padrão: POST /auth/login, que aceita um email e senha e retorna um JWT. Aqui estão quatro casos que o cobrem adequadamente.

AUTH-LOGIN-001: credenciais válidas (funcional, crítica)

• Endpoint: POST /auth/login
• Pré-condições: um usuário existe com o email dana@example.com
• Corpo: {"email": "dana@example.com", "password": "Correct-Horse-9"}
• Status esperado: 200
• Resposta esperada: corpo contém um token (string) não vazio, token_type igual a Bearer, expires_in igual a 3600
• Tempo de resposta esperado: abaixo de 800 ms

AUTH-LOGIN-002: senha errada (negativo, crítica)

• Corpo: {"email": "dana@example.com", "password": "wrong"}
• Status esperado: 401
• Resposta esperada: error igual a invalid_credentials; nenhum campo token presente
• Nota: a mensagem não deve revelar se o email existe

AUTH-LOGIN-003: campo de senha ausente (negativo, alta)

• Corpo: {"email": "dana@example.com"}
• Status esperado: 400
• Resposta esperada: error igual a validation_error; details nomeia o campo password

AUTH-LOGIN-004: email malformado (negativo, média)

• Corpo: {"email": "not-an-email", "password": "Correct-Horse-9"}
• Status esperado: 400
• Resposta esperada: error igual a validation_error

Quatro casos, um endpoint, e você já está verificando o contrato, o formato do erro, os códigos de status e um orçamento de latência. Adicione um caso de segurança para uma string de SQL-injection no campo de email e você terá uma suíte que vale a pena executar em cada commit.

Escrevendo o mesmo caso de teste no Apidog

Você pode executar todos os quatro casos acima sem escrever uma linha de script. No Apidog, um caso de teste de API é construído visualmente.

1. Importe ou defina o endpoint. Importe POST /auth/login de um arquivo OpenAPI, de uma coleção Postman, ou defina-o diretamente. O esquema da requisição se torna a base para cada asserção.
2. Adicione os dados da requisição. Insira o corpo para o caso AUTH-LOGIN-001. Para cobertura orientada a dados, anexe um arquivo CSV ou JSON para que um caso seja executado contra cada linha de credencial; é assim que o teste de API orientado a dados substitui quatro casos quase idênticos por um.
3. Defina asserções visualmente. Clique para afirmar que o status é igual a 200, que token existe e é uma string não vazia, que expires_in é igual a 3600, e que o tempo de resposta permanece abaixo de 800 ms. Nenhuma scriptagem é necessária.
4. Agrupe casos em um cenário de teste. Adicione todos os quatro casos de login a um cenário para que o endpoint seja totalmente exercitado em uma única execução.
5. Execute e leia o relatório. O Apidog executa o cenário, gera um relatório de aprovação/falha por caso e mostra a asserção exata que falhou. Você pode executar o cenário localmente, em um cronograma ou dentro da CI.

O ponto não é que a scriptagem esteja errada; é que um caso visual estruturado é mais rápido de escrever, mais fácil de revisar e mais difícil de errar sutilmente. Quando você precisa de código, o Apidog ainda permite que você use scripts personalizados. Para um fluxo de trabalho totalmente sem scripts, o teste de API sem Postman aborda a abordagem mais ampla.

Erros comuns a evitar

Afirmar apenas o código de status. Um 200 significa que a requisição foi processada, não que a resposta estava correta. Sempre afirme os campos do corpo.

Um caso gigante por endpoint. Quando falha, você não aprende nada. Divida por condição.

Dados de teste reutilizados. Se cada caso negativo envia o mesmo payload, você testa apenas um modo de falha.

Nenhuma asserção de latência. Regressões de desempenho passam silenciosamente quando nada mede o tempo de resposta.

Casos que nunca são automatizados. Um caso documentado que nenhum executor executa é um comentário, não um teste. Mova os casos para uma suíte que seja executada em cada compilação; gerar scripts de teste a partir de uma especificação OpenAPI é uma maneira rápida de iniciar essa suíte.

Baixe o Apidog se você quiser seguir o exemplo e construir os quatro casos de login você mesmo.

Perguntas frequentes

Quantos casos de teste um endpoint precisa? O suficiente para cobrir o "caminho feliz", cada falha de campo obrigatório, uma falha de autenticação e uma sonda de segurança. Para um endpoint simples, são de quatro a seis casos; para um complexo, pode ser mais.

Devo escrever casos antes da API ser construída? Sim. Escrever casos com base no design, priorizando o design, identifica falhas de contrato precocemente. Combine isso com a geração de casos de teste assistida por IA para rascunhar um primeiro conjunto rapidamente e depois refinar manualmente.

Planilha ou ferramenta de teste para armazenar casos? Uma planilha documenta a intenção, mas não pode executar. Mantenha os casos em uma ferramenta que os execute e reporte os resultados, para que um caso esteja sempre verde ou vermelho.

Qual é a diferença entre um caso de teste e um cenário de teste? Um cenário é o objetivo de alto nível (“verificar login”); um caso é uma verificação concreta e executável dentro dele. Veja cenário de teste vs caso de teste.