The API Testing Checklist I Use for Every Endpoint

Três anos atrás, eu assisti a uma API de produção falhar espetacularmente às 2 da manhã porque ninguém testou o que acontece quando você envia um campo de data formatado como "32/13/2021." A cascata foi bela da pior maneira possível: 47.000 transações falhadas, clientes furiosos inundando os canais de suporte e um CEO que queria respostas que eu não tinha. Aquela noite mudou para sempre a minha forma de abordar os testes de API.

Eu sou Sarah Chen, e sou engenheira de automação de QA há oito anos, sendo os últimos cinco focados exclusivamente em testes de API para plataformas de fintech e saúde. Testei tudo, desde endpoints CRUD simples até APIs complexas de processamento de pagamentos que lidam com milhões de dólares diariamente. O que aprendi é o seguinte: a maioria das falhas de API não são casos exóticos de borda—são problemas previsíveis que uma lista de verificação sistemática teria detectado.

A lista de verificação que estou compartilhando hoje é a exata que uso para cada endpoint que testo. Ela salvou minha equipe de pelo menos uma dúzia de incidentes de produção apenas no último ano, e é abrangente o suficiente para que engenheiros juniores possam segui-la, enquanto é detalhada o suficiente para capturar problemas que desenvolvedores seniores podem perder. Isso não é teoria—esse é um processo testado em batalha refinado através de centenas de implementações de API.

Autenticação e Autorização: A Camada Fundamental

Antes de testar qualquer outra coisa, eu verifico o perímetro de segurança. Isso não se trata apenas de verificar se a autenticação funciona—é sobre sondar sistematicamente cada cenário de autenticação e limite de autorização. Eu vi APIs demais que funcionam perfeitamente com credenciais válidas mas falham catastroficamente ou vazam dados quando as credenciais estão ausentes, malformadas ou pertencem ao usuário errado.

Primeiro, testo sem nenhum token de autenticação. O endpoint deve retornar um status 401 Não Autorizado, não um 500 Erro Interno do Servidor, e definitivamente não dados reais. Encontrei APIs de produção que retornavam registros de usuários completos quando nenhum token de autenticação era fornecido porque o desenvolvedor assumiu que o middleware de autenticação sempre seria executado. Não foi.

Em seguida, testo com um token expirado. Isso captura um número surpreendente de problemas porque a lógica de expiração do token muitas vezes reside em uma parte diferente do código do que a autenticação inicial. A resposta deve ser um claro 401 com uma mensagem indicando que o token expirou, não um genérico "não autorizado" que deixa o cliente adivinhando se deve atualizar ou re-autenticar.

Depois, testo com um token malformado—strings aleatórias, tokens com caracteres removidos, tokens de outros sistemas. A API deve lidar com isso graciosamente sem expor rastros de pilha ou detalhes de erro interno. Uma vez encontrei uma API que travava todo o serviço quando recebia um token contendo certos caracteres Unicode porque a biblioteca de análise de JWT não estava lidando adequadamente com a codificação.

O teste de autorização é onde as coisas ficam interessantes. Testo com tokens válidos pertencentes a usuários que não deveriam ter acesso ao recurso. Para um endpoint GET /users/123, autentico como usuário 456 e tento acessar os dados de 123. A resposta deve ser 403 Proibido, não 404 Não Encontrado (que vaza informações sobre a existência do recurso) e definitivamente não 200 com os dados.

Eu também testo o controle de acesso baseado em função sistematicamente. Se sua API tem funções de administrador, gerente e usuário, testo cada endpoint com cada função. Mantenho uma planilha de matriz: as linhas são endpoints, as colunas são funções, as células contêm códigos de status esperados. Isso captura bugs de permissão antes de chegarem à produção, onde eles se tornam vulnerabilidades de segurança.

Validação de Solicitação: Teste de Limite de Entrada

A validação de entrada é onde a maioria das APIs mostra sua verdadeira qualidade. Uma API bem projetada valida cada campo de entrada minuciosamente e retorna mensagens de erro claras e acionáveis. Uma mal projetada aceita dados lixo ou trava misteriosamente.

"A maioria das falhas de API não são casos exóticos de borda—são problemas previsíveis que uma lista de verificação sistemática teria pegado."

Começo com testes de campos obrigatórios. Para cada campo obrigatório, envio uma solicitação sem ele. A API deve retornar 400 Solicitação Malformada com uma mensagem claramente identificando qual campo está faltando. Eu vi APIs que retornam "erro de validação" sem especificar o que falhou, forçando os desenvolvedores a adivinhar qual dos 15 campos causou o problema.

Depois testo a validação de tipo de dados. Se um campo espera um inteiro, envio strings, floats, booleanos, nulo, arrays e objetos. Cada um deve retornar um 400 com uma mensagem clara como "idade deve ser um inteiro" não "formato de solicitação inválido." Uma vez testei uma API de e-commerce onde enviar uma string para a quantidade fez com que o sistema criasse pedidos para zero itens, o que quebrou toda a cadeia de execução.

A validação do comprimento da string é crítica e muitas vezes negligenciada. Testo com strings vazias, caracteres únicos, strings no comprimento máximo, strings um caractere acima do máximo e strings absurdamente longas (mais de 10.000 caracteres). Eu já derrubei bancos de dados de produção enviando strings do tamanho de megabytes para campos que não estavam devidamente validados, causando exaustão da memória.

Para campos numéricos, testo valores de limite sistematicamente: zero, números negativos, decimais quando inteiros são esperados, números maiores que o valor máximo de inteiro e valores especiais como Infinito ou NaN. Uma API de pagamento que testei uma vez aceitou quantias de pagamento negativas, o que teria permitido que usuários creditassem suas contas de forma arbitrária.

A validação de data e hora merece atenção especial porque é consistentemente problemática. Testo com datas inválidas (30 de fevereiro, mês 13), vários formatos (ISO 8601, timestamps Unix, strings legíveis por humanos), datas muito no passado ou futuro, e casos de borda de fuso horário. O incidente às 2 da manhã que mencionei no início? Isso foi uma falha de validação de data.

Para campos de enumeração, testo com valores válidos, valores inválidos, variações de caso e nulo. Se a API aceita "ativo" e "inativo" como valores de status, vou tentar "ATIVO", "Ativo", "pendente", string vazia e nulo. Cada um deve ser aceito (se não for sensível a maiúsculas) ou rejeitado com uma mensagem clara listando as opções válidas.

Validação de Resposta: Garantindo a Integridade dos Dados

Testar o que retorna é tão importante quanto testar o que entra. Eu vi APIs que aceitam solicitações perfeitamente, mas retornam dados inconsistentes, incompletos ou mal formatados que quebram aplicações cliente.