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 curl e 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. 200 significa 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.
As cinco perguntas de um teste de API
O que conferirPerguntaExemplo de defeito
StatusO resultado é o esperado?Pedido inexistente devolve 200
Corpo e esquemaOs campos obrigatórios estão lá, com o tipo certo?total sumiu ou virou texto
CabeçalhosO formato e as regras de cache estão certos?Corpo em HTML
Casos de erroEntrada inválida recebe uma resposta clara?CEP com letras derruba o servidor com 500
Login e permissãoSó 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 409 ou 422
  • 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:3000
  1. Peça o pedido 1 sem estar logado e veja status e cabeçalhos: curl -i http://localhost:3000/pedidos/1

    curl -i http://localhost:3000/pedidos/1
    HTTP/1.1 401 Unauthorized
    Content-Type: application/json; charset=utf-8
    Content-Length: 22
    
    {"erro":"Faça login"}
  2. Repita o pedido mandando o token da Ana no cabeçalho Authorization com o valor Bearer token-ana.

    curl -i -H "Authorization: Bearer token-ana" http://localhost:3000/pedidos/1
    HTTP/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}
  3. 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/999
    HTTP/1.1 404 Not Found
    Content-Type: application/json; charset=utf-8
    Content-Length: 33
    
    {"erro":"Pedido não encontrado"}
  4. 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/1
    HTTP/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 total que virou texto
  • Pega o cabeçalho Content-Type errado
  • 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 400 ou 422 com uma mensagem clara, nunca um 500.

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 403 que 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: number aceita 59.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.

  1. Explore as rotas com curl -i ou Postman e anote os status e campos de cada resposta
  2. Automatize um caso de sucesso conferindo status, Content-Type e os tipos dos campos obrigatórios
  3. Automatize uma entrada inválida e confira que a resposta é 4xx com mensagem clara
  4. Automatize um acesso negado: sem token e com o token de outra pessoa, sem vazar dados
  5. Faça os testes criarem os próprios dados e apagarem tudo no final, com o token lido de variável de ambiente

Referências

Cursos relacionados