Guia o desenvolvedor na validação completa de APIs — contratos, endpoints, payloads, autenticação, códigos de status HTTP e comportamento sob condições de erro. Use esta skill SEMPRE que o objetivo for testar interfaces de programação de aplicações, independentemente da ferramenta (Postman, curl, código, insomnia ou qualquer HTTP client). Acione quando o usuário mencionar: "testar API", "teste de API", "API testing", "validar endpoints", "testar REST", "testar GraphQL", "testar contrato de API", "verificar se a API está retornando certo", "testar autenticação da API", "testar headers", "criar coleção de testes para minha API", "como testar meus endpoints". Não confundir com teste de integração (que testa comunicação entre módulos internos) — esta skill foca especificamente em interfaces HTTP. Agnóstica de linguagem e ferramenta.
Guia o desenvolvedor na validação completa de APIs — contratos, endpoints, payloads, autenticação, códigos de status HTTP e comportamento sob condições de erro. Use esta skill SEMPRE que o objetivo for testar interfaces de programação de aplicações, independentemente da ferramenta (Postman, curl, código, insomnia ou qualquer HTTP client). Acione quando o usuário mencionar: "testar API", "teste de API", "API testing", "validar endpoints", "testar REST", "testar GraphQL", "testar contrato de API", "verificar se a API está retornando certo", "testar autenticação da API", "testar headers", "criar coleção de testes para minha API", "como testar meus endpoints". Não confundir com teste de integração (que testa comunicação entre módulos internos) — esta skill foca especificamente em interfaces HTTP. Agnóstica de linguagem e ferramenta.
O teste de API valida que uma interface de programação de aplicações (API) se comporta conforme especificado — aceitando as entradas corretas, retornando as saídas esperadas, protegendo recursos com autenticação adequada e comunicando erros de forma clara e padronizada. É uma forma de teste de caixa preta aplicada especificamente ao contrato de uma API, seja ela REST, GraphQL, RPC ou qualquer outro estilo.
Quando usar
Quando quer validar que seus endpoints retornam os dados e status codes corretos
Quando quer verificar se a autenticação e autorização estão funcionando corretamente
Quando quer criar um conjunto de testes automatizáveis para sua API
Quando precisa validar que a API está seguindo o contrato definido (OpenAPI/Swagger)
Quando integra com uma API de terceiros e quer verificar o comportamento antes de usar
Quando faz uma mudança na API e quer garantir que o contrato não foi quebrado
Quando quer testar o comportamento da API com dados inválidos ou malformados
Quando NÃO usar
Quando quer testar a comunicação entre módulos internos (não expostos como API) → use teste-de-integracao
Quando quer testar apenas a interface visual do usuário → use teste-de-sistema
Quando quer fazer um teste de segurança profundo (pentest) → use teste-de-seguranca
Como funciona — Processo Passo a Passo
Passo 1: Mapeamento de endpoints
Liste todos os endpoints a testar. Agrupe por recurso (ex: /usuarios, /produtos, /pedidos). Para cada endpoint, anote: método HTTP (GET, POST, PUT, DELETE, PATCH), path, parâmetros esperados e body format.
Passo 2: Testes de contrato básico (caminho feliz)
Para cada endpoint: envie uma requisição válida e verifique que o status code está correto, a estrutura do response está conforme esperado e os campos obrigatórios estão presentes.
Passo 3: Testes de autenticação
Sem token/credencial → deve retornar 401 Unauthorized
Token expirado → deve retornar 401
Token inválido → deve retornar 401
Token de outro usuário tentando acessar recurso privado → deve retornar 403 Forbidden
Token válido com permissão correta → deve retornar 200 (ou o código esperado)
Passo 4: Testes de validação de input
Campos obrigatórios ausentes → deve retornar 400 ou 422
Tipos de dados incorretos (string onde espera número) → deve retornar 400 ou 422
Valores fora dos limites (strings muito longas, números negativos) → comportamento definido
Payload completamente vazio → deve retornar 400
Payload com JSON malformado → deve retornar 400
Passo 5: Testes de erro e não encontrado
Recurso inexistente → deve retornar 404 Not Found
Método HTTP não suportado naquele endpoint → deve retornar 405 Method Not Allowed
Corpo da requisição em formato incorreto (ex: XML quando espera JSON) → 415 ou 400
Passo 6: Testes de idempotência (quando aplicável)
PUT/PATCH: chamar duas vezes com os mesmos dados deve produzir o mesmo resultado
DELETE: chamar duas vezes no mesmo recurso — segunda deve retornar 404 (recurso já removido)
POST: chamar duas vezes — cria duplicata ou retorna erro de conflito (409)?
Passo 7: Documentação dos casos
Consolide: endpoint | método | cenário | input | status esperado | campos esperados no body de resposta.
Critérios de Qualidade
Pelo menos 1 caso de caminho feliz por endpoint
Todos os cenários de autenticação testados (sem token, expirado, inválido, válido)
Validação de input para todos os campos obrigatórios e com restrições
Códigos de erro cobertos com o comportamento esperado documentado
Casos de teste são independentes (não dependem de estado gerado por outro teste)
A estrutura do response (campos e tipos) é verificada, não apenas o status code
Exemplo Conceitual
Cenário: Endpoint POST /pedidos — cria um novo pedido.
Caso
Método
Input
Status esperado
Verificação adicional
Caminho feliz
POST
pedido válido com todos os campos
201 Created
body retorna o pedido criado com id
Campo obrigatório ausente
POST
sem campo produto_id
422
body contém mensagem de erro descritiva
Usuário não autenticado
POST
sem token
401
body contém erro de autenticação
Usuário sem permissão
POST
token de cliente tentando criar como admin
403
acesso negado
ID de produto inexistente
POST
produto_id: "xyz-inexistente"
404
body indica que produto não existe
Checklist de Conclusão
Listei todos os endpoints a testar antes de criar casos?
Testei autenticação: sem token, token inválido, token expirado, token sem permissão?
Testei campos obrigatórios ausentes e tipos de dados incorretos?
Cobri os status codes: 200, 201, 400, 401, 403, 404, 422?
Verifiquei a estrutura do body de resposta (campos e tipos), não só o status code?
Os casos de teste são agnósticos de ferramenta (funcionam com qualquer HTTP client)?
Casos de teste são independentes entre si?
Skills Relacionadas
Skill
Relação
Quando preferir aquela
teste-de-caixa-preta
Base teórica — esta skill é caixa preta aplicada a APIs
Quando quer a técnica genérica sem foco em HTTP
teste-de-integracao
Complementar — quando a API é parte de uma integração maior
Quando quer testar o fluxo completo entre módulos que usam a API
teste-de-seguranca
Extensão — testes de segurança mais profundos na API
Quando quer ir além dos cenários de autenticação básica
