Guia de Testes de API: Do Básico aos Fluxos Automatizados

APIs são os contratos entre sistemas de software. Quando uma API quebra, tudo que depende dela também quebra. Mesmo assim, os testes de API costumam ser tratados como algo secundário — algo feito manualmente em uma aba do navegador pouco antes do deploy. Uma estratégia adequada de testes de API detecta bugs cedo, documenta o comportamento esperado e dá confiança para colocar o código em produção.

O que é um teste de API?

Um teste de API envia uma requisição HTTP e verifica algo sobre a resposta:

• Status code — Recebemos 200 OK ou 404 Not Found?
• Corpo da resposta — A estrutura dos dados está correta? Os valores estão certos?
• Headers — O Content-Type está definido corretamente? O header de autenticação está presente?
• Tempo de resposta — O endpoint responde dentro de um tempo aceitável?
• Tratamento de erros — O que acontece com entradas inválidas? Recebemos erros com mensagens úteis?

Status codes HTTP que você precisa conhecer

Código	Significado	Quando você verá
200	OK	GET, PUT, PATCH bem-sucedidos
201	Created	POST bem-sucedido que cria um recurso
204	No Content	DELETE bem-sucedido ou ação sem corpo
400	Bad Request	Entrada inválida, JSON malformado, campos ausentes
401	Unauthorized	Token de autenticação ausente ou inválido
403	Forbidden	Autenticado, mas sem autorização
404	Not Found	Recurso não existe
409	Conflict	Recurso duplicado, conflito de versão
422	Unprocessable Entity	Erros de validação em JSON válido
429	Too Many Requests	Limite de requisições excedido
500	Internal Server Error	Bug no lado do servidor
503	Service Unavailable	Servidor fora do ar ou sobrecarregado

401 significa "quem é você?" — 403 significa "eu sei quem você é, mas você não pode fazer isso."

Testando manualmente com o API Request Builder

Antes de automatizar, entenda seus endpoints manualmente. Nosso API Request Builder permite que você:

• Defina o método HTTP (GET, POST, PUT, PATCH, DELETE)
• Adicione headers (Authorization, Content-Type, headers personalizados)
• Monte parâmetros de query sem precisar codificar a URL manualmente
• Escreva o corpo da requisição em JSON com realce de sintaxe
• Inspecione a resposta completa, incluindo headers e tempo de resposta

Isso é ideal para explorar uma nova API, depurar um endpoint específico ou verificar rapidamente uma correção.

Testando REST APIs: o ciclo CRUD completo

Para uma API hipotética /users, uma suite de testes completa cobre:

Criar (POST)

POST /users
Content-Type: application/json

{
  "name": "Alice Chen",
  "email": "alice@example.com",
  "role": "editor"
}

Verificar:

• Status 201 Created
• O corpo da resposta contém o usuário criado com um id gerado
• O header Location aponta para o novo recurso (ex.: /users/42)

Ler (GET)

GET /users/42
Authorization: Bearer <token>

Verificar:

• Status 200 OK
• O corpo corresponde ao usuário criado
• O id é 42

Atualizar (PUT / PATCH)

PATCH /users/42
Content-Type: application/json

{ "role": "admin" }

Verificar:

• Status 200 OK
• O campo role agora é "admin" na resposta
• Os demais campos permanecem inalterados

Deletar (DELETE)

DELETE /users/42
Authorization: Bearer <token>

Verificar:

• Status 204 No Content
• Um GET /users/42 subsequente retorna 404

Testes negativos: os testes que a maioria das pessoas ignora

Os testes positivos verificam o caminho feliz. Testes negativos verificam se a API lida bem com entradas inválidas:

• Campos obrigatórios ausentes → 400 com mensagem de erro clara
• Tipos de dados inválidos ("age": "twenty") → 400
• Recurso inexistente (GET /users/99999) → 404
• Token expirado → 401
• Acesso aos dados de outro usuário → 403
• Envio de payload de 10 MB → 413 Payload Too Large
• Exceder limites de requisições → 429 com header Retry-After

Uma API bem projetada falha de forma previsível e informativa.

Padrões de teste de autenticação

Bearer tokens (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Cenários de teste:

• Token válido → resposta correta
• Token expirado → 401 com mensagem "Token expired"
• Token adulterado (alterar um caractere) → 401
• Header ausente → 401
• Token de ambiente diferente → 401

Use nosso JWT Decoder para inspecionar tokens e verificar tempos de expiração durante os testes manuais.

API keys

X-API-Key: sk_live_abc123

Teste: chave errada, chave ausente, chave com permissões insuficientes.

Fluxos OAuth 2.0

O OAuth adiciona complexidade — teste os endpoints de troca de tokens separadamente dos endpoints de recursos.

Validando corpos de resposta

Não verifique apenas os status codes. Valide a estrutura das respostas:

// Usando Jest + supertest
test("GET /users/:id retorna o usuário correto", async () => {
  const response = await request(app).get("/users/42").set("Authorization", `Bearer ${token}`);

  expect(response.status).toBe(200);
  expect(response.headers["content-type"]).toMatch(/json/);
  expect(response.body).toMatchObject({
    id: 42,
    name: expect.any(String),
    email: expect.stringMatching(/^[^\s@]+@[^\s@]+\.[^\s@]+$/),
    role: expect.oneOf(["admin", "editor", "viewer"]),
  });
});

Para schemas de resposta maiores, use validação de JSON Schema com nosso JSON Schema Validator para definir a estrutura esperada uma vez e testar todos os endpoints com base nela.

Testes de contrato

Em microsserviços, os testes de contrato garantem que consumidor e provedor concordem com o formato da API. O consumidor define o que precisa; o provedor verifica se está cumprindo. Ferramentas como o Pact automatizam esse processo.

Isso é especialmente valioso quando equipes diferentes são responsáveis por serviços distintos — um teste de contrato falha imediatamente quando um campo é renomeado ou removido, antes da integração.

Testes de performance e carga

Os testes funcionais dizem se a API funciona. Os testes de performance dizem quão bem ela funciona sob carga:

• Baseline — Qual é o tempo de resposta p50/p95/p99 com um único usuário?
• Teste de carga — Como ela se comporta no pico de tráfego esperado?
• Teste de estresse — A partir de que ponto ela começa a falhar?
• Teste de pico — O que acontece com um aumento repentino de tráfego de 10×?

Um objetivo comum: < 200ms para p95 no pico de carga esperado.

Checklist de testes de API

• Testar todas as operações CRUD para cada recurso
• Testar casos negativos: entrada inválida, autenticação ausente, recurso não encontrado
• Validar corpos de resposta com base em um schema (não apenas status codes)
• Testar casos extremos de autenticação: tokens expirados, ausentes e adulterados
• Verificar se as respostas de erro contêm mensagens úteis
• Verificar se paginação, filtragem e ordenação funcionam corretamente
• Testar o comportamento do limite de requisições
• Garantir que dados sensíveis não vazam nas respostas de erro
• Verificar o tempo de resposta na carga esperada

Bons testes de API são sua rede de segurança para refatorações e a melhor documentação que você pode ter — eles mostram exatamente o que cada endpoint faz e o que ele espera receber.