Testes de API
Como conferir status, corpo, cabeçalhos, erros e permissões de uma API com testes automatizados e isolados.
Cerca de 16 min · Revisado em
Ao final, você vai conseguir
- Conferir status, cabeçalhos, campos e tipos de uma resposta HTTP
- Explorar uma API com
curle transformar as verificações em asserções no código - Testar entradas inválidas, falta de login (
401) e falta de permissão (403) sem vazamento de dados - Explicar o que é um contrato de API e o que um teste de contrato protege
- Escrever testes isolados que criam e limpam os próprios dados e leem segredos de variáveis de ambiente
Por trás de cada tela de aplicativo existe uma API respondendo pedidos: o saldo do banco, o status da entrega, a lista de consultas do SUS. Quando ela erra, toda tela que depende dela erra junto, e às vezes do jeito mais perigoso: mostrando o pedido de uma pessoa para outra. Testar a API direto, sem tela, é rápido, estável e pega esses defeitos antes de qualquer clique. É uma das habilidades mais pedidas em vagas de QA.
O que conferir numa resposta
Na aula sobre API REST e contratos você viu que uma resposta HTTP tem três partes: o status (um número que resume o resultado), os cabeçalhos (informações sobre a resposta) e o corpo (os dados, quase sempre em JSON). Um teste de API é um programa que faz um pedido e confere as três, sem abrir nenhuma tela.
Uma resposta de GET /pedidos/1, do jeito que ela chega.
HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: 7f3a9c
{"id": 1, "cliente": "Ana", "total": 59.9, "pago": true}- Status: A primeira coisa a conferir.
200significa sucesso. Mas um status certo com corpo errado continua sendo bug, por isso ele é só o começo. - Cabeçalho de tipo: Diz em que formato o corpo veio. Se uma mudança fizer a API responder
text/html(uma página de erro do servidor, por exemplo), o aplicativo que espera JSON quebra. - Identificador do pedido: Muitas APIs mandam um código único por requisição. Guarde ele no relato de bug: com esse número, quem cuida do servidor acha o registro exato nos logs.
- Campo e tipo: Confira se o campo existe e se tem o tipo combinado:
59.9é número. Se virar o texto"59,90", a conta do carrinho no aplicativo deixa de funcionar. - Valor: Além do formato, confira o valor que a regra de negócio promete. Um pedido recém-pago deveria vir com
true.
| O que conferir | Pergunta | Exemplo de defeito |
|---|---|---|
| Status | O resultado é o esperado? | Pedido inexistente devolve 200 |
| Corpo e esquema | Os campos obrigatórios estão lá, com o tipo certo? | total sumiu ou virou texto |
| Cabeçalhos | O formato e as regras de cache estão certos? | Corpo em HTML |
| Casos de erro | Entrada inválida recebe uma resposta clara? | CEP com letras derruba o servidor com 500 |
| Login e permissão | Só quem pode vê e muda os dados? | Uma pessoa lê o pedido de outra |
Ao finalizar uma compra, a API responde 200 OK com o corpo {"erro": "Estoque insuficiente"}. O teste confere só o status. O que está acontecendo?
- O teste passa mesmo com a compra falhando, e a API deveria responder com um status de erro, como
409ou422 - Nenhum: se o status é
200, a operação deu certo - O problema é só do aplicativo, que deveria ler a mensagem de erro
- Basta o teste conferir que o corpo não está vazio
Conversando com a API sem tela
Antes de automatizar, você explora. O jeito mais direto é o curl, um programa de terminal que faz requisições HTTP. Com a opção -i, ele mostra o status e os cabeçalhos além do corpo. Com -H, você manda um cabeçalho, como o token de login.
Explore a API da loja com curl
A API está rodando no seu computador, na porta 3000. Leia cada resposta antes de seguir: o status da primeira linha diz muito.
API da loja rodando em http://localhost:3000Peça o pedido 1 sem estar logado e veja status e cabeçalhos:
curl -i http://localhost:3000/pedidos/1curl -i http://localhost:3000/pedidos/1HTTP/1.1 401 Unauthorized Content-Type: application/json; charset=utf-8 Content-Length: 22 {"erro":"Faça login"}Repita o pedido mandando o token da Ana no cabeçalho
Authorizationcom o valorBearer token-ana.curl -i -H "Authorization: Bearer token-ana" http://localhost:3000/pedidos/1HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 X-Request-Id: 7f3a9c Content-Length: 49 {"id":1,"cliente":"Ana","total":59.9,"pago":true}Ainda com o token da Ana, peça um pedido que não existe: o
999.curl -i -H "Authorization: Bearer token-ana" http://localhost:3000/pedidos/999HTTP/1.1 404 Not Found Content-Type: application/json; charset=utf-8 Content-Length: 33 {"erro":"Pedido não encontrado"}Agora tente ver o pedido 1, que é da Ana, usando o token do Bruno:
Bearer token-bruno.curl -i -H "Authorization: Bearer token-bruno" http://localhost:3000/pedidos/1HTTP/1.1 403 Forbidden Content-Type: application/json; charset=utf-8 Content-Length: 34 {"erro":"Este pedido não é seu"}
No terceiro passo, o pedido 999 voltou 404 Not Found. Você deveria abrir um relato de bug?
- Não. Esse é o comportamento esperado, e vale um teste para garantir que continue assim
- Sim. Qualquer status que não seja
200é um defeito - Só se a mensagem de erro estiver em inglês
Do olho para o código
Conferir no terminal funciona uma vez. Para conferir a cada mudança, você escreve as verificações em código. Cada verificação é uma asserção: uma afirmação que precisa ser verdadeira, senão o teste para e falha. Em Python, ela se escreve assert condição.
O mesmo teste de API em duas ferramentas comuns
Playwright (TypeScript)
import { test, expect } from '@playwright/test';
test('devolve o pedido da pessoa logada', async ({ request }) => {
const resposta = await request.get('/pedidos/1', {
headers: { Authorization: 'Bearer ' + process.env.TOKEN_ANA },
});
expect(resposta.status()).toBe(200);
expect(resposta.headers()['content-type']).toContain('application/json');
const pedido = await resposta.json();
expect(pedido).toMatchObject({ id: 1, cliente: 'Ana' });
expect(typeof pedido.total).toBe('number');
});pytest (Python)
import os
import requests
BASE = 'http://localhost:3000'
def test_devolve_o_pedido_da_pessoa_logada():
resposta = requests.get(
BASE + '/pedidos/1',
headers={'Authorization': 'Bearer ' + os.environ['TOKEN_ANA']},
)
assert resposta.status_code == 200
assert resposta.headers['Content-Type'].startswith('application/json')
pedido = resposta.json()
assert pedido['id'] == 1
assert isinstance(pedido['total'], (int, float))Conferir o esquema é conferir a forma da resposta: quais campos são obrigatórios e de que tipo cada um é. Ele pega a maioria das quebras causadas por mudanças apressadas, como um campo renomeado ou um número que virou texto.
Escreva um teste que pegue APIs quebradas
A API falsa devolve dicionários parecidos com respostas HTTP. Complete testar(api) com assert até ele passar com a API correta e falhar com cada uma das quatro versões com defeito. Confira também o pedido 999, que deve voltar 404. Rode e leia o placar no final.
# Uma API falsa: devolve um dicionário no formato de uma resposta HTTP
def api_correta(pedido_id):
if pedido_id == 1:
return {
'status': 200,
'headers': {'Content-Type': 'application/json'},
'body': {'id': 1, 'cliente': 'Ana', 'total': 59.9, 'pago': True},
}
return {
'status': 404,
'headers': {'Content-Type': 'application/json'},
'body': {'erro': 'Pedido não encontrado'},
}
# Versões com defeito, como as que aparecem depois de uma mudança apressada
def api_sem_total(pedido_id):
resposta = api_correta(pedido_id)
resposta['body'].pop('total', None)
return resposta
def api_total_texto(pedido_id):
resposta = api_correta(pedido_id)
if 'total' in resposta['body']:
resposta['body']['total'] = '59,90'
return resposta
def api_html(pedido_id):
resposta = api_correta(pedido_id)
resposta['headers']['Content-Type'] = 'text/html'
return resposta
def api_erro_disfarcado(pedido_id):
resposta = api_correta(pedido_id)
resposta['status'] = 200
return resposta
# Seu teste: recebe uma API e confere a resposta com assert
def testar(api):
resposta = api(1)
assert resposta['status'] == 200
# Escreva aqui as outras verificações
# Placar (não precisa mexer)
def pega_defeito(api):
try:
testar(api)
except Exception:
return True
return False
print('API correta passa:', not pega_defeito(api_correta))
for defeito in [api_sem_total, api_total_texto, api_html, api_erro_disfarcado]:
print(defeito.__name__, '->', 'pegou' if pega_defeito(defeito) else 'deixou passar')- O teste passa com a API correta
- Pega a resposta sem o campo
total - Pega o
totalque virou texto - Pega o cabeçalho
Content-Typeerrado - Pega o pedido inexistente respondido com
200
Erros, login e permissão
Caminho feliz é o uso em que tudo dá certo: dados válidos, pessoa logada, pedido existente. Ele é o primeiro a ser testado e o que menos esconde bugs. Os defeitos mais caros moram nos outros caminhos: dado inválido, sessão expirada, pessoa tentando ver o que não é dela.
- Autenticação
- Descobrir quem está pedindo. É o crachá na portaria do prédio. Na API, costuma ser um token no cabeçalho
Authorization. Sem ele, ou com ele vencido, a resposta é401. - Autorização
- Decidir o que essa pessoa pode fazer. O crachá abre o seu andar, não o do vizinho. Logada mas sem permissão, a resposta é
403. - Validação
- Conferir se os dados enviados fazem sentido: CEP com 8 dígitos, quantidade positiva. Dado inválido deve receber
400ou422com uma mensagem clara, nunca um500.
Qual status a API deveria devolver em cada situação?
401 sem login · 403 sem permissão · 404 não existe · 422 dado inválido
- Pedir a lista de pedidos sem mandar token
- Usar um token que venceu ontem
- Bruno, logado, pede o pedido da Ana
- Pessoa cliente tenta acessar a rota de administração
- Pedir o produto
99999, que nunca foi cadastrado - Cadastrar endereço com CEP
abc12 - Fazer um pedido com quantidade
-2
Teste quem pode ver o pedido
Complete testar_acesso(api): sem token a resposta deve ser 401; com o token do Bruno, o pedido da Ana deve voltar 403 e sem nenhum dado do pedido no corpo. O teste precisa passar com a API correta e pegar as três versões com defeito.
CONTAS = {'token-ana': 'Ana', 'token-bruno': 'Bruno'}
PEDIDOS = {1: {'id': 1, 'cliente': 'Ana', 'total': 59.9}}
def api_correta(pedido_id, token=None):
pessoa = CONTAS.get(token)
if pessoa is None:
return {'status': 401, 'body': {'erro': 'Faça login'}}
pedido = PEDIDOS.get(pedido_id)
if pedido is None:
return {'status': 404, 'body': {'erro': 'Pedido não encontrado'}}
if pedido['cliente'] != pessoa:
return {'status': 403, 'body': {'erro': 'Este pedido não é seu'}}
return {'status': 200, 'body': dict(pedido)}
# Defeito 1: esqueceram de exigir login
def api_sem_login(pedido_id, token=None):
return {'status': 200, 'body': dict(PEDIDOS[pedido_id])}
# Defeito 2: exige login, mas não confere de quem é o pedido
def api_vaza_pedido(pedido_id, token=None):
if CONTAS.get(token) is None:
return {'status': 401, 'body': {'erro': 'Faça login'}}
return {'status': 200, 'body': dict(PEDIDOS[pedido_id])}
# Defeito 3: responde 403, mas manda os dados junto
def api_403_com_dados(pedido_id, token=None):
resposta = api_correta(pedido_id, token)
if resposta['status'] == 403:
resposta['body'] = dict(PEDIDOS[pedido_id], erro='Este pedido não é seu')
return resposta
def testar_acesso(api):
da_ana = api(1, 'token-ana')
assert da_ana['status'] == 200
# 1. Sem token, a API deve responder 401
# 2. Com o token do Bruno: 403 e nenhum dado do pedido no corpo
# Placar (não precisa mexer)
def pega_defeito(api):
try:
testar_acesso(api)
except Exception:
return True
return False
print('API correta passa:', not pega_defeito(api_correta))
for defeito in [api_sem_login, api_vaza_pedido, api_403_com_dados]:
print(defeito.__name__, '->', 'pegou' if pega_defeito(defeito) else 'deixou passar')- O teste passa com a API correta
- Pega a API que não exige login
- Pega a API que mostra o pedido da Ana para o Bruno
- Pega o
403que vaza os dados no corpo
Algumas APIs respondem 404 (não existe) quando alguém pede o pedido de outra pessoa, em vez de 403. Por quê?
Para não confirmar que o recurso existe. Com 403, quem está tentando adivinhar números de pedido descobre quais são reais. O importante para o teste é saber qual das duas a equipe escolheu, porque essa decisão faz parte do contrato, e conferir que nenhum dado vazou.
O contrato entre quem pede e quem responde
O contrato descreve as rotas, o que cada uma recebe, os campos e tipos da resposta e os status possíveis. Um formato muito usado para escrevê-lo é o OpenAPI, um arquivo YAML ou JSON que também gera documentação navegável.
Um trecho do contrato da rota de pedidos em OpenAPI.
/pedidos/{id}:
get:
responses:
'200':
content:
application/json:
schema:
type: object
required: [id, cliente, total]
properties:
id: { type: integer }
total: { type: number }
'404':
description: Pedido não encontrado- Rota: O caminho, com
{id}no lugar do número do pedido. - Método: O que se pode fazer nessa rota: aqui, consultar.
- Status prometido: Cada status possível é listado com o formato da resposta. Um status que não está aqui é uma quebra de contrato.
- Campos obrigatórios: Se algum desses faltar, quem consome a API pode quebrar. É exatamente o que o seu teste do exercício conferia.
- Tipo:
numberaceita59.9, não aceita"59,90". O tipo é parte da promessa. - Erro previsto: Erros também são combinados. Testar que eles acontecem do jeito descrito é tão importante quanto testar o sucesso.
Um teste de contrato confere se a API real cumpre o combinado. Há dois jeitos comuns. No mais simples, os testes validam cada resposta contra o esquema do OpenAPI. No outro, chamado de contrato guiado pelo consumidor, o aplicativo registra quais campos usa, e a API roda essas expectativas na própria CI antes de publicar (a ferramenta Pact é a mais conhecida).
A equipe da API renomeou total para valor_total, atualizou os próprios testes e publicou. Tudo verde. No dia seguinte, o carrinho do aplicativo mostra R$ NaN. Qual teste teria evitado isso?
- Um teste de contrato, que conferiria a resposta contra os campos que o aplicativo usa
- Mais testes de unidade na API
- Nenhum: renomear campo é normal e o aplicativo deveria se adaptar sozinho
Dados de teste que não atrapalham ninguém
Um teste isolado não depende de outro teste nem do que sobrou de uma execução anterior. A receita: cada teste cria os dados de que precisa, com nomes únicos, usa o identificador que a API devolveu e apaga o que criou no final, mesmo se falhar. E tudo isso num ambiente de teste, nunca no sistema que as pessoas usam de verdade.
Criar, usar e limpar: o finally roda mesmo quando a verificação falha.
test('cancela um pedido', async ({ request }) => {
const criado = await request.post('/pedidos', {
data: { cliente: 'teste-' + Date.now(), itens: [{ produto: 'Caneca', quantidade: 1 }] },
});
const { id } = await criado.json();
try {
const resposta = await request.post('/pedidos/' + id + '/cancelar');
expect(resposta.status()).toBe(200);
} finally {
await request.delete('/pedidos/' + id);
}
});Coloque em ordem o ciclo de um teste de API isolado.
- Criar os dados próprios do teste, com um nome único
- Guardar o identificador que a API devolveu
- Fazer a requisição que está sendo testada
- Conferir status, corpo e cabeçalhos
- Apagar o que foi criado, mesmo se a verificação falhou
Quais práticas deixam a suíte confiável e quais criam problemas?
Deixa confiável · Cria problemas
- Cada teste cria a própria pessoa usuária
- Ler o token de uma variável de ambiente
- Rodar contra um banco de laboratório que pode ser recriado
- Usar o identificador que a API devolveu ao criar
- O teste B usa o pedido que o teste A criou
- Escrever o token direto no código e enviar ao GitHub
- Testar o cadastro no sistema de produção
Uma última promessa de contrato que vale testar é a idempotência: repetir o mesmo pedido não muda o resultado além da primeira vez. Apagar o pedido 7 duas vezes deixa o sistema igual a apagar uma vez. Em pagamentos, isso é questão de dinheiro.
A internet falha no meio de um Pix e o aplicativo reenvia o mesmo pagamento automaticamente. Que teste de API protege a pessoa de pagar duas vezes?
- Enviar duas vezes o mesmo pagamento, com a mesma chave de idempotência, e conferir que só uma cobrança existe
- Enviar um pagamento e conferir que voltou
201 - Conferir que a API responde em menos de um segundo
Fechamento
- Um teste de API faz um pedido e confere status, corpo (campos e tipos) e cabeçalhos, sem abrir tela.
- Os bugs mais caros ficam fora do caminho feliz: teste dado inválido, falta de login (
401) e falta de permissão (403), conferindo que nenhum dado vaza. curl, Postman e Insomnia servem para explorar; a proteção de verdade é o teste em código, que roda a cada mudança.- O contrato, muitas vezes escrito em OpenAPI, é o combinado com quem usa a API; testes de contrato acusam quando ele é quebrado.
- Testes isolados criam os próprios dados, limpam no final e leem segredos de variáveis de ambiente.
Automatize três respostas de uma API
Escolha uma API de laboratório que você possa rodar no seu computador, como a de um projeto seu ou um exemplo de curso, e escreva testes automatizados para o sucesso, o erro e o acesso negado.
- Explore as rotas com
curl -iou Postman e anote os status e campos de cada resposta - Automatize um caso de sucesso conferindo status,
Content-Typee os tipos dos campos obrigatórios - Automatize uma entrada inválida e confira que a resposta é
4xxcom mensagem clara - Automatize um acesso negado: sem token e com o token de outra pessoa, sem vazar dados
- Faça os testes criarem os próprios dados e apagarem tudo no final, com o token lido de variável de ambiente