Forem: Lucas

Como Usar Insomnia para Testar APIs: Guia Completo

Lucas — Fri, 22 May 2026 07:32:48 +0000

Insomnia é um cliente de API da Kong para enviar requisições e inspecionar respostas. Ele oferece uma interface limpa e suporta HTTP, REST, GraphQL, gRPC, SOAP e WebSocket em um só lugar. É uma boa opção quando você quer testar APIs sem usar uma ferramenta pesada no estilo IDE.

Experimente o Apidog hoje

Neste guia, você vai testar uma API no Insomnia do começo ao fim: criar uma coleção, enviar uma requisição, inspecionar a resposta, configurar ambientes, reutilizar variáveis e escrever suítes de teste com asserções automatizadas. Os exemplos usam uma API pública para que você possa reproduzir os passos imediatamente.

Instalar o Insomnia e criar uma requisição

Baixe o Insomnia pelo site oficial da Kong e instale-o na sua plataforma.

Ao abrir o app pela primeira vez, o Insomnia pode pedir login. Você pode trabalhar localmente sem conta, se preferir. Nesse modo, os dados ficam na sua máquina. A sincronização em nuvem é opcional e ficou mais relevante a partir da versão 8.

O Insomnia organiza o trabalho em coleções e documentos.

Para criar sua primeira requisição:

Clique em Criar.
Escolha Coleção de Requisições.
Nomeie a coleção, por exemplo: Testes de API de Usuário.
Dentro da coleção, clique em +.
Escolha Requisição HTTP.
Selecione o método GET.
Informe a URL:

GET https://jsonplaceholder.typicode.com/users/1

Clique em Enviar.

No painel de resposta, verifique:

código de status;
tempo de resposta;
tamanho da resposta;
corpo retornado;
cabeçalhos;
formatação automática do JSON.

Para respostas grandes, use filtros com JSONPath ou XPath para encontrar campos específicos.

Configurar métodos, parâmetros e autenticação

Para testar cenários reais, você normalmente precisa configurar corpo, query params, headers e autenticação. O Insomnia organiza esses itens em abas abaixo da barra de URL.

Enviar um corpo JSON

Crie uma requisição POST e selecione Corpo > JSON.

Exemplo:

{
  "name": "Daniel Okafor",
  "email": "daniel.okafor@example.com"
}

Quando você escolhe o tipo de corpo, o Insomnia configura automaticamente o cabeçalho:

Content-Type: application/json

Adicionar query params

Use a aba Consulta para adicionar parâmetros sem editar a URL manualmente.

Exemplo:

page=1
limit=10
sort=name

Isso ajuda a manter URLs longas legíveis e permite ativar ou desativar parâmetros individualmente.

Configurar headers

Use a aba Cabeçalhos para valores esperados pela API, como:

Accept: application/json
X-Request-Id: test-123

Configurar autenticação

Na aba Autenticação, escolha o esquema usado pela API. O Insomnia suporta, entre outros:

Token Portador;
Autenticação Básica;
Chave de API;
OAuth 1.0;
OAuth 2.0;
AWS IAM.

Para uma API protegida por bearer token:

Abra Autenticação.
Escolha Token Portador.
Informe o token ou referencie uma variável de ambiente.

Evite colar tokens diretamente em várias requisições. Prefira variáveis, por exemplo:

{{ _.auth_token }}

Se você está definindo quais respostas sua API deve retornar, a referência sobre códigos de status HTTP que as APIs REST devem usar pode ajudar.

Configurar ambientes e variáveis

Ambientes evitam repetição e facilitam alternar entre local, staging e produção.

No Insomnia, um ambiente é um objeto JSON de variáveis anexado a uma coleção.

Para configurar:

Abra o menu de ambiente no topo da barra lateral.
Clique em Gerenciar Ambientes.
Edite o Ambiente Base para valores compartilhados.
Crie sub-ambientes para cada destino.

Exemplo de ambiente:

{
  "base_url": "https://jsonplaceholder.typicode.com",
  "auth_token": "your-token-here"
}

Agora altere a URL da requisição para usar a variável:

GET {{ _.base_url }}/users/1

Para usar o token em uma requisição protegida:

Authorization: Bearer {{ _.auth_token }}

Ao trocar o ambiente ativo, todas as requisições que usam essas variáveis são atualizadas automaticamente.

Encadear requisições com tags de template

O Insomnia também oferece tags de template, que funcionam como pequenas funções dentro dos campos.

Você pode usá-las para:

gerar timestamps;
gerar UUIDs;
extrair valores de respostas anteriores;
reutilizar tokens retornados por uma requisição de login.

Um caso comum é autenticação:

Crie uma requisição de login.
Execute o login e receba uma resposta com token.
Use uma tag de resposta para extrair o valor em $.token.
Injete esse valor no header Authorization de outras requisições.

Conceitualmente, o fluxo fica assim:

POST /login

Resposta:

{
  "token": "abc123"
}

Depois, nas requisições protegidas:

Authorization: Bearer <token extraído da resposta de login>

Com isso, o Insomnia executa a requisição dependente quando necessário, extrai o valor e o reutiliza. A cadeia continua declarativa, sem scripts de acoplamento para manter.

Para estruturar verificações relacionadas, veja também este exemplo de caso de teste de API.

Escrever suítes de teste com asserções

Enviar uma requisição mostra a resposta. Para validar automaticamente se ela está correta, use o recurso de suítes de teste do Insomnia, também exibido como Testes de Unidade em algumas versões.

Para criar uma suíte:

Abra sua coleção.
Vá para a visualização Testes.
Crie uma suíte de testes.
Adicione testes individuais.
Associe cada teste a uma requisição da coleção.

Cada teste é um trecho de JavaScript. O Insomnia usa a biblioteca Chai para asserções e fornece o helper insomnia.send() para executar a requisição.

Exemplo mínimo:

const response = await insomnia.send();

expect(response.status).to.equal(200);

Exemplo validando o corpo da resposta:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body.email).to.equal("daniel.okafor@example.com");
expect(body).to.have.property("id");

Você também pode validar headers:

const response = await insomnia.send();

expect(response.headers["content-type"]).to.include("application/json");

E validar campos aninhados:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(body.address).to.have.property("city");
expect(body.company.name).to.be.a("string");

Clique em Executar Testes para rodar a suíte. O Insomnia mostra quais testes passaram, quais falharam e quanto tempo cada um levou.

Use essas suítes como verificação de regressão: depois de alterar um endpoint, execute os testes e confirme se o comportamento esperado continua válido.

Organizar suítes de teste

À medida que o número de testes cresce, a organização passa a importar.

Um padrão prático é criar uma suíte por recurso:

Usuários
Posts
Autenticação
Pagamentos
Relatórios

Dentro de cada suíte, mantenha cada teste focado em um comportamento.

Exemplo para um recurso de usuários:

Usuários
├── deve retornar usuário existente
├── deve retornar 404 para usuário inexistente
├── deve criar usuário com payload válido
├── deve rejeitar email inválido
└── deve bloquear criação sem autenticação

Evite testes grandes demais. Quando um teste falha, o nome deve deixar claro o que quebrou sem exigir leitura completa do código.

Para aprofundar a estratégia de validação, veja o guia sobre asserções de API e o artigo sobre suítes de teste para automação de testes de API.

Executar testes pela linha de comando com Inso

A interface gráfica é útil durante o desenvolvimento, mas automação exige execução sem UI.

O Insomnia oferece o Inso, um companheiro de linha de comando. Depois de exportar ou sincronizar sua coleção, execute uma suíte pelo terminal:

inso run test "User API tests"

Se algum teste falhar, o Inso retorna um código de saída diferente de zero. Isso é exatamente o que um pipeline de CI precisa para falhar uma build automaticamente.

Um fluxo comum em CI fica assim:

npm install -g inso
inso run test "User API tests"

Em um pipeline, o objetivo é:

baixar ou acessar a coleção;
selecionar o ambiente correto;
executar a suíte;
falhar a build se houver erro.

O Inso também pode lintar especificações de API e gerar relatórios de teste em formatos padrão. Para o padrão geral de integração, veja este guia sobre automação de testes de API em CI/CD.

A mudança para a nuvem na versão 8 e uma alternativa

O Insomnia 8 migrou para um modelo mais orientado à nuvem. Por padrão, ele incentivava usuários a criar uma conta Kong e armazenar projetos na nuvem.

Essa mudança frustrou parte da comunidade, principalmente quem usava versões anteriores de forma totalmente local e offline. Versões posteriores restauraram uma opção mais clara de uso somente local ou Bloco de rascunhos, mas o episódio fez algumas equipes avaliarem alternativas, especialmente em ambientes onde dados de API não podem sair da infraestrutura interna.

Se esse é o seu caso, o Apidog pode ser considerado. Ele reúne design, depuração, mocking, testes e documentação de API, além de importar exportações do Insomnia para evitar começar do zero.

No Apidog, você pode criar asserções visualmente sem escrever JavaScript, mas ainda usar scripts quando necessário. Como especificação da API, dados de teste e servidor mock ficam no mesmo projeto, os testes tendem a permanecer alinhados ao contrato da API.

Você pode baixar o Apidog e importar uma coleção do Insomnia para comparar os fluxos lado a lado. Para uma visão mais ampla, a lista de ferramentas de teste de API online gratuitas reúne outras opções.

O Insomnia continua sendo um cliente forte e focado, especialmente para desenvolvedores individuais e pequenas equipes que valorizam uma interface minimalista e rápida. A melhor escolha depende de como sua equipe trabalha e de quanto do ciclo de vida da API você quer centralizar em uma única ferramenta.

Perguntas frequentes

O Insomnia é gratuito para usar?

Sim. O Insomnia possui um nível gratuito para uso individual, incluindo envio de requisições e execução de suítes de teste localmente.

Planos pagos adicionam recursos de colaboração em equipe e limites maiores de sincronização em nuvem. Versões recentes também permitem trabalhar localmente se você preferir não usar sincronização.

Quais protocolos o Insomnia suporta?

O Insomnia suporta:

HTTP;
REST;
GraphQL;
gRPC;
SOAP;
WebSocket.

A configuração da requisição varia conforme o protocolo, mas a inspeção da resposta e, para requisições baseadas em HTTP, as asserções de testes seguem um fluxo semelhante.

Como escrever asserções no Insomnia?

Use suítes de teste.

O fluxo básico é:

Abra a visualização Testes na coleção.
Crie uma suíte.
Adicione um teste.
Associe o teste a uma requisição.
Use insomnia.send() para executar a chamada.
Valide status, headers ou corpo com expect.

Exemplo:

const response = await insomnia.send();
const body = JSON.parse(response.data);

expect(response.status).to.equal(200);
expect(body).to.have.property("id");

O que mudou no Insomnia 8?

O Insomnia 8 adotou um padrão mais orientado à nuvem, solicitando login em uma conta Kong e incentivando sincronização dos projetos.

Alguns usuários não gostaram do fluxo de conta obrigatório e da mudança em relação ao uso puramente local. Atualizações posteriores adicionaram opções mais claras para uso local, mas a mudança levou algumas equipes a considerar alternativas.

Posso executar testes do Insomnia em um pipeline de CI?

Sim. Use o Inso, a ferramenta de linha de comando do Insomnia.

Depois de exportar ou sincronizar sua coleção, execute:

inso run test "<nome da suíte>"

Se algum teste falhar, o Inso retorna um código de saída diferente de zero. Assim, o CI pode falhar a build automaticamente quando um teste de API quebrar.

Como Mockar uma API para Testes: Guia Prático

Lucas — Fri, 22 May 2026 07:31:59 +0000

Testes que dependem de uma API ativa falham pelos motivos errados: servidor de homologação fora do ar, rate limit de terceiros, dados alterados por outra pessoa ou instabilidade de rede. Para testar o seu código com previsibilidade, substitua o endpoint real por um mock controlado que retorna a resposta esperada sempre que o teste roda.

Experimente o Apidog hoje

Neste guia, você vai montar um fluxo prático para simular uma API em testes: definir um esquema, gerar respostas mock, executar um servidor mock, apontar sua suíte para ele e cobrir cenários de erro. Os exemplos usam uma API simples de pedidos com GET /orders/{id}, mas o mesmo padrão funciona para REST ou GraphQL.

Quando simular a API é a escolha certa

Use mocks quando o objetivo do teste for validar o comportamento do seu código, não a disponibilidade da rede ou do backend.

Bons casos para mock:

Testes de unidade de clients HTTP.
Testes de integração entre módulos internos.
Validação de tratamento de erros.
Testes de timeout, retry e fallback.
Desenvolvimento frontend antes do backend estar pronto.

Exemplo: você quer verificar se seu client interpreta um 200, trata um 404 com uma mensagem clara e tenta novamente após um 503. Nenhum desses casos exige um servidor real.

Mantenha a API real para uma camada menor de testes:

Testes de contrato.
Smoke tests.
Testes ponta a ponta críticos.

A divisão prática é: use mock para velocidade e isolamento; use o serviço real para confirmar que o contrato continua válido. Para aprofundar, veja estes cenários onde a simulação de API compensa e a diferença entre servidor mock e servidor real.

Fluxo de trabalho em 5 passos

Simular uma API para testes normalmente segue este fluxo:

Defina o esquema da API.
Crie respostas simuladas, estáticas ou dinâmicas.
Execute um servidor mock local ou hospedado.
Configure seus testes para usar a URL do mock.
Teste caminhos de erro difíceis de reproduzir em produção.

Vamos aplicar isso ao endpoint:

GET /orders/{id}

Passo 1: Defina o esquema

Um mock só é útil se representar o contrato real da API. Comece por um esquema. Se sua API já tem um documento OpenAPI, use-o. Caso contrário, escreva uma especificação mínima para o endpoint que será testado.

Exemplo simplificado:

paths:
  /orders/{id}:
    get:
      parameters:
        - name: id
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          content:
            application/json:
              schema:
                type: object
                properties:
                  id: { type: string }
                  status: { type: string, enum: [pending, shipped, delivered] }
                  total: { type: number }
                  items: { type: array, items: { type: object } }
        '404':
          description: Order not found

Esse esquema serve para duas coisas:

Define quais campos o mock deve retornar.
Centraliza o contrato entre backend, frontend e testes.

Quando o backend altera o contrato, você atualiza o esquema e regenera os mocks a partir dele. Essa é a base para manter o teste de contrato de API confiável.

Passo 2: Gere respostas simuladas

Você pode trabalhar com dois tipos de resposta mock.

Respostas estáticas

São payloads JSON fixos. O mock sempre retorna o mesmo conteúdo.

Exemplo:

{
  "id": "order_8842",
  "status": "shipped",
  "total": 149.99,
  "items": [
    {
      "sku": "sku_123",
      "quantity": 1
    },
    {
      "sku": "sku_456",
      "quantity": 2
    }
  ]
}

Use respostas estáticas quando o teste precisa de asserções previsíveis:

expect(order.id).toBe('order_8842');
expect(order.status).toBe('shipped');
expect(order.total).toBe(149.99);

Respostas dinâmicas

São geradas a cada requisição. Em vez de fixar "total": 149.99, o mock pode gerar valores realistas com base no esquema:

UUID para id.
Valor do enum para status.
Número plausível para total.
Lista variável para items.

Esse tipo de resposta ajuda a encontrar bugs que um único payload fixo pode esconder, como:

Parser quebrando com strings longas.
Campos opcionais ausentes.
Valores nulos.
Arrays vazios.
Valores numéricos fora do comum.

Na prática, use os dois:

Payloads estáticos para testes com muitas asserções.
Payloads dinâmicos para ampliar cobertura.

Com Apidog, você pode gerar endpoints mock diretamente a partir do esquema. A ferramenta identifica nomes de campos como email, phone ou avatar e preenche valores compatíveis automaticamente.

Ao escrever payloads manualmente, evite dados irreais. Um pedido com "total": 0 e items: [] pode passar no teste, mas não representa bem uma resposta de produção. Prefira dados próximos dos reais: total plausível, múltiplos itens e status válido no enum.

Passo 3: Execute o servidor mock

Depois de definir as respostas, você precisa servi-las em uma URL.

Você tem duas opções principais.

Opção 1: servidor mock local

Um servidor local roda na sua máquina, normalmente em uma porta como localhost:4010.

Use essa opção para:

Testes de unidade.
Testes de integração.
Execuções locais.
Pipelines de CI com ambiente controlado.

Com o Prism, por exemplo, você pode iniciar um mock a partir de um arquivo OpenAPI:

prism mock openapi.yaml
# Mock server listening on http://127.0.0.1:4010

Depois disso, qualquer chamada para:

GET http://127.0.0.1:4010/orders/order_8842

retorna uma resposta compatível com o contrato.

Opção 2: servidor mock na nuvem

Um servidor mock na nuvem fornece uma URL pública.

Use essa opção quando:

Um app mobile precisa acessar o mock.
Um colaborador externo precisa testar a API.
Um runner de CI não consegue acessar sua máquina.
Você quer compartilhar um endpoint mock com outra equipe.

O Apidog fornece uma URL de Cloud Mock por projeto, permitindo que outras pessoas chamem o mesmo endpoint sem depender do seu ambiente local.

Para testes automatizados, prefira o mock local. Ele evita latência externa, reduz flakiness e elimina estado compartilhado entre builds. Use o mock na nuvem para demonstrações, testes entre dispositivos e colaboração.

Passo 4: Aponte seus testes para o mock

Não deixe a URL da API fixa no código. Torne a URL base configurável por variável de ambiente.

Exemplo em JavaScript:

// orderClient.test.js
import { getOrder } from './orderClient.js';

const BASE_URL = process.env.API_BASE_URL || 'http://127.0.0.1:4010';

test('parses a shipped order', async () => {
  const order = await getOrder('order_8842', BASE_URL);

  expect(order.status).toBe('shipped');
  expect(typeof order.total).toBe('number');
});

O client recebe a URL base como argumento:

// orderClient.js
export async function getOrder(id, baseUrl) {
  const response = await fetch(`${baseUrl}/orders/${id}`);

  if (!response.ok) {
    throw new Error(`Failed to fetch order: ${response.status}`);
  }

  return response.json();
}

Assim, o mesmo teste pode rodar contra ambientes diferentes:

# Local usando mock
API_BASE_URL=http://127.0.0.1:4010 npm test

# Job separado usando API real para contrato
API_BASE_URL=https://api.example.com npm test

Esse padrão mantém a simulação fora da lógica da aplicação. Se você executa testes em pipeline, aplique a mesma ideia ao automatizar testes de API em CI/CD.

Passo 5: Teste os caminhos de erro

Esse é o ponto em que mocks mais ajudam. Um servidor real raramente retorna um 500 exatamente quando você precisa testar seu fallback. Um mock retorna sob demanda.

Configure respostas específicas para falhas e valide o comportamento do client.

Cenário	Mock retorna	O que verificar
Registro ausente	`404`	Client lança erro claro de "não encontrado"
Falha no servidor	`500`	Client tenta novamente e depois exibe fallback
Limite de taxa atingido	`429` com `Retry-After`	Client aguarda o tempo correto
Resposta lenta	`200` após 5s de atraso	Client atinge timeout e se recupera
Corpo malformado	`200` com JSON quebrado	Client falha graciosamente, sem travar

Exemplo de teste para 404:

test('throws clear error when order is not found', async () => {
  await expect(getOrder('order_404', BASE_URL)).rejects.toThrow(
    'Failed to fetch order: 404'
  );
});

Exemplo de teste para retry em 500:

test('retries when server returns 500', async () => {
  const order = await getOrderWithRetry('order_retry', BASE_URL, {
    retries: 2
  });

  expect(order.status).toBe('shipped');
});

As regras avançadas de mock do Apidog permitem retornar respostas diferentes com base na requisição. Por exemplo:

GET /orders/order_404 retorna 404.
GET /orders/order_timeout retorna 200 com atraso.
Qualquer outro ID retorna 200.

Isso permite cobrir caminho feliz e falhas usando o mesmo endpoint mock. Combine com assertivas de API para verificar comportamento, não apenas status code.

Organizando mocks em uma suíte de testes crescente

Um endpoint mock é fácil de manter. Cem endpoints espalhados pela suíte viram dívida técnica rapidamente.

Use estas práticas:

Agrupe mocks por serviço

Organize os mocks pelo serviço real que representam, não pelo teste que os consome.

Exemplo:

tests/
  mocks/
    orders/
      order-shipped.json
      order-not-found.json
      order-rate-limited.json
    payments/
      payment-approved.json
      payment-declined.json

Quando a API de pedidos muda, você sabe onde atualizar.

Nomeie fixtures pelo cenário

Prefira nomes que expliquem o comportamento:

order-shipped.json
order-pending.json
order-404.json
order-rate-limited.json

Evite nomes genéricos como:

response1.json
mock-data.json
test.json

Um teste falhando com order-rate-limited é muito mais fácil de diagnosticar.

Versione mocks junto com os testes

Mocks fazem parte da suíte. Eles devem passar por code review como qualquer outro código de teste.

Inclua no PR:

Alteração no esquema.
Alteração no mock.
Alteração nos testes afetados.

Reutilize uma resposta base

Evite criar payloads completamente diferentes para cada teste. A maioria dos cenários muda apenas um campo.

Exemplo:

const baseOrder = {
  id: 'order_8842',
  status: 'shipped',
  total: 149.99,
  items: [
    { sku: 'sku_123', quantity: 1 },
    { sku: 'sku_456', quantity: 2 }
  ]
};

const pendingOrder = {
  ...baseOrder,
  status: 'pending'
};

const deliveredOrder = {
  ...baseOrder,
  status: 'delivered'
};

Isso reduz duplicação e facilita mudanças no contrato. A mesma disciplina usada em uma suíte de testes para automação de API também vale para mocks.

Mantendo o mock honesto

Mocks podem se desviar da API real.

Exemplos comuns:

Backend adiciona um campo obrigatório.
total vira amount.
Um enum recebe novo valor.
Um campo deixa de ser string e vira number.
A estrutura de erro muda.

Se seus testes rodam apenas contra o mock antigo, eles continuam verdes enquanto a produção quebra.

Para evitar isso, adote dois hábitos.

1. Gere o mock a partir do mesmo esquema do backend

Se o backend publica OpenAPI, use esse arquivo como fonte única da verdade.

Fluxo recomendado:

OpenAPI schema
      ↓
Mock server
      ↓
Testes de unidade/integração

Quando o esquema muda, o mock muda junto. Um mock escrito manualmente tende a ficar desatualizado.

2. Rode testes de contrato contra a API real

Mantenha um conjunto pequeno de testes que valida a API real contra o esquema.

Esse job pode rodar:

A cada merge.
Em horário agendado.
Antes de releases.
Contra staging.

O objetivo não é testar toda a aplicação de novo. O objetivo é responder: "a API real ainda corresponde ao contrato usado pelos mocks?"

Se esse teste falhar, atualize o esquema e regenere os mocks antes que a quebra chegue aos usuários.

Também revise mocks durante code review. Se um PR altera uma resposta da API, o mock correspondente deve mudar junto. Trate o mock como parte do contrato, não como um detalhe descartável de teste.

Se você quer um ambiente único para manter esquema, mock server e testes sincronizados, baixe o Apidog. Para comparar alternativas, veja este resumo de ferramentas de simulação de API REST.

Perguntas frequentes

Devo simular a API para todos os testes?

Não. Simule em testes de unidade e integração quando o foco for validar o seu código. Mantenha um conjunto menor de testes de contrato e ponta a ponta contra a API real para confirmar que o mock ainda corresponde à produção.

Qual é a diferença entre resposta mock estática e dinâmica?

Uma resposta estática é um JSON fixo, ideal para asserções previsíveis. Uma resposta dinâmica é gerada por requisição com valores realistas, útil para encontrar bugs que um único payload fixo não cobre. Na prática, use ambas.

Como garanto que meu mock permaneça preciso?

Gere o mock a partir do mesmo esquema usado pelo backend, preferencialmente OpenAPI. Depois, execute testes de contrato contra a API real para confirmar que as respostas em produção ou staging ainda seguem esse esquema.

Um mock pode simular respostas lentas ou com falha?

Sim. Você pode configurar um mock para retornar 500, 429 com cabeçalho Retry-After, JSON inválido ou uma resposta 200 com atraso. Isso permite testar retry, timeout e fallback de forma controlada.

Servidor mock local ou servidor mock na nuvem para testes?

Use servidor mock local para execuções automatizadas. Ele é mais rápido, evita latência de rede e reduz flakiness. Use mock na nuvem quando um dispositivo móvel, runner de CI ou colaborador externo precisar acessar o endpoint sem depender da sua máquina.

Framework de Testes Automatizados com Pytest API: Tutorial Prático

Lucas — Fri, 22 May 2026 07:30:30 +0000

Desenvolvedores Python usam o pytest porque ele reduz boilerplate: um teste é uma função test_*, uma asserção é um assert, e o executor cuida da descoberta e do relatório de falhas. Com requests, você consegue montar um conjunto de testes de API direto no código, sem depender de frameworks pesados.

Experimente o Apidog hoje

Neste guia, você vai criar um conjunto de testes de API com pytest: configurar o projeto, escrever requisições HTTP, reutilizar setup com fixtures, testar múltiplas entradas com parametrize, validar status code, corpo da resposta e Schema JSON. Os exemplos usam uma API fictícia realista para que você possa adaptar a estrutura ao seu projeto.

Configurando o projeto

Crie um ambiente virtual e instale as dependências:

python -m venv .venv
source .venv/bin/activate
pip install pytest requests jsonschema

Use uma estrutura simples para manter os testes organizados:

api-tests/
  conftest.py        # fixtures compartilhadas
  test_users.py      # testes dos endpoints de usuários
  test_orders.py     # testes dos endpoints de pedidos
  pytest.ini         # configuração do pytest

O pytest descobre testes automaticamente quando você segue estas convenções:

arquivos começam com test_ ou terminam com _test.py;
funções começam com test_;
classes começam com Test e não possuem __init__.

Exemplo de configuração inicial em pytest.ini:

[pytest]
addopts = -v
testpaths = .
markers =
    smoke: testes rápidos de verificação principal
    slow: testes mais demorados

Se automação de testes ainda é um tema novo para você, este guia sobre o que é teste automatizado ajuda a contextualizar.

Por que usar pytest para testes de API? Porque requests resolve a camada HTTP e o pytest resolve o restante: descoberta, asserções legíveis, setup e teardown com fixtures, testes orientados por dados com parametrize e relatórios. Assim, os testes podem ficar no mesmo repositório da aplicação e falhar na mesma pull request que introduziu a mudança.

Escrevendo seu primeiro teste de API

Um teste básico envia uma requisição e valida a resposta:

import requests

BASE_URL = "https://api.example.com/v1"

def test_get_user_returns_200():
    response = requests.get(f"{BASE_URL}/users/42")

    assert response.status_code == 200

Agora valide campos do corpo JSON:

def test_get_user_returns_expected_fields():
    response = requests.get(f"{BASE_URL}/users/42")
    body = response.json()

    assert body["id"] == 42
    assert "email" in body
    assert body["status"] == "active"

Execute:

pytest -v

Quando um assert falha, o pytest mostra o valor real e o esperado sem exigir métodos especiais de asserção. Para ampliar a cobertura das verificações, veja este guia sobre asserções de API.

Compartilhando configuração com fixtures

Evite repetir BASE_URL, headers e sessões HTTP em todos os testes. Use fixtures.

Crie um conftest.py:

# conftest.py
import pytest
import requests

BASE_URL = "https://api.example.com/v1"

@pytest.fixture(scope="session")
def api_session():
    session = requests.Session()
    session.headers.update({"Accept": "application/json"})

    yield session

    session.close()

Agora qualquer teste pode receber api_session como argumento:

def test_get_user(api_session):
    response = api_session.get(f"{BASE_URL}/users/42")

    assert response.status_code == 200

Para autenticação, crie outra fixture:

# conftest.py
@pytest.fixture
def auth_token(api_session):
    response = api_session.post(
        f"{BASE_URL}/auth/login",
        json={
            "email": "qa@example.com",
            "password": "test-pass",
        },
    )

    assert response.status_code == 200
    return response.json()["token"]

Use o token no teste:

def test_create_order(api_session, auth_token):
    response = api_session.post(
        f"{BASE_URL}/orders",
        headers={"Authorization": f"Bearer {auth_token}"},
        json={"product_id": 7, "quantity": 2},
    )

    assert response.status_code == 201
    assert response.json()["status"] == "pending"

O scope="session" cria a sessão uma vez por execução. O yield separa setup e teardown: o código antes de yield prepara o recurso; o código depois limpa o recurso quando ele sai do escopo.

Fixtures substituem bem padrões antigos como setup_function e teardown_function, porque são composáveis, explícitas e suportam escopos. A documentação oficial de fixtures do pytest recomenda esse modelo como abordagem padrão.

Executando o mesmo teste com múltiplas entradas

APIs precisam ser testadas com entradas válidas, inválidas e casos de borda. Em vez de criar várias funções quase iguais, use @pytest.mark.parametrize:

import pytest

BASE_URL = "https://api.example.com/v1"

@pytest.mark.parametrize(
    "user_id, expected_status",
    [
        (42, 200),
        (99999, 404),
        (0, 404),
        (-1, 400),
    ],
)
def test_get_user_status_codes(api_session, user_id, expected_status):
    response = api_session.get(f"{BASE_URL}/users/{user_id}")

    assert response.status_code == expected_status

O pytest gera quatro casos independentes. Se um falhar, os outros continuam sendo executados e reportados.

Quando a lista de entradas crescer, carregue os dados de um arquivo CSV ou JSON. Este guia sobre testes de API orientados por dados com CSV e JSON cobre esse padrão. Se você precisa revisar qual status code usar em cada cenário, consulte a referência sobre códigos de status HTTP que APIs REST devem usar.

Fazendo asserções no corpo da resposta

Status code é necessário, mas não suficiente. Uma resposta 200 com JSON incorreto ainda é um bug.

Exemplo:

def test_order_response_body(api_session, auth_token):
    response = api_session.post(
        f"{BASE_URL}/orders",
        headers={"Authorization": f"Bearer {auth_token}"},
        json={"product_id": 7, "quantity": 2},
    )

    body = response.json()

    assert response.status_code == 201
    assert isinstance(body["id"], int)
    assert body["product_id"] == 7
    assert body["quantity"] == 2
    assert body["total"] > 0
    assert body["status"] == "pending"

Você também pode validar tempo de resposta com um limite simples:

assert response.elapsed.total_seconds() < 1.0

Mantenha esse limite generoso para evitar falhas intermitentes causadas por variação normal de rede.

Validando Schema JSON

Para capturar campos ausentes, tipos incorretos ou mudanças estruturais, valide a resposta contra um Schema JSON.

Instale a dependência, se ainda não instalou:

pip install jsonschema

Defina o schema:

from jsonschema import validate

order_schema = {
    "type": "object",
    "required": ["id", "product_id", "quantity", "status", "total"],
    "properties": {
        "id": {"type": "integer"},
        "product_id": {"type": "integer"},
        "quantity": {"type": "integer", "minimum": 1},
        "status": {"type": "string"},
        "total": {"type": "number"},
    },
}

Use no teste:

def test_order_matches_schema(api_session, auth_token):
    response = api_session.post(
        f"{BASE_URL}/orders",
        headers={"Authorization": f"Bearer {auth_token}"},
        json={"product_id": 7, "quantity": 2},
    )

    assert response.status_code == 201
    validate(instance=response.json(), schema=order_schema)

A validação por schema escala melhor do que validar campo por campo em todos os testes. A biblioteca jsonschema é uma opção comum em Python, e a documentação de validação lista as palavras-chave suportadas.

Usando variáveis de ambiente

Não codifique URLs, usuários, senhas ou tokens nos testes. Leia valores sensíveis de variáveis de ambiente.

Exemplo:

import os

BASE_URL = os.environ.get("API_BASE_URL", "https://staging.example.com/v1")

Para credenciais:

import os

@pytest.fixture
def auth_token(api_session):
    response = api_session.post(
        f"{BASE_URL}/auth/login",
        json={
            "email": os.environ["API_USER_EMAIL"],
            "password": os.environ["API_USER_PASSWORD"],
        },
    )

    assert response.status_code == 200
    return response.json()["token"]

Isso permite executar o mesmo conjunto de testes localmente, em staging ou na CI sem editar código.

Executando os testes na CI

O pytest retorna código de saída diferente de zero quando há falha. Isso já é suficiente para quebrar um pipeline.

Com relatório JUnit:

pytest -v --junitxml=results.xml

Exemplo básico com GitHub Actions:

name: API tests

on:
  pull_request:
  push:
    branches:
      - main

jobs:
  pytest-api:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install pytest requests jsonschema

      - name: Run API tests
        env:
          API_BASE_URL: ${{ secrets.API_BASE_URL }}
          API_USER_EMAIL: ${{ secrets.API_USER_EMAIL }}
          API_USER_PASSWORD: ${{ secrets.API_USER_PASSWORD }}
        run: |
          pytest -v --junitxml=results.xml

Para uma configuração mais completa, incluindo secrets e seleção de ambiente, veja o guia sobre testes de API em pipelines de CI/CD.

Executando testes em paralelo

Quando o conjunto crescer, use pytest-xdist para reduzir o tempo de feedback:

pip install pytest-xdist
pytest -n auto

Isso distribui testes entre os núcleos da CPU.

Para funcionar bem, seus testes precisam ser independentes:

não dependa da ordem de execução;
crie dados próprios para cada teste;
limpe recursos criados durante o teste;
evite compartilhar estado mutável entre testes.

Um conjunto que depende de ordem tende a falhar de forma imprevisível quando executado em paralelo.

Mantendo o conjunto de testes sustentável

Um conjunto com 50 testes é fácil de manter. Um com 500 exige disciplina.

Organize por domínio

Prefira arquivos focados:

test_users.py
test_orders.py
test_payments.py

Evite um arquivo gigante com todos os endpoints.

Use markers

Registre markers no pytest.ini:

[pytest]
markers =
    smoke: testes críticos e rápidos
    slow: testes demorados

Use nos testes:

import pytest

@pytest.mark.smoke
def test_get_user(api_session):
    response = api_session.get(f"{BASE_URL}/users/42")

    assert response.status_code == 200

Execute apenas smoke tests:

pytest -m smoke

Execute tudo exceto testes lentos:

pytest -m "not slow"

Centralize configuração e helpers

Mantenha em um único lugar:

BASE_URL;
fixtures;
schemas;
funções auxiliares;
criação e limpeza de dados de teste.

Se você copiar o mesmo código duas vezes, extraia para fixture ou função auxiliar. A mesma disciplina modular descrita neste guia sobre como escrever scripts de teste automatizados se aplica a pytest.

Quando optar por uma plataforma

Um framework pytest funciona bem quando sua equipe escreve Python e quer testes próximos ao código da aplicação. Ele é menos conveniente quando QA, produto ou outras áreas precisam contribuir sem escrever fixtures, helpers e asserções manualmente.

Apidog cobre esse espaço com construção visual de testes, validação de schema contra especificação OpenAPI, execuções orientadas por dados com CSV e JSON, e executor CLI para CI. Muitas equipes usam os dois: pytest para cenários com lógica complexa e Apidog para cobertura ampla, design e simulação das APIs que os testes pytest validam. Você pode baixar o Apidog e comparar as abordagens em um endpoint real.

Perguntas frequentes

Por que usar pytest em vez do unittest embutido do Python para testes de API?

O pytest exige menos boilerplate. Testes são funções simples, asserções usam assert, fixtures lidam com setup de forma flexível e parametrize facilita testes orientados por dados. Ele também consegue executar testes existentes no estilo unittest, o que reduz o risco de migração.

Qual é a diferença entre fixture e parametrize?

Uma fixture fornece um recurso reutilizável, como sessão HTTP ou token de autenticação. parametrize executa o mesmo teste várias vezes com entradas diferentes. Eles se complementam: um teste parametrizado pode receber fixtures normalmente.

Devo fazer asserções sobre tempo de resposta?

Você pode usar response.elapsed.total_seconds() para detectar regressões grandes. Mas pytest é uma ferramenta de teste funcional, não de carga. Para testes reais de performance, use uma ferramenta dedicada e mantenha limites de tempo flexíveis nos testes funcionais.

Como manter testes de API independentes?

Crie dados específicos para cada teste, limpe recursos após a execução e não dependa da ordem dos testes. Testes independentes podem rodar em paralelo e falham de forma isolada, o que facilita a depuração.

O pytest pode validar respostas contra uma especificação OpenAPI?

O pytest sozinho não faz essa validação. Você pode validar JSON com jsonschema ou usar plugins que comparam respostas com um documento OpenAPI. Se validação de schema contra OpenAPI for parte central do fluxo, uma plataforma como Apidog pode reduzir a configuração manual.

Diferenças entre Postman e JMeter: Qual o Melhor?

Lucas — Fri, 22 May 2026 07:28:31 +0000

As pessoas frequentemente colocam Postman e JMeter como concorrentes e perguntam qual deles vence. Essa comparação parte de uma premissa errada: o Postman valida se uma API se comporta corretamente; o JMeter valida se uma API suporta tráfego. Um responde “este endpoint retorna os dados corretos?”; o outro responde “este endpoint continua funcionando quando 2.000 usuários acessam ao mesmo tempo?”.

Experimente o Apidog hoje

Confundir os dois leva a decisões ruins. Uma equipe pode executar uma coleção no Postman, ver tudo verde e assumir que a API está pronta para produção, mesmo sem medir latência sob concorrência. Outra pode rodar um teste de carga no JMeter e esperar que ele detecte um campo JSON malformado. Este guia mostra quando usar cada ferramenta e como encaixá-las em um fluxo de testes prático.

Para que o Postman foi desenvolvido

Postman é um cliente de API e uma plataforma de colaboração. Ele serve para criar requisições, organizá-las em coleções, configurar variáveis de ambiente e escrever scripts de teste em JavaScript executados após cada resposta.

Use o Postman principalmente para testes funcionais:

validar códigos de status;
verificar campos no corpo da resposta;
conferir headers;
validar contratos e esquemas;
automatizar regressões em pipelines.

Um teste típico no Postman fica assim:

pm.test("Status is 200", function () {
    pm.response.to.have.status(200);
});

pm.test("Response has a user id", function () {
    const body = pm.response.json();

    pm.expect(body).to.have.property("id");
    pm.expect(body.id).to.be.a("number");
});

Esse é um teste orientado por asserções. O Postman envia a requisição, avalia a resposta e marca o teste como aprovado ou reprovado.

Você pode executar uma coleção manualmente, com o Collection Runner, ou em CI usando Postman CLI/Newman. O objetivo continua sendo o mesmo: confirmar que a API cumpre o contrato esperado. Para se aprofundar nesse tipo de verificação, veja o guia sobre asserções de API.

Para que o JMeter foi desenvolvido

Apache JMeter é uma ferramenta de teste de carga e desempenho. Em vez de validar apenas uma resposta, ele simula muitos usuários acessando o sistema ao mesmo tempo.

No JMeter, você configura um Thread Group, que representa um conjunto de usuários virtuais. Nele você define:

quantidade de threads/usuários;
tempo de rampa;
número de iterações;
requisições executadas;
timers, listeners e asserções.

Com isso, o JMeter mede:

latência;
vazão;
taxa de erro;
percentis de resposta;
comportamento sob concorrência.

As perguntas que o JMeter responde são quantitativas:

Qual é o p95 com 500 usuários simultâneos?
Em qual volume de requisições a taxa de erro passa de 1%?
O pool de conexões do banco vira gargalo com 300 sessões?
O serviço degrada gradualmente ou falha de uma vez?

Você não obtém essas respostas enviando uma requisição por vez.

O JMeter também vai além de HTTP. Ele suporta JDBC, JMS, FTP, SMTP, TCP e outros protocolos. Isso é útil quando você precisa testar o sistema como um todo, não apenas um endpoint REST. Para entender melhor as métricas, veja a visão geral de testes de desempenho.

Comparação lado a lado

Aspecto	Postman	JMeter
Propósito primário	Testes funcionais e de integração de API	Testes de carga, estresse e desempenho
Questão central	A resposta está correta?	A API aguenta a carga?
Modelo de concorrência	Uma requisição por vez; Runner itera sequencialmente	Muitos usuários simulados em paralelo
Protocolos	HTTP, HTTPS, GraphQL, WebSocket, gRPC	HTTP, JDBC, JMS, FTP, SMTP, TCP e mais
Scripting	Scripts de teste JavaScript	Groovy, BeanShell, samplers Java
Saída	Asserções de aprovação/reprovação por requisição	Percentis de latência, vazão, taxa de erro
Curva de aprendizado	Mais amigável para iniciantes	Mais íngreme, voltado para desempenho
Melhor etapa	Desenvolvimento, integração, regressão	Validação de capacidade e estresse pré-lançamento
Relatórios	Resultados de teste, relatórios via CLI	Dashboards HTML, gráficos agregados

A diferença central é o modelo de concorrência. O Collection Runner do Postman pode repetir requisições, mas não foi feito para simular centenas ou milhares de usuários atingindo o mesmo endpoint ao mesmo tempo. O JMeter existe exatamente para isso.

Quando usar o Postman

Use o Postman quando a pergunta principal for: a API está correta?

Casos práticos:

validar um novo endpoint durante o desenvolvimento;
testar payloads de entrada e saída;
automatizar regressão funcional;
validar contratos de API;
compartilhar coleções entre backend, frontend e QA;
documentar exemplos de requisição e resposta;
testar fluxos simples de autenticação;
rodar checks em cada pull request.

Exemplo de fluxo em CI:

postman collection run ./collections/api.json \
  --environment ./environments/staging.json

Ou usando Newman:

newman run ./collections/api.json \
  -e ./environments/staging.json

Se uma asserção quebrar, a build falha. Isso é regressão funcional, não teste de carga. Esse tipo de verificação deve rodar cedo e com frequência.

O Postman também ajuda no trabalho diário de desenvolvimento. Você pode salvar exemplos de resposta, simular serviços que ainda não existem e manter um workspace compartilhado. Tudo isso acelera o ciclo de construir, testar e revisar APIs.

Para cenários de contrato, veja também testes de contrato de API.

Lendo um resultado do JMeter

Uma execução do JMeter gera números. O ponto é saber quais números importam.

O tempo médio de resposta costuma ser a métrica menos confiável isoladamente. Algumas respostas muito rápidas podem esconder uma cauda de requisições lentas.

Observe principalmente:

p90
p95
p99
vazão
taxa de erro

Exemplo:

Usuários simultâneos: 500
Vazão: 1.200 req/s
p95: 1,8s
p99: 3,4s
Taxa de erro: 0,8%

Um p95 de 1,8s significa que 5% das requisições demoraram mais do que isso. Mesmo que a média pareça aceitável, esses usuários estão tendo uma experiência ruim.

Leia as métricas em conjunto:

latência baixa com erro alto não é sucesso;
vazão alta com p99 ruim indica degradação na cauda;
teste com 50 usuários não prova comportamento com 1.000;
teste curto não revela necessariamente vazamentos ou saturação.

Quando usar o JMeter

Use o JMeter quando a pergunta principal for: a API aguenta o tráfego esperado?

Casos práticos:

validar capacidade antes de um lançamento;
identificar em que ponto a latência degrada;
testar regras de autoescalonamento;
executar soak tests de várias horas;
executar spike tests com picos repentinos;
detectar gargalos de banco, cache, filas ou conexões;
validar SLAs de desempenho.

Exemplo de execução sem GUI:

jmeter -n \
  -t teste-carga.jmx \
  -l resultado.jtl \
  -e \
  -o ./relatorio

Em execuções sérias, prefira o modo sem GUI. A interface gráfica é útil para montar e depurar o plano, mas pode distorcer medições em testes pesados.

Os resultados do JMeter alimentam planejamento de capacidade. Se o p95 fica abaixo de 400 ms com 1.000 usuários, mas sobe para mais de 2s com 1.500, você encontrou um limite operacional importante. Esse número orienta decisões de infraestrutura.

Para um fluxo mais estruturado, veja o tutorial de teste de desempenho de API.

Eles são complementares, não rivais

Uma estratégia madura usa os dois tipos de teste.

Durante o desenvolvimento:

escreva ou atualize o contrato da API;
valide a requisição e a resposta no Postman;
adicione asserções funcionais;
rode a coleção em CI;
bloqueie regressões em cada PR.

Antes do lançamento:

defina cenários de tráfego realistas;
configure usuários virtuais no JMeter;
rode testes de carga, pico ou saturação;
analise p95, p99, vazão e erros;
ajuste infraestrutura ou código conforme os gargalos.

Ignorar qualquer etapa deixa uma lacuna. Uma API pode estar funcionalmente correta e colapsar com 200 usuários. Outra pode ser rápida e retornar dados errados.

Exemplo prático

Uma equipe lança um endpoint de busca.

No Postman, os testes confirmam que ele:

retorna resultados corretos;
pagina corretamente;
rejeita consultas malformadas;
responde com status HTTP esperado.

Tudo passa.

Duas semanas depois, uma campanha de marketing multiplica o tráfego por dez. O endpoint passa a responder em oito segundos porque cada busca aciona uma varredura sem índice no banco.

Os testes funcionais não tinham como detectar isso: eles enviavam poucas requisições contra um sistema ocioso. Um teste de carga com concorrência realista teria exposto o gargalo antes do lançamento.

O inverso também acontece. Uma equipe otimiza a API para 5.000 usuários simultâneos, mas não valida o corpo da resposta. Em produção, o endpoint retorna preços errados por causa de cache desatualizado. O teste de carga mediu velocidade, mas não correção.

Velocidade sem correção é apenas erro rápido.

Onde o Apidog se encaixa

Se manter duas ferramentas separadas parece pesado, o Apidog integra design de API, depuração, testes funcionais automatizados e servidores mock em uma única plataforma.

Com ele, você pode:

projetar o esquema da API;
enviar e depurar requisições;
criar cenários de teste com asserções visuais;
encadear etapas em suítes automatizadas;
usar servidores mock;
executar testes de desempenho com usuários virtuais configuráveis.

A vantagem é manter cobertura funcional e de desempenho no mesmo workspace, reduzindo exportações, sincronizações e troca de contexto entre ferramentas.

Você pode baixar o Apidog e experimentar os recursos de teste gratuitamente. Se quiser comparar alternativas primeiro, veja o resumo das melhores alternativas ao Postman para testes de API.

Perguntas frequentes

O Postman pode fazer teste de carga?

Não de forma significativa. O Collection Runner itera uma coleção sequencialmente, e o Postman adicionou recursos básicos de teste de desempenho no aplicativo desktop, mas isso não substitui uma ferramenta criada para concorrência realista, ramp-up controlado e análise detalhada de percentis. Para carga séria, use JMeter, k6, Gatling ou o módulo de teste de desempenho do Apidog.

O JMeter pode fazer teste funcional de API?

Pode, usando Response Assertions para validar status e conteúdo do corpo. Mas a GUI do JMeter não é ideal para manter suítes funcionais com muitas asserções. A força do JMeter está na concorrência. Normalmente, equipes deixam testes funcionais no Postman ou Apidog e usam JMeter para carga.

O JMeter é mais difícil de aprender que o Postman?

Sim. No Postman, você envia uma requisição em poucos minutos. No JMeter, precisa entender Thread Groups, samplers, timers, listeners, ramp-up e execução sem GUI. A curva é maior, especialmente para quem nunca trabalhou com performance.

Preciso das duas ferramentas?

Você precisa dos dois tipos de teste: funcional e desempenho. Não precisa necessariamente dos dois produtos. Uma plataforma como o Apidog cobre testes funcionais e testes de desempenho em um só lugar, reduzindo a necessidade de manter duas cadeias separadas.

Qual ferramenta detecta uma consulta de banco de dados lenta?

JMeter, sob carga. Uma requisição única no Postman pode parecer rápida em um ambiente ocioso. O problema aparece quando várias requisições competem por conexões, CPU, locks ou I/O. A concorrência revela o gargalo.

Onde k6, Gatling e Locust se encaixam?

Eles são alternativas ao JMeter, não ao Postman. k6, Gatling e Locust são ferramentas de teste de carga e geralmente favorecem testes definidos por código em vez de GUI. Nenhuma delas substitui testes funcionais de API.

Com que frequência devo executar testes de carga?

Com menos frequência do que testes funcionais. Testes funcionais devem rodar em cada commit ou pull request. Testes de carga são mais caros e demorados, então normalmente rodam antes de lançamentos, após mudanças relevantes de infraestrutura ou em uma cadência periódica, como semanalmente.

Como Testar APIs com Postman: Um Guia Prático

Lucas — Fri, 22 May 2026 07:24:43 +0000

Postman é uma das ferramentas mais usadas para enviar requisições HTTP e validar o comportamento de APIs. Ele começou como extensão de navegador e evoluiu para um aplicativo desktop capaz de lidar com requisições simples, coleções, scripts de teste e execuções automatizadas. Se você constrói ou consome APIs, vale dominar o fluxo básico de teste.

Experimente o Apidog hoje

Neste guia, você vai testar uma API no Postman do jeito que faria no dia a dia: enviar requisições, inspecionar respostas, escrever asserções, configurar ambientes para alternar entre staging e produção e executar uma coleção completa com o Collection Runner. Os exemplos usam uma API pública, então você pode acompanhar sem configurar backend próprio.

Configure o Postman e envie sua primeira requisição

Baixe o Postman no site oficial e instale o aplicativo desktop. Você pode usá-lo localmente sem conta, mas o login permite sincronizar coleções entre dispositivos.

Para criar sua primeira requisição:

Abra o Postman.
Clique em New.
Escolha HTTP Request.
Selecione o método GET.
Informe a URL:

GET https://jsonplaceholder.typicode.com/users/1

Clique em Send.

No painel de resposta, verifique:

código de status, como 200 OK;
tempo de resposta;
tamanho da resposta;
corpo retornado;
headers da resposta.

Use as abas Pretty, Raw e Preview para alternar entre JSON formatado, resposta bruta e visualização renderizada.

Enviando uma requisição POST

Para testar envio de dados:

Altere o método para POST.
Abra a aba Body.
Selecione raw.
Escolha JSON no seletor de formato.
Cole um payload:

{
  "name": "Maria Chen",
  "email": "maria.chen@example.com"
}

Quando você escolhe JSON como tipo de corpo, o Postman adiciona automaticamente o header:

Content-Type: application/json

Se a API exigir autenticação, adicione headers na aba Headers, por exemplo:

Authorization: Bearer {{auth_token}}

Se quiser revisar quais códigos HTTP uma API REST deve retornar, veja este guia sobre códigos de status HTTP que APIs REST devem usar.

Organize requisições em coleções

Uma requisição isolada serve para validação rápida. Testes reais geralmente envolvem fluxos:

criar um usuário;
buscar o usuário;
atualizar o usuário;
excluir o usuário.

No Postman, agrupe essas requisições em collections.

Para criar uma coleção:

Clique em Collections na barra lateral.
Clique no ícone +.
Dê um nome descritivo, como Testes de fumaça da API de Usuários.
Salve cada requisição com Ctrl/Cmd + S.
Nomeie cada requisição com clareza, por exemplo:
- Criar usuário
- Buscar usuário por ID
- Atualizar usuário
- Excluir usuário

Você também pode criar pastas dentro da coleção, por exemplo:

Testes de fumaça da API de Usuários
├── Auth
│   └── Login
├── Users
│   ├── Criar usuário
│   ├── Buscar usuário
│   ├── Atualizar usuário
│   └── Excluir usuário

Coleções também são a unidade de compartilhamento. Você pode exportar uma coleção como JSON ou compartilhar um link se estiver usando sincronização em nuvem. Quem importar a coleção terá as mesmas requisições e scripts.

Scripts compartilhados na coleção

O Postman permite adicionar scripts em três níveis:

requisição;
pasta;
coleção.

Um pre-request script no nível da coleção roda antes de cada requisição. Isso é útil para gerar timestamps, atualizar tokens ou preparar variáveis.

Um script de teste no nível da coleção roda após cada requisição. Isso é útil para validações globais, como tempo máximo de resposta.

Exemplo de teste global:

pm.test("Tempo de resposta abaixo de 1000ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(1000);
});

Definir regras comuns uma vez evita duplicação e mantém cada requisição focada no comportamento específico do endpoint.

Escreva testes na aba Tests

Enviar uma requisição mostra o que a API retornou. Escrever um teste valida automaticamente se a resposta está correta.

No Postman, os testes são escritos em JavaScript na área Scripts da requisição. Em versões mais antigas, essa área aparece como aba Tests.

O objeto principal é pm.

O padrão mais usado é:

pm.test("Nome do teste", function () {
    // asserções aqui
});

Se uma expectativa falhar, o teste fica vermelho.

Asserções comuns no Postman

// Verifica o código de status
pm.test("O código de status é 200", function () {
    pm.response.to.have.status(200);
});

// Verifica o tempo de resposta
pm.test("A resposta está abaixo de 500ms", function () {
    pm.expect(pm.response.responseTime).to.be.below(500);
});

// Verifica um campo no corpo JSON
pm.test("O usuário tem o email esperado", function () {
    const body = pm.response.json();
    pm.expect(body.email).to.eql("maria.chen@example.com");
});

// Verifica um header
pm.test("Content-Type é JSON", function () {
    pm.expect(pm.response.headers.get("Content-Type"))
      .to.include("application/json");
});

A sintaxe de asserção vem do Chai. Por isso, pm.expect suporta padrões como:

pm.expect(value).to.eql(expected);
pm.expect(value).to.include("text");
pm.expect(value).to.be.above(10);
pm.expect(value).to.be.below(500);

Depois de clicar em Send, veja os resultados em Test Results. Cada teste aparece como aprovado ou reprovado.

Boas práticas para testes

Use nomes de teste que expliquem o comportamento esperado:

pm.test("Retorna email do usuário solicitado", function () {
    const body = pm.response.json();
    pm.expect(body.email).to.exist;
});

Evite nomes genéricos:

pm.test("Teste 1", function () {
    // ruim para debug
});

Priorize asserções que realmente afetam consumidores da API:

status code;
estrutura do JSON;
campos obrigatórios;
tipos de dados;
headers importantes;
regras de negócio visíveis na resposta.

Evite validar valores instáveis que você não controla, como timestamps gerados pelo servidor, IDs randômicos ou campos que mudam a cada execução. Isso reduz falsos negativos.

O painel de Snippets do Postman ajuda a inserir asserções prontas e aprender a API pm.

Para se aprofundar, veja estes guias sobre asserções de API e como escrevê-las bem e exemplo de caso de teste de API.

Use ambientes e variáveis

Evite hardcoding de URLs como:

https://api.staging.example.com

Se você repetir essa URL em várias requisições, mudar de staging para produção vira retrabalho. Use environments.

Um ambiente é um conjunto nomeado de variáveis.

Criando um ambiente

Abra a área de ambientes no Postman.
Crie um ambiente chamado Staging.
Adicione a variável:

base_url = https://jsonplaceholder.typicode.com

Crie outro ambiente chamado Production com outro valor de base_url.

Agora, use a variável na requisição:

GET {{base_url}}/users/1

Selecione o ambiente ativo no canto superior direito. Todas as requisições que usam {{base_url}} passam a apontar para o ambiente selecionado.

Reutilizando dados entre requisições

Variáveis também ajudam a encadear fluxos. Por exemplo, uma requisição de login pode capturar um token da resposta e salvá-lo no ambiente:

pm.test("Salva o token de autenticação", function () {
    const token = pm.response.json().token;
    pm.environment.set("auth_token", token);
});

Depois, outras requisições podem usar:

Authorization: Bearer {{auth_token}}

Esse padrão é útil para fluxos com estado:

fazer login;
salvar token;
criar recurso;
salvar ID criado;
buscar recurso pelo ID;
excluir recurso.

Exemplo salvando um ID:

pm.test("Salva o ID do usuário criado", function () {
    const body = pm.response.json();
    pm.environment.set("user_id", body.id);
});

Uso posterior:

GET {{base_url}}/users/{{user_id}}

Escopos de variáveis no Postman

O Postman tem diferentes escopos:

Escopo	Uso recomendado
Variável de ambiente	Valores que mudam entre staging, produção e local
Variável de coleção	Valores constantes para uma coleção específica
Variável global	Valores disponíveis em todo o workspace
Variável local	Valores temporários durante uma execução

Escolha o menor escopo possível. Isso reduz colisões e evita que uma variável usada em uma coleção afete outra.

Execute uma coleção inteira com o Collection Runner

Clicar em Send em cada requisição funciona no começo, mas fica lento quando a suíte cresce. O Collection Runner executa uma coleção inteira em sequência e mostra um resumo de aprovação/reprovação.

Para executar uma coleção:

Abra a coleção.
Clique em Run ou no menu de três pontos e escolha Run collection.
Selecione o ambiente.
Defina o número de iterações.
Opcionalmente, anexe um arquivo de dados CSV ou JSON.
Clique em Run.

O Postman executa as requisições de cima para baixo e roda os testes de cada uma.

A tela de resultados mostra:

requisições executadas;
testes aprovados;
testes reprovados;
detalhes de falha;
histórico de execuções.

Esse fluxo funciona bem como verificação de regressão depois de um deploy.

Ordene a coleção como uma jornada

A ordem importa. Se uma requisição depende de dados criados antes, coloque-a depois da requisição que cria esses dados.

Exemplo:

1. Login
2. Criar usuário
3. Buscar usuário criado
4. Atualizar usuário
5. Validar atualização
6. Excluir usuário

Esse formato transforma a coleção em um roteiro executável de uma jornada real.

Testes orientados por dados

Para testar várias entradas sem duplicar requisições, use um arquivo CSV ou JSON no Collection Runner.

Exemplo de CSV:

email,password,expected_status
valid@example.com,correct-password,200
invalid@example.com,wrong-password,401
missing@example.com,,400

Na requisição, use as colunas como variáveis:

{
  "email": "{{email}}",
  "password": "{{password}}"
}

No teste, valide o status esperado:

pm.test("Retorna o status esperado", function () {
    pm.response.to.have.status(Number(pm.iterationData.get("expected_status")));
});

Cada linha vira uma iteração. Isso permite testar múltiplos cenários com a mesma requisição.

O artigo sobre testes de API orientados a dados com CSV e JSON detalha esse padrão.

Para executar a mesma coleção em CI sem interface gráfica, use o Newman, a ferramenta de linha de comando do Postman. Veja também a comparação Newman versus Postman.

Onde o Postman pode ficar pesado

O Postman funciona muito bem para testes exploratórios e suítes pequenas ou médias. Em projetos maiores, dois pontos costumam aparecer.

Primeiro, asserções automatizadas exigem JavaScript. Para desenvolvedores, isso é flexível. Para pessoas de QA ou membros menos técnicos, pode criar uma curva de aprendizado.

Segundo, design da API, testes, mocking e documentação podem ficar separados. Quando isso acontece, a especificação da API e os testes podem se desalinhar.

Apidog é uma plataforma de API que aborda esses pontos. Ele importa coleções do Postman diretamente, então a migração não precisa começar do zero. Asserções podem ser construídas visualmente sem código, com opção de scripts quando necessário. Como design, depuração, mocking, testes e documentação compartilham uma única fonte de verdade, os testes tendem a permanecer alinhados com a especificação da API.

Se você está comparando ferramentas, veja esta lista de alternativas ao Postman para testes de API. Você também pode baixar o Apidog e importar uma coleção existente para comparar o fluxo.

Isso não significa que você precisa abandonar o Postman. Ele continua sendo uma escolha sólida para verificações rápidas e equipes que já o utilizam. O ponto é entender onde cada ferramenta se encaixa melhor.

Perguntas frequentes

Preciso escrever código para testar APIs no Postman?

Para enviar requisições e ler respostas, não. Para asserções automatizadas, sim. A área de testes do Postman executa JavaScript usando o objeto pm. Os padrões são simples e podem ser copiados dos snippets integrados, mas ainda exigem algum código. Se você precisa de um construtor visual de asserções sem código, uma plataforma como o Apidog cobre esse caso.

Qual é a diferença entre uma coleção do Postman e um ambiente?

Uma coleção é um conjunto de requisições agrupadas, geralmente com testes. Um ambiente é um conjunto de variáveis, como base_url, auth_token ou user_id.

Coleções definem o que será enviado. Ambientes definem os valores que mudam entre local, staging e produção.

Como executo testes do Postman automaticamente em CI?

Use o Newman, o executor de linha de comando do Postman.

Exporte sua coleção e seu ambiente, depois execute:

newman run collection.json -e environment.json

Se algum teste falhar, o Newman retorna código diferente de zero. Isso permite quebrar o pipeline de CI quando a suíte falha.

Veja também o guia sobre automação de testes de API em CI/CD.

O Postman pode testar mais do que APIs REST?

Sim. O Postman moderno suporta GraphQL, gRPC, WebSocket e SOAP, além de HTTP/REST. A configuração muda conforme o protocolo, mas o conceito de requisição, resposta e validação continua parecido.

Quantas asserções uma requisição deve ter?

O suficiente para confirmar o comportamento esperado, sem transformar uma mudança pequena em várias falhas redundantes.

Uma base prática:

status code;
tempo de resposta;
formato do corpo;
dois ou três campos importantes para o endpoint.

Mantenha cada bloco pm.test focado em uma expectativa. Assim, quando falhar, a mensagem aponta exatamente o que quebrou.

Teste de Performance: Tipos, Métricas e Como Funciona

Lucas — Fri, 22 May 2026 07:24:29 +0000

Um software que funciona em testes funcionais não necessariamente funciona sob carga. Uma API pode retornar a resposta correta em ambiente local, passar no QA e ainda falhar quando centenas ou milhares de usuários acessam ao mesmo tempo. Teste de desempenho é o processo de medir velocidade, estabilidade e escalabilidade quando o sistema está ocupado.

Experimente o Apidog hoje

Neste guia, você verá o que testar, quais métricas acompanhar, como encaixar testes de desempenho no fluxo de desenvolvimento e como executar esse tipo de verificação em APIs.

O que é teste de desempenho

Teste de desempenho avalia como um sistema se comporta sob uma carga definida.

Ele não responde apenas:

“A funcionalidade funciona?”

Ele responde:

“Com que velocidade ela responde, quantas requisições suporta e como falha quando chega ao limite?”

Exemplo prático:

Um endpoint de login pode estar funcionalmente correto:

POST /login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secret"
}

Resposta esperada:

{
  "token": "jwt-token"
}

Mas sob carga, esse mesmo endpoint pode apresentar:

tempo médio aceitável;
percentil 95 muito alto;
aumento de erros 500;
saturação de CPU;
gargalo no banco de dados.

Nesse caso, o teste funcional passa, mas a experiência real do usuário falha.

O resultado de um teste de desempenho não deve ser tratado como um simples “passou” ou “falhou”. O ideal é produzir um perfil do sistema:

com X usuários simultâneos;
a vazão foi Y requisições por segundo;
o p95 ficou em Z ms;
a taxa de erro foi N%;
o gargalo apareceu em CPU, memória, banco ou dependência externa.

Esse perfil ajuda a definir capacidade, SLAs/SLOs e limites aceitáveis antes do deploy.

Principais tipos de teste de desempenho

Teste de desempenho é uma família de testes. Cada tipo aplica carga de uma forma diferente para responder a uma pergunta específica.

1. Teste de linha de base

O teste de linha de base mede o comportamento do sistema sob carga normal.

Use para responder:

“Como o sistema se comporta hoje em condições esperadas?”

Exemplo:

50 usuários virtuais;
5 minutos de duração;
fluxo principal da aplicação;
ambiente semelhante à produção.

Resultado esperado:

Usuários virtuais: 50
Duração: 5 min
p95: 320 ms
Taxa de erro: 0.1%
Throughput: 180 req/s

Essa linha de base vira a referência para comparar mudanças futuras.

2. Teste de carga

O teste de carga aplica o tráfego de pico esperado.

Use para responder:

“O sistema aguenta o tráfego máximo esperado em um dia normal?”

Exemplo:

pico previsto: 500 usuários simultâneos;
limite de resposta: p95 abaixo de 800 ms;
taxa de erro máxima: 1%.

Critérios de aceitação:

p95 <= 800 ms
error_rate <= 1%
CPU <= 80%
memory sem crescimento contínuo

Se o sistema cumprir esses limites, ele suporta a carga esperada.

3. Teste de estresse

O teste de estresse aumenta a carga além do esperado até o sistema degradar ou falhar.

Use para responder:

“Onde está o ponto de ruptura?”

Exemplo de rampa:

100 usuários -> 300 -> 600 -> 1000 -> 1500

Observe:

quando a latência dispara;
quando os erros começam;
qual recurso satura primeiro;
se o sistema degrada de forma controlada;
se há perda de dados ou falhas em cascata.

Uma degradação aceitável pode ser:

Sistema mais lento, mas ainda respondendo.
Fila aumentando, mas sem perda de mensagens.
Erros controlados com status 429 ou 503.

Uma degradação ruim:

Banco indisponível.
Timeouts em cascata.
Processos reiniciando.
Dados inconsistentes.

4. Teste de pico

O teste de pico aplica uma subida brusca de carga e depois reduz rapidamente.

Use para responder:

“O sistema aguenta rajadas repentinas?”

Cenários comuns:

campanha de marketing;
venda relâmpago;
notícia viral;
início de evento ao vivo;
abertura de inscrições.

Exemplo:

50 usuários por 2 min
1000 usuários por 1 min
50 usuários por 2 min

Esse teste verifica se o sistema escala rápido o suficiente e se volta ao estado normal após o pico.

5. Teste de capacidade

O teste de capacidade identifica o limite máximo sustentável do sistema.

Use para responder:

“Quantos usuários ou requisições por segundo o sistema suporta mantendo os objetivos definidos?”

Exemplo de objetivo:

p95 <= 500 ms
error_rate <= 0.5%
CPU <= 75%

Resultado:

Capacidade máxima sustentável: 720 usuários simultâneos
Throughput máximo estável: 2.100 req/s

Esse número pode ser usado para:

planejamento de infraestrutura;
configuração de autoescalonamento;
definição de limites de tráfego;
estimativas de custo.

6. Teste de imersão

O teste de imersão, também chamado de teste de estabilidade ou resistência, mantém carga moderada por um período longo.

Use para responder:

“O sistema degrada depois de horas em execução?”

Exemplo:

200 usuários virtuais
Duração: 8 horas
Carga constante

Problemas que esse teste encontra:

vazamento de memória;
conexões não fechadas;
crescimento de filas;
exaustão de pool;
lentidão progressiva;
logs crescendo sem controle.

Testes curtos normalmente não revelam esse tipo de falha.

Quais testes executar primeiro

Para a maioria das equipes, uma sequência prática é:

Linha de base para entender o comportamento atual.
Carga para validar o pico esperado.
Imersão para verificar estabilidade.
Estresse para encontrar o limite.
Pico para sistemas com tráfego imprevisível.

Não comece com um teste extremo. Primeiro estabeleça uma referência confiável.

Métricas que definem um bom resultado

Um teste de desempenho só é útil se você coletar as métricas certas.

Tempo de resposta

Tempo de resposta é a duração entre a requisição e a resposta.

Exemplo:

GET /products/123
Tempo de resposta: 240 ms

Não analise apenas a média. Use percentis.

Métricas úteis:

p50: 120 ms
p90: 300 ms
p95: 450 ms
p99: 1200 ms

A média pode esconder problemas. Um sistema com média de 200 ms ainda pode ter p99 de 3 segundos. Usuários reais sentem essa cauda lenta.

Vazão

Vazão é o volume de trabalho concluído por unidade de tempo.

Normalmente aparece como:

requisições por segundo
transações por minuto
mensagens processadas por segundo

Exemplo:

Total de requisições: 120.000
Duração: 10 minutos
Throughput: 200 req/s

Essa métrica mostra a capacidade real do sistema.

Concorrência

Concorrência é o número de usuários, conexões ou operações simultâneas.

Exemplo:

100 usuários simultâneos
500 usuários simultâneos
1000 conexões abertas

A pergunta prática é:

“Em qual nível de concorrência o tempo de resposta ultrapassa o limite aceitável?”

Exemplo:

Até 500 usuários: p95 <= 700 ms
A partir de 800 usuários: p95 > 2 s

Nesse caso, o limite operacional está entre 500 e 800 usuários simultâneos.

Taxa de erro

Taxa de erro é a porcentagem de requisições que falham.

Exemplo:

Total: 100.000 requisições
Falhas: 750
Taxa de erro: 0.75%

Inclua erros como:

5xx;
timeouts;
falhas de conexão;
respostas inválidas;
violações de assertivas.

Um sistema rápido, mas com alta taxa de erro, não tem bom desempenho.

CPU e memória

CPU e memória ajudam a explicar por que a latência ou os erros aumentam.

Exemplos:

CPU em 100% + latência alta = possível gargalo de computação
CPU baixa + latência alta = possível gargalo em banco, lock ou dependência externa
Memória crescendo continuamente = possível vazamento

Também monitore:

uso de disco;
I/O;
conexões de banco;
tamanho de filas;
latência de dependências externas;
garbage collection;
saturação de pool de threads.

Como interpretar um resultado

Evite relatórios vagos como:

O teste passou.

Prefira uma leitura objetiva:

Com 500 usuários simultâneos durante 10 minutos, o sistema manteve 1.200 req/s,
p95 de 620 ms e taxa de erro de 0.2%. A CPU ficou em 72% e a memória permaneceu
estável. O gargalo principal apareceu no banco de dados quando a concorrência
passou de 800 usuários.

Esse formato ajuda o time a tomar decisões:

manter a arquitetura atual;
otimizar consulta;
adicionar índice;
aumentar pool;
configurar cache;
ajustar autoscaling;
limitar tráfego;
adiar release.

Onde o teste de desempenho entra no processo

Teste de desempenho não deve ser uma etapa única no fim do projeto.

Em sistemas com deploy contínuo, o desempenho pode regredir em pequenas mudanças:

uma nova consulta sem índice;
um endpoint chamando serviço externo;
uma serialização pesada;
uma integração adicionada;
uma mudança no payload;
um aumento no número de chamadas ao banco.

O modelo mais eficiente é tratar desempenho como parte da definição de qualidade.

Defina orçamentos de desempenho

Crie limites para caminhos críticos.

Exemplo:

POST /login
p95 <= 500 ms
error_rate <= 0.5%

GET /products
p95 <= 700 ms
error_rate <= 1%

POST /checkout
p95 <= 1000 ms
error_rate <= 0.2%

Esses limites devem ser conhecidos por devs, QA e operações.

Execute testes leves em CI/CD

Para pull requests, use testes curtos e objetivos.

Exemplo:

Duração: 2 a 5 minutos
Carga: baixa ou moderada
Objetivo: detectar regressões óbvias

Se o orçamento for quebrado, o build deve falhar.

Um fluxo possível:

Pull request
  -> testes unitários
  -> testes funcionais
  -> teste de carga leve
  -> validação de orçamento
  -> merge

Você pode integrar esse processo ao seu pipeline de CI/CD.

Agende testes pesados fora do PR

Testes de estresse, pico e imersão são mais longos e caros. Execute em janelas agendadas:

antes de releases importantes;
durante a noite;
semanalmente;
antes de campanhas com tráfego previsto;
após mudanças de infraestrutura.

Por que testar desempenho na camada de API

Para muitos sistemas, a camada de API é o melhor ponto para começar.

APIs são boas candidatas porque:

concentram regras de negócio;
são mais estáveis que interfaces gráficas;
permitem cenários automatizados;
têm respostas fáceis de validar;
produzem métricas consistentes;
são adequadas para execução em pipeline.

Exemplo de cenário de API:

1. Criar usuário
2. Fazer login
3. Buscar produtos
4. Adicionar item ao carrinho
5. Finalizar pedido
6. Validar resposta

Esse tipo de fluxo é mais realista do que testar apenas um endpoint isolado.

O teste de desempenho de API permite medir a experiência real do backend sem depender da UI. Manter esses testes junto com testes funcionais de API ajuda a validar correção e velocidade no mesmo ciclo.

Erros comuns em testes de desempenho

Alguns erros tornam o resultado do teste pouco confiável.

1. Testar em infraestrutura irrealista

Um teste em um laptop ou em homologação subdimensionada não representa produção.

Evite:

Ambiente local
Banco pequeno
Cache diferente
Poucos recursos
Configuração fora do padrão de produção

Prefira:

Ambiente semelhante à produção
Dados representativos
Mesmas configurações críticas
Monitoramento habilitado
Dependências próximas do cenário real

Se não for possível replicar produção, documente as diferenças.

2. Ignorar aquecimento

Muitos sistemas são mais lentos no início:

caches ainda vazios;
pools de conexão abrindo;
JIT aquecendo;
índices e páginas sendo carregados;
autoscaling ainda não ativado.

Não misture aquecimento com estado estável.

Exemplo de abordagem:

Primeiros 2 minutos: aquecimento
Próximos 10 minutos: medição oficial

3. Usar média em vez de percentis

A média esconde a cauda lenta.

Compare:

Média: 200 ms
p95: 900 ms
p99: 3000 ms

Nesse exemplo, muitos usuários ainda terão uma experiência ruim.

Sempre reporte pelo menos:

p50
p90
p95
p99

4. Usar dados irreais

Testar sempre com o mesmo usuário, produto ou payload pode mascarar gargalos.

Evite:

{
  "userId": 1,
  "productId": 1
}

em todas as requisições.

Prefira variar dados:

[
  { "userId": 101, "productId": 9001 },
  { "userId": 235, "productId": 8420 },
  { "userId": 879, "productId": 1203 }
]

O tráfego real atinge diferentes linhas, índices, caches e partições.

5. Testar apenas um endpoint isolado

Usuários não fazem apenas uma chamada. Eles percorrem fluxos.

Em vez de testar somente:

GET /products

teste um cenário:

POST /login
GET /products
GET /products/{id}
POST /cart
POST /checkout

Isso revela contenção em recursos compartilhados, como banco de dados, cache e pools de conexão.

6. Tratar teste de desempenho como evento único

Um teste feito antes do lançamento fica obsoleto rapidamente.

O desempenho muda quando o código muda. Por isso, os testes devem ser repetíveis e automatizados.

Um processo mínimo:

A cada PR: teste leve
Antes do release: teste de carga completo
Semanalmente: teste de imersão
Antes de campanhas: teste de pico

Executando testes de desempenho com Apidog

O Apidog permite trabalhar com design de API, testes funcionais e testes de carga no mesmo espaço de trabalho. Isso evita manter uma definição separada da API apenas para desempenho.

Um fluxo prático:

Escolha um endpoint ou cenário de teste.
Valide primeiro se o cenário passa funcionalmente.
Configure usuários virtuais.
Defina a duração do teste.
Execute com aumento gradual de carga.
Acompanhe percentis, vazão e taxa de erro.
Identifique em qual nível de concorrência o desempenho muda.
Compare o resultado com seu orçamento.

Exemplo de objetivo para um cenário:

Cenário: login + busca + checkout
Usuários virtuais: 300
Duração: 10 minutos
p95 máximo: 1000 ms
Taxa de erro máxima: 0.5%

Como o mesmo cenário pode ser usado para execuções funcionais e de desempenho, você mantém um único artefato de teste. Para cargas maiores que uma única máquina, o cenário pode ser exportado para o JMeter mantendo a mesma definição.

Você pode baixar o Apidog e começar por um endpoint crítico que já existe no seu sistema.

Perguntas frequentes

Qual é a diferença entre teste de desempenho e teste funcional?

Teste funcional verifica se o software retorna o resultado correto. Teste de desempenho verifica a rapidez, estabilidade e confiabilidade desse resultado sob carga.

Os dois são necessários. Um não substitui o outro.

Que tipo de teste de desempenho devo executar primeiro?

Comece com linha de base e depois teste de carga.

A linha de base mostra o comportamento atual em condições normais. O teste de carga valida se o sistema aguenta o pico esperado. Depois, adicione testes de estresse, pico e imersão conforme a criticidade do sistema.

Por que usar percentis em vez de tempo médio de resposta?

Porque a média esconde a cauda lenta.

Percentis como p95 e p99 mostram o que usuários menos favorecidos experimentam. Essa é a parte que normalmente gera reclamações, abandono e incidentes.

Teste de desempenho pode ser automatizado?

Sim.

Uma boa prática é executar testes leves em CI para detectar regressões. Testes mais pesados, como estresse e imersão, costumam ser agendados porque consomem mais tempo e infraestrutura.

Quando o teste de desempenho deve começar?

O mais cedo possível.

Mesmo sem infraestrutura final, você já pode:

definir orçamentos;
escrever cenários;
identificar caminhos críticos;
preparar dados de teste;
automatizar validações básicas.

Assim que um endpoint estiver funcional, execute um teste de carga simples para encontrar problemas enquanto ainda são baratos de corrigir.

Quem é responsável pelo teste de desempenho?

Em equipes modernas, a responsabilidade é compartilhada.

Desenvolvedores validam impacto de suas mudanças.
QA mantém cenários e critérios.
SRE ou operações fornece infraestrutura, observabilidade e métricas.
Produto ajuda a definir fluxos críticos e expectativas de uso.

Quando o teste de desempenho fica restrito a um único especialista no fim do ciclo, os problemas tendem a chegar à produção.

Por quanto tempo um teste de desempenho deve rodar?

Depende do objetivo.

Para teste de carga, execute tempo suficiente para passar o aquecimento e atingir estado estável, normalmente alguns minutos.

Para teste de imersão, rode por horas ou dias, porque o objetivo é encontrar degradação lenta, vazamento de memória e exaustão de recursos.

Cenário de Teste vs Caso de Teste: Principais Diferenças Explicadas

Lucas — Fri, 22 May 2026 07:23:55 +0000

“Cenário de teste” e “caso de teste” costumam aparecer como sinônimos, mas não são. Confundir os dois deixa o plano de testes vago demais para executar ou detalhado demais para revisar. O cenário define o que testar; o caso define como testar. Quando você separa essas camadas, sua cobertura fica mais auditável, executável e fácil de manter.

Experimente o Apidog hoje

Este guia mostra a diferença prática entre cenário e caso de teste, como estruturar os dois em testes de API e como aplicar esse fluxo usando Apidog.

O que é um cenário de teste?

Um cenário de teste é uma declaração de alto nível sobre um comportamento que precisa ser validado. Ele descreve a intenção do teste, sem entrar em endpoint, payload, headers ou valores esperados.

Pense no cenário como o item de cobertura no plano de teste.

Para um checkout de e-commerce, bons cenários seriam:

Verificar checkout para um usuário registrado com cartão salvo
Verificar checkout para um usuário convidado
Verificar checkout quando um item fica sem estoque durante a compra
Verificar checkout quando o pagamento é recusado

Cada cenário responde:

Que comportamento do produto ou da API precisa funcionar?

Ele não responde:

Qual endpoint chamar?
Qual payload enviar?
Qual status HTTP esperar?
Qual campo validar na resposta?

Exemplo de cenário:

Cenário: Usuário convidado consegue finalizar uma compra.

Isso é legível para produto, QA e engenharia. Também serve como mapa de cobertura: se o cenário não existe, nenhum caso de teste detalhado vai cobrir aquela lacuna.

O que é um caso de teste?

Um caso de teste é a verificação concreta e executável dentro de um cenário. Ele define pré-condições, entrada, ação e resultado esperado com precisão suficiente para que qualquer pessoa ou ferramenta obtenha o mesmo veredito.

Para o cenário:

Cenário: Verificar checkout para um usuário convidado.

Você pode criar casos como:

POST /orders com payload válido de convidado retorna 201 e um order_id
POST /orders sem endereço de entrega retorna 400 e validation_error
POST /orders com SKU fora de estoque retorna 409 e error: out_of_stock

Um caso de teste precisa ser específico. Por exemplo:

POST /orders
Content-Type: application/json

{
  "customer": {
    "type": "guest",
    "email": "guest@example.com"
  },
  "shipping_address": {
    "street": "Rua A",
    "city": "São Paulo",
    "zip": "01000-000"
  },
  "items": [
    {
      "sku": "SKU-123",
      "quantity": 1
    }
  ],
  "payment_method": "credit_card"
}

Resultado esperado:

Status: 201
Response body:
- order_id existe
- status = "created"
- total > 0

A diferença é simples:

"O checkout funciona"                     -> cenário vago
"POST /orders com convidado válido..."    -> caso de teste executável

Se você precisa de um modelo completo, veja como escrever casos de teste de API. Para entender onde entram scripts automatizados, veja caso de teste vs script de teste.

As principais diferenças

Dimensão	Cenário de teste	Caso de teste
Nível	Alto nível: o que testar	Baixo nível: como testar
Detalhe	Breve, normalmente uma linha	Passo a passo, com dados
Foco	Objetivo de negócio ou funcional	Execução técnica
Entradas	Não especificadas	Payloads, headers e parâmetros exatos
Resultado esperado	Implícito	Declarado com precisão
Público	Produto, QA e engenharia	QA, desenvolvedores e automação
Quantidade	Poucos por funcionalidade	Muitos por cenário
Momento de criação	Planejamento do teste	Depois que os cenários são definidos

A relação é hierárquica:

Funcionalidade
└── Cenário de teste
    ├── Caso de teste 1
    ├── Caso de teste 2
    └── Caso de teste 3

O cenário controla a amplitude da cobertura.

Os casos controlam a profundidade da validação.

Um erro comum é criar dezenas de casos detalhados sem mapear os cenários. O resultado é uma lista plana de testes, sem resposta clara para perguntas como:

A funcionalidade de checkout de convidado está realmente coberta?

Outro ponto importante:

Um cenário pode estar coberto ou não coberto
Um caso de teste pode estar aprovado ou reprovado

Você precisa dos dois níveis para gerenciar qualidade.

Como cenários e casos funcionam juntos

Um fluxo prático vai do geral para o específico.

1. Identifique cenários a partir dos requisitos

Leia a documentação da API, histórias de usuário ou especificação funcional. Liste os comportamentos que precisam ser validados, incluindo caminhos de erro.

Exemplo:

Funcionalidade: Notas

Cenários:
- Usuário cria uma nota
- Usuário lista suas notas
- Usuário edita uma nota existente
- Usuário exclui uma nota
- Usuário não autenticado não acessa notas

Inclua também unhappy paths:

- Criar nota sem título
- Criar nota com payload inválido
- Criar nota com token expirado

2. Defina o objetivo de cada cenário

Escreva o que significa o cenário estar correto.

Exemplo:

Cenário: Usuário cria uma nota

Objetivo:
Um usuário autenticado deve conseguir criar uma nota válida.
Payloads inválidos devem ser rejeitados com mensagens claras.
Usuários não autenticados não devem criar notas.

Isso evita interpretações diferentes entre QA, backend e produto.

3. Escreva casos de teste para cada cenário

Expanda o cenário em casos concretos.

Para cada caso, defina:

Pré-condição
Endpoint
Método HTTP
Headers
Payload
Resultado esperado
Asserções

Modelo simples:

Caso: Criar nota com dados válidos

Pré-condição:
- Usuário autenticado
- Token válido disponível

Requisição:
POST /notes

Resultado esperado:
- Status 201
- Campo id existe
- title corresponde ao enviado
- created_at existe

4. Revise a completude

Antes de executar, revise a cobertura.

Perguntas úteis:

Cada cenário tem pelo menos um happy path?
Cada cenário tem casos negativos?
Todos os status HTTP documentados aparecem em algum caso?
Campos obrigatórios têm validação?
Permissões e autenticação foram cobertas?
Há casos para limites de tamanho, formato e valores inválidos?

Lacunas encontradas nessa etapa são baratas. Lacunas encontradas em produção não são.

5. Execute e rastreie resultados

Execute os casos e registre:

Aprovado/reprovado por caso
Cenários afetados
Erros por endpoint
Status HTTP inesperados
Diferenças no contrato da API

O relatório ideal mostra os dois níveis:

Cenário: Usuário cria uma nota
Status: Em risco

Casos:
✅ Criar nota válida
❌ Criar nota sem título
✅ Criar nota sem autenticação

Assim, engenharia sabe qual caso falhou, e produto entende qual comportamento está em risco.

Para equipes que usam BDD, cenários também podem ser escritos em Given-When-Then. Veja o guia Gherkin para teste de API BDD.

Exemplo prático: do cenário aos casos

Considere uma API de notas.

O comportamento principal:

Cenário: Um usuário pode criar uma nota.

Esse cenário é intencionalmente simples. Ele pertence ao plano de teste e deve ser compreensível por qualquer pessoa.

Agora transforme esse cenário em casos executáveis.

Caso 1: criar nota com sucesso

Requisição:

POST /notes
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Compras",
  "body": "leite, ovos"
}

Resultado esperado:

Status: 201
Response:
- id não vazio
- title = "Compras"
- body = "leite, ovos"
- created_at existe
Tempo de resposta: < 600 ms

Caso 2: criar nota sem campo obrigatório

Requisição:

POST /notes
Authorization: Bearer <token>
Content-Type: application/json

{
  "body": "leite, ovos"
}

Resultado esperado:

Status: 400
Response:
- error = "validation_error"
- details contém "title"

Caso 3: criar nota sem autenticação

Requisição:

POST /notes
Content-Type: application/json

{
  "title": "Compras",
  "body": "leite, ovos"
}

Resultado esperado:

Status: 401
Response:
- nenhum id é retornado

Caso 4: criar nota com payload muito grande

Requisição:

POST /notes
Authorization: Bearer <token>
Content-Type: application/json

{
  "title": "Arquivo grande",
  "body": "<texto com 2 MB>"
}

Resultado esperado:

Status: 413
Response:
- mensagem de erro clara

Resultado da estrutura:

Cenário: Um usuário pode criar uma nota
├── Caso 1: payload válido
├── Caso 2: campo obrigatório ausente
├── Caso 3: sem autenticação
└── Caso 4: payload muito grande

Um cenário, quatro casos. O cenário define o que validar. Os casos definem como validar.

Se depois você adicionar:

Cenário: Um usuário pode anexar um arquivo a uma nota.

Esse é um novo cenário, com seus próprios casos. O plano cresce de forma estruturada, em vez de virar uma pilha solta de verificações.

Construindo cenários e casos no Apidog

Apidog permite modelar essa hierarquia diretamente no fluxo de teste de API.

Um cenário de teste no Apidog pode ser montado como uma sequência ordenada de requisições. Cada etapa representa uma chamada de API com suas próprias validações.

Exemplo de fluxo:

1. POST /auth/login
   - Extrair token da resposta

2. POST /notes
   - Usar token no header Authorization
   - Validar status 201
   - Validar campo id

3. GET /notes/{id}
   - Confirmar que a nota criada pode ser consultada

Esse encadeamento é útil quando uma requisição depende do resultado da anterior, como:

Login retorna token
Criação retorna id
Consulta usa o id
Exclusão usa o mesmo id

Cada bloco de requisição com asserções funciona como um caso de teste. Você pode validar:

Código de status
Campos do corpo da resposta
Schema
Tempo de resposta
Valores esperados
Dados extraídos de respostas anteriores

Também é possível usar teste orientado a dados para executar o mesmo caso com múltiplas entradas de CSV ou JSON. Isso ajuda a cobrir variações inválidas sem duplicar manualmente cada teste.

Exemplo de massa de dados:

title,body,expected_status
Compras,"leite, ovos",201
,"sem título",400
Titulo,"",201

Depois, os cenários podem ser agrupados em conjuntos de teste (test suites) para execuções repetíveis.

Você pode executar esses conjuntos:

Localmente
Em uma programação
Dentro de CI
Como parte de um fluxo de validação antes do deploy

O valor está no relatório em dois níveis:

Caso falhou:
POST /notes sem title retornou 500 em vez de 400

Cenário afetado:
Usuário pode criar uma nota

Engenharia vê o detalhe técnico. Liderança vê o impacto na funcionalidade.

Para começar, baixe o Apidog e crie seu primeiro cenário com múltiplos casos.

Por que você precisa de ambos

Pular uma das camadas cria problemas diferentes.

Se você escreve apenas casos de teste:

❌ Lista longa de requisições
❌ Sem mapa de cobertura
❌ Difícil responder se uma funcionalidade está completa

Se você escreve apenas cenários:

❌ Plano legível, mas não executável
❌ Resultados inconsistentes entre testadores
❌ Automação difícil ou impossível

Use os dois:

Cenários = cobertura e intenção
Casos = execução e evidência

Eles também atendem públicos diferentes:

Produto lê cenários para validar se as funcionalidades certas estão cobertas
QA usa cenários para organizar o plano
Desenvolvedores usam casos para entender contratos e falhas
Automação executa casos
Liderança acompanha o status por cenário

A regra prática:

Mantenha cenários estáveis.
Atualize casos sempre que o contrato da API mudar.

Cenários mudam quando a intenção da funcionalidade muda. Casos mudam quando endpoints, payloads, autenticação, schemas ou regras de validação mudam.

Perguntas frequentes

Um cenário de teste é o mesmo que um conjunto de testes?

Não. Um cenário descreve um comportamento a ser validado. Um conjunto de testes é uma coleção de testes executáveis agrupados para uma execução.

Um conjunto pode conter casos de vários cenários.

Veja também: conjunto de testes vs caso de teste.

Quantos casos de teste um cenário deve ter?

O suficiente para cobrir:

Happy path
Validações obrigatórias
Erros esperados
Permissões
Limites relevantes
Códigos de status documentados

Um cenário simples pode ter três ou quatro casos. Um cenário crítico ou complexo pode exigir muito mais.

Quem escreve cenários e quem escreve casos?

Cenários geralmente são definidos em conjunto por produto, QA e engenharia, porque representam a intenção do comportamento.

Casos normalmente são escritos por QA ou desenvolvedores, porque exigem detalhes técnicos da API.

Para padronizar a escrita, veja o formato de especificação de caso de teste.

Preciso de cenários se meus testes são automatizados?

Sim. A automação executa casos, mas os cenários dizem se os casos corretos existem.

Automação sem mapa de cobertura apenas executa lacunas mais rápido.

Tipos de Framework de Teste de Automação: Qual Escolher para sua Equipe

Lucas — Fri, 22 May 2026 07:23:41 +0000

Equipes costumam dizer que “usam automação” como se isso definisse como os testes são organizados. Não define. Duas suítes podem ser automatizadas e, ainda assim, ter estruturas completamente diferentes, com custos de manutenção muito diferentes. Essa estrutura é o framework: ele determina como os testes crescem, quem consegue contribuir e quanto uma mudança pequena na UI ou na API afeta o restante da suíte.

Experimente o Apidog hoje

Este guia apresenta seis tipos clássicos de frameworks de automação de testes: linear, modular, baseado em dados (data-driven), baseado em palavras-chave (keyword-driven), híbrido e baseado em comportamento (behavior-driven, ou BDD). A ideia é ajudar você a escolher uma estrutura de acordo com sua equipe, seu produto e seu custo de manutenção — não apenas herdar o que alguém configurou antes.

O que é um framework de automação de testes

Um framework de automação de testes é o conjunto de convenções, componentes reutilizáveis e decisões arquiteturais que define como os testes são escritos, organizados, executados e mantidos.

Ele responde perguntas como:

Onde ficam os dados de teste?
Como reutilizar passos comuns, como login ou criação de usuário?
Como separar lógica de teste de dados de entrada?
Quem pode criar testes: apenas desenvolvedores ou também QA e produto?
Como os resultados são reportados?
Como evitar que uma mudança pequena quebre centenas de testes?

Se você está começando, esta visão geral sobre o que é teste automatizado ajuda a contextualizar os conceitos antes de comparar os tipos de framework.

A manutenção é o ponto central. Criar os primeiros testes automatizados costuma ser simples. Manter centenas ou milhares de testes enquanto a aplicação muda toda semana é o desafio real.

Exemplo prático: uma tela de login muda o rótulo de Email para E-mail corporativo.

Em uma suíte bem modularizada, você atualiza um seletor ou uma função.
Em uma suíte linear, talvez precise editar dezenas ou centenas de scripts repetidos.

A aplicação é a mesma. O custo muda por causa da estrutura do framework.

Os seis tipos de framework

1. Linear: gravação e reprodução

Um framework linear registra ações e as reproduz como um script. Cada teste é uma sequência plana de passos, sem funções compartilhadas e sem separação entre lógica e dados.

Exemplo conceitual:

test('login válido', async ({ page }) => {
  await page.goto('/login')
  await page.fill('#email', 'user@example.com')
  await page.fill('#password', '123456')
  await page.click('button[type="submit"]')
  await expect(page).toHaveURL('/dashboard')
})

Esse formato funciona bem para:

protótipos;
demonstrações rápidas;
smoke checks pontuais;
testes descartáveis.

O problema aparece quando a suíte cresce. Se o login está copiado em cinquenta testes, qualquer mudança no formulário exige cinquenta edições.

Use linear apenas quando o teste for realmente temporário. Se a suíte vai durar mais do que algumas semanas, extraia funções reutilizáveis cedo.

2. Modular

Um framework modular divide a aplicação em módulos reutilizáveis. Em vez de repetir os passos em cada teste, você cria funções ou objetos que representam partes estáveis do sistema.

Exemplo:

async function login(page, email, password) {
  await page.goto('/login')
  await page.fill('#email', email)
  await page.fill('#password', password)
  await page.click('button[type="submit"]')
}

test('usuário acessa o dashboard após login', async ({ page }) => {
  await login(page, 'user@example.com', '123456')
  await expect(page).toHaveURL('/dashboard')
})

Agora, se a tela de login mudar, você ajusta a função login() uma vez.

Esse tipo é indicado quando:

a suíte será mantida por mais tempo;
há vários fluxos compartilhando os mesmos passos;
desenvolvedores ou QAs técnicos escrevem testes;
você quer reduzir duplicação.

A desvantagem é o investimento inicial. Alguém precisa definir os módulos, as funções reutilizáveis e os limites de abstração. Para a maioria das equipes de engenharia, porém, essa é a base mais segura. Ela combina bem com as práticas descritas em como escrever scripts de teste automatizados.

3. Baseado em dados (data-driven)

Um framework data-driven separa a lógica do teste dos dados de entrada. O mesmo teste roda várias vezes usando dados vindos de CSV, JSON, planilhas ou banco de dados.

Exemplo com uma lista de credenciais:

const casos = [
  { email: 'user@example.com', password: '123456', esperado: 'sucesso' },
  { email: 'user@example.com', password: 'errada', esperado: 'erro' },
  { email: '', password: '123456', esperado: 'erro' },
]

for (const caso of casos) {
  test(`login com ${caso.email || 'email vazio'} deve retornar ${caso.esperado}`, async ({ page }) => {
    await login(page, caso.email, caso.password)

    if (caso.esperado === 'sucesso') {
      await expect(page).toHaveURL('/dashboard')
    } else {
      await expect(page.locator('.error')).toBeVisible()
    }
  })
}

Também é comum carregar os dados de um arquivo JSON:

[
  {
    "email": "user@example.com",
    "password": "123456",
    "esperado": "sucesso"
  },
  {
    "email": "user@example.com",
    "password": "errada",
    "esperado": "erro"
  }
]

Esse modelo é útil quando você precisa testar muitas combinações de entrada contra o mesmo fluxo:

logins válidos e inválidos;
limites numéricos;
variações de localidade;
diferentes perfis de usuário;
payloads de API.

Para APIs, uma abordagem de teste baseada em dados com CSV e JSON permite transformar uma requisição em muitos casos de teste.

A limitação: o comportamento do teste permanece fixo. Você aumenta a cobertura variando os dados, não criando fluxos completamente diferentes.

4. Baseado em palavras-chave (keyword-driven)

Um framework keyword-driven representa ações como palavras-chave: Login, SearchProduct, AddToCart, VerifyTotal.

Os testes podem ser descritos em uma tabela:

Ação	Argumento 1	Argumento 2
Login	user@example.com	123456
SearchProduct	notebook
AddToCart	notebook
VerifyTotal	3500.00

Por trás da tabela, cada palavra-chave tem uma implementação:

const keywords = {
  Login: async (page, email, password) => {
    await login(page, email, password)
  },

  SearchProduct: async (page, term) => {
    await page.fill('#search', term)
    await page.press('#search', 'Enter')
  },

  VerifyTotal: async (page, expectedTotal) => {
    await expect(page.locator('#total')).toHaveText(expectedTotal)
  }
}

Esse tipo é útil quando:

analistas de QA ou pessoas de negócio precisam montar testes;
a equipe técnica quer controlar a implementação;
os fluxos são compostos por ações de alto nível;
a legibilidade para não-programadores é importante.

O custo está na biblioteca de palavras-chave. Se ela for mal desenhada, vira outro sistema para manter. Palavras-chave muito genéricas perdem clareza; palavras-chave muito específicas geram duplicação.

5. Híbrido

Um framework híbrido combina dois ou mais modelos. Na prática, muitas suítes maduras acabam assim:

modular para reutilizar fluxos;
data-driven para variar entradas;
keyword-driven para permitir composição por não-programadores;
BDD para cenários que exigem alinhamento com produto.

Exemplo de combinação modular + data-driven:

import casosLogin from './casos-login.json'

for (const caso of casosLogin) {
  test(`login: ${caso.nome}`, async ({ page }) => {
    await login(page, caso.email, caso.password)
    await validarResultadoLogin(page, caso.esperado)
  })
}

O híbrido funciona bem quando a mistura é intencional. O risco é acumular camadas sem padrão claro.

Evite isso documentando decisões como:

quando usar teste modular puro;
quando usar dados externos;
quando criar uma nova palavra-chave;
quando escrever cenários BDD;
onde ficam fixtures, helpers e dados.

Um framework híbrido deve reduzir complexidade operacional, não apenas adicionar abstrações.

6. Baseado em comportamento: BDD

Um framework BDD expressa testes em linguagem próxima da natural usando o padrão Dado-Quando-Então (Given-When-Then), geralmente em Gherkin.

Exemplo:

Funcionalidade: Login

  Cenário: Usuário acessa o painel com credenciais válidas
    Dado que existe um usuário registrado
    Quando ele envia credenciais válidas
    Então ele deve acessar o painel

Cada passo precisa de uma implementação:

Given('que existe um usuário registrado', async function () {
  // criar ou buscar usuário de teste
})

When('ele envia credenciais válidas', async function () {
  // executar login
})

Then('ele deve acessar o painel', async function () {
  // validar resultado
})

O principal benefício do BDD é criar entendimento compartilhado entre produto, QA e engenharia. A especificação vira algo que todos conseguem ler.

Use BDD quando:

requisitos são frequentemente mal interpretados;
produto ou negócio realmente revisam os cenários;
os testes também servem como documentação executável;
a clareza do comportamento importa mais do que a velocidade de escrita.

Evite BDD quando apenas desenvolvedores leem os testes. Nesse caso, você paga o custo de manter Gherkin e definições de passo sem capturar o principal benefício. Para APIs, este guia Gherkin para testes de API BDD mostra o padrão aplicado na prática.

Comparando os tipos de framework

Tipo de framework	Reutilização	Não-programadores podem criar	Custo de configuração	Escalabilidade
Linear	Nenhuma	Sim, via gravação	Muito baixo	Ruim
Modular	Alta	Não	Médio	Boa
Baseado em dados	Média	Parcialmente	Médio	Boa para entradas
Baseado em palavras-chave	Alta	Sim	Alto	Boa
Híbrido	Alta	Às vezes	Alto	Muito boa
BDD	Alta	Sim, para ler e criar	Alto	Boa

O padrão é simples: quanto menor o custo inicial, pior tende a ser a escalabilidade. E quanto mais você quer incluir não-programadores na criação dos testes, mais investimento técnico será necessário na infraestrutura.

Erros comuns ao escolher um framework

1. Abstrair cedo demais

Criar um framework keyword-driven ou híbrido para uma suíte com quinze testes pode ser exagero. A camada de abstração pode custar mais do que os testes que ela deveria simplificar.

Sinal de alerta:

muitos helpers criados antes de haver duplicação real;
palavras-chave que são usadas uma única vez;
documentação do framework maior que a suíte.

Regra prática: deixe a duplicação real justificar a próxima camada de abstração.

2. Permanecer linear por tempo demais

O erro oposto também é comum. Uma suíte começa com vinte scripts gravados e continua linear quando chega a quatrocentos testes.

Sinal de alerta:

uma mudança de produto exige editar muitos arquivos;
os mesmos passos aparecem copiados em vários testes;
correções simples levam horas;
ninguém quer mexer nos testes antigos.

Quando isso acontecer, extraia funções reutilizáveis e migre para uma estrutura modular antes que a manutenção vire rotina.

3. Escolher um tipo para um público que não participa

BDD só compensa se pessoas fora da engenharia realmente leem ou escrevem os cenários.

Keyword-driven só compensa se analistas ou usuários técnicos realmente montam testes com palavras-chave.

Se apenas desenvolvedores mantêm a suíte, uma estrutura modular ou híbrida simples pode ser mais eficiente.

Como escolher um tipo de framework

Use critérios práticos.

1. Tamanho e vida útil da suíte

Teste descartável: linear pode bastar.
Suíte mantida por meses: modular, no mínimo.
Suíte grande e crítica: híbrido provavelmente será necessário.

2. Quem escreve os testes

Apenas engenharia: modular ou híbrido.
QA técnico + engenharia: modular com dados externos.
QA não-programador ou negócio: keyword-driven ou BDD.

3. Variação de dados

Se o fluxo é estável, mas os dados variam muito, use data-driven.

Exemplos:

cálculo de frete;
regras de desconto;
permissões por perfil;
validação de payloads;
limites de campos.

4. Problemas de comunicação

Se produto, QA e engenharia interpretam requisitos de formas diferentes, BDD pode ajudar porque força uma especificação compartilhada.

5. Habilidades da equipe

O melhor framework é aquele que sua equipe consegue manter. Uma arquitetura sofisticada que ninguém entende falha mais rápido do que uma estrutura simples e bem aplicada.

Na prática, muitas equipes terminam com um híbrido:

modular como base;
data-driven para casos com muitas combinações;
BDD onde a colaboração com produto é importante;
palavras-chave quando não-programadores precisam montar testes.

Comece simples. Adicione estrutura quando a dor real aparecer. Para estratégias além do tipo de framework, a distinção entre cenário de teste versus caso de teste ajuda a definir o escopo correto de cada teste.

Onde uma plataforma ajuda

Escolher o tipo de framework é uma decisão de arquitetura. Executá-lo bem depende das ferramentas.

Para testes de API, o Apidog oferece suporte à reutilização modular por meio de requisições compartilhadas e parametrizadas, execuções data-driven com CSV e JSON, e um construtor visual de testes que permite a não-programadores montar testes. Isso representa o espírito de uma estrutura keyword-driven sem exigir que a equipe crie manualmente uma biblioteca própria de palavras-chave.

Isso importa porque um framework só funciona se a equipe consegue segui-lo de forma consistente. Uma plataforma que já incorpora padrões de organização ajuda a manter a suíte coerente conforme os testes crescem e pessoas entram ou saem do projeto.

Você pode baixar o Apidog para ver esses padrões em uso e decidir quanto código de framework personalizado ainda faz sentido para sua equipe. Em muitos casos, menos do que parece, porque o Apidog já cobre camadas de requisição, dados e relatórios que um framework manual precisaria reimplementar.

Perguntas frequentes

Qual a diferença entre uma ferramenta de automação e um framework de automação de testes?

Uma ferramenta executa testes, como um driver de navegador ou um cliente HTTP. Um framework define a estrutura ao redor dessas ferramentas: organização dos testes, reutilização de lógica, dados, execução e relatórios.

Você pode usar uma ferramenta sem um framework, mas a manutenção tende a ficar difícil conforme a suíte cresce.

Qual o melhor tipo de framework de automação de testes?

Não existe um melhor universal.

Linear: bom para scripts descartáveis.
Modular: boa base para a maioria das equipes técnicas.
Data-driven: ideal para muitas variações de entrada.
Keyword-driven: útil quando não-programadores criam testes.
BDD: útil quando produto, QA e engenharia precisam compartilhar especificações.
Híbrido: comum em suítes grandes e maduras.

Escolha com base na equipe, no tempo de vida da suíte e no custo de manutenção esperado.

O BDD é apenas para testes de API ou apenas para testes de UI?

Não. BDD é um padrão estrutural, não uma camada de teste. O formato Dado-Quando-Então pode ser usado em testes unitários, de API ou de UI.

O requisito principal é o público: BDD faz mais sentido quando pessoas fora da engenharia leem ou escrevem os cenários.

Posso mudar o tipo de framework depois que a suíte já existe?

Sim, mas o custo aumenta com o tamanho da suíte.

Migrar de linear para modular significa extrair funções reutilizáveis de scripts repetidos. Migrar para data-driven exige separar dados da lógica. Migrar para BDD exige criar cenários e definições de passo.

Por isso, vale escolher uma estrutura mínima que consiga escalar desde o início.

Projetos pequenos precisam de um framework?

Um projeto realmente curto pode usar um script linear sem grande estrutura. Mas projetos pequenos frequentemente crescem.

Se a suíte vai durar mais do que algumas semanas ou será mantida por mais de uma pessoa, uma estrutura modular leve geralmente já compensa.

Como Testar API SOAP Online: Ferramentas e Exemplo Prático

Lucas — Fri, 22 May 2026 07:23:24 +0000

SOAP não desapareceu. Sistemas bancários, gateways de pagamento, serviços governamentais e plataformas empresariais mais antigas ainda expõem endpoints SOAP, e alguém precisa testá-los. Se você passou sua carreira em REST e JSON, um serviço SOAP pode parecer estranho: o protocolo é mais rígido, os payloads são XML e o contrato fica em um arquivo WSDL separado.

Experimente o Apidog hoje

A boa notícia: testar uma API SOAP online fica simples quando você entende o que o serviço espera. Neste guia, você verá as diferenças práticas entre SOAP e REST, como montar uma requisição real, quais cabeçalhos validar e como automatizar testes com ferramentas que leem WSDL.

Por que o teste SOAP é diferente

REST é um estilo arquitetural. SOAP é um protocolo com regras formais. Essa diferença muda a forma como você testa.

Uma mensagem SOAP é sempre um documento XML dentro de um envelope. Esse envelope contém:

Header: metadados, como autenticação, roteamento ou WS-Security.
Body: operação chamada e seus parâmetros.
Namespaces XML obrigatórios.
Um Content-Type específico, normalmente text/xml ou application/soap+xml.

Você não envia um JSON solto. Um envelope malformado pode ser rejeitado antes de chegar à lógica da aplicação.

Outra diferença importante é que SOAP quase sempre usa HTTP POST, mesmo para operações de leitura.

O ponto central é o WSDL. Um WSDL, ou Web Services Description Language, é o contrato que descreve:

operações disponíveis;
formato exato das requisições;
formato esperado das respostas;
namespaces;
endpoint real do serviço;
binding e protocolo de transporte.

Ao testar SOAP, trate o WSDL como seu mapa. Um bom testador SOAP online importa o WSDL e gera modelos de requisição, evitando que você escreva envelopes manualmente. Se quiser entender melhor esse tipo de contrato, veja também este guia sobre teste de contrato de API.

Como uma requisição SOAP realmente se parece

Aqui está uma requisição SOAP realista para um serviço de conversão de moeda:

POST /CurrencyService.asmx HTTP/1.1
Host: rates.example.com
Content-Type: text/xml; charset=utf-8
SOAPAction: "https://rates.example.com/ConvertAmount"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:cur="https://rates.example.com/">
  <soap:Header>
    <cur:AuthToken>e9f2a1c7-4b8d-4c2a-9f31-7d6e5a4b3c21</cur:AuthToken>
  </soap:Header>
  <soap:Body>
    <cur:ConvertAmount>
      <cur:FromCurrency>USD</cur:FromCurrency>
      <cur:ToCurrency>EUR</cur:ToCurrency>
      <cur:Amount>250.00</cur:Amount>
    </cur:ConvertAmount>
  </soap:Body>
</soap:Envelope>

A resposta segue o mesmo padrão:

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:cur="https://rates.example.com/">
  <soap:Body>
    <cur:ConvertAmountResponse>
      <cur:ConvertAmountResult>231.45</cur:ConvertAmountResult>
    </cur:ConvertAmountResponse>
  </soap:Body>
</soap:Envelope>

Ao testar, valide pelo menos estes pontos:

HTTP status: 200
Content-Type: text/xml ou application/soap+xml
Ausência de <soap:Fault>
Presença do elemento esperado no Body
Valor retornado compatível com o cenário

Dois detalhes costumam causar erro:

Muitos serviços exigem o cabeçalho HTTP SOAPAction.
Uma falha SOAP pode vir com HTTP 200.

Ou seja: verificar apenas o status HTTP não é suficiente. Seu teste precisa analisar o XML da resposta e procurar por <soap:Fault>. É aqui que asserções de API estruturadas fazem diferença.

Ferramentas online para testar APIs SOAP

Apidog

Apidog lida com SOAP junto com REST, GraphQL e WebSocket em um único lugar.

Fluxo prático:

Importe o WSDL.
Escolha a operação SOAP.
Edite os parâmetros gerados.
Configure headers como Content-Type, SOAPAction e autenticação.
Envie a requisição.
Adicione asserções sobre elementos XML.
Encadeie chamadas em um cenário.
Execute como teste automatizado.

Como o Apidog também projeta e simula APIs, você pode simular uma resposta SOAP antes que o serviço real esteja pronto. Baixe o Apidog para testar serviços SOAP na versão gratuita.

SoapUI

SoapUI é uma das ferramentas mais tradicionais para teste SOAP. Você aponta para um WSDL, e ele cria um projeto com as operações disponíveis.

Use SoapUI quando precisar de:

testes funcionais SOAP;
execução orientada a dados;
validações detalhadas de XML;
suporte amplo a cenários SOAP legados.

A edição open source é gratuita e robusta. A experiência é mais pesada por ser uma aplicação desktop Java, e relatórios mais avançados ficam na versão paga ReadyAPI. Para mais contexto, veja o que é o SoapUI e como funciona.

Postman

Postman pode enviar requisições SOAP, mas exige configuração manual.

Checklist mínimo no Postman:

Método: POST.
Body: raw.
Tipo: XML.
Header Content-Type: text/xml; charset=utf-8.
Header SOAPAction, se o serviço exigir.
Envelope SOAP completo no corpo.

Funciona bem para verificações pontuais. Porém, como o Postman não interpreta o WSDL automaticamente, você precisa montar os envelopes por conta própria.

Testadores SOAP baseados em navegador

Ferramentas web leves permitem colar uma URL WSDL e disparar requisições direto do navegador.

Use para:

confirmar se o endpoint está ativo;
validar rapidamente uma operação;
reproduzir um erro simples.

Evite para:

regressão automatizada;
testes orientados a dados;
asserções complexas;
organização de suítes de teste.

Um fluxo de trabalho rápido para testes SOAP

Siga este fluxo para testar uma API SOAP sem perder tempo com XML manual.

1. Obtenha o WSDL

Muitos serviços expõem o WSDL adicionando ?wsdl ao endpoint:

https://example.com/CurrencyService.asmx?wsdl

Abra no navegador e confirme que o XML carrega.

2. Importe o WSDL na ferramenta

Use uma ferramenta como Apidog ou SoapUI para importar o contrato. Ela deve gerar modelos de requisição para cada operação.

3. Escolha uma operação

Exemplo:

ConvertAmount

Verifique os parâmetros esperados:

FromCurrency
ToCurrency
Amount

4. Preencha valores reais

Exemplo:

<cur:FromCurrency>USD</cur:FromCurrency>
<cur:ToCurrency>EUR</cur:ToCurrency>
<cur:Amount>250.00</cur:Amount>

Evite começar com dados fictícios inválidos. Primeiro valide o caminho feliz.

5. Configure os headers

Headers comuns:

Content-Type: text/xml; charset=utf-8
SOAPAction: "https://rates.example.com/ConvertAmount"

Se a API usa SOAP 1.2, o Content-Type pode ser:

Content-Type: application/soap+xml; charset=utf-8

6. Envie e inspecione o corpo

Não pare no status HTTP. Abra o XML de resposta e procure por:

<soap:Fault>

Se existir, a chamada falhou, mesmo que o HTTP status seja 200.

7. Adicione asserções

Em um cenário de sucesso, valide:

ausência de <soap:Fault>;
existência do elemento de resposta;
valor esperado;
tipo ou formato do valor;
tempo de resposta, se relevante.

Exemplo de expectativa:

Não deve existir: //soap:Fault
Deve existir: //cur:ConvertAmountResult
Valor esperado: 231.45

Para organizar esses testes em uma suíte sustentável, veja este guia sobre construção de conjuntos de testes para automação de API.

Falhas SOAP e como asserir sobre elas

Uma falha SOAP é a estrutura de erro do protocolo. Ela normalmente contém:

faultcode;
faultstring;
detail, quando há informações adicionais.

Exemplo:

<soap:Fault>
  <faultcode>soap:Client</faultcode>
  <faultstring>Invalid currency code</faultstring>
  <detail>
    <errorCode>UNSUPPORTED_CURRENCY</errorCode>
  </detail>
</soap:Fault>

Como essa falha pode chegar com HTTP 200, uma automação que valida apenas o status cria falsos positivos.

Em testes de sucesso, adicione uma asserção como:

<soap:Fault> não deve existir

Em testes de erro esperado, valide o oposto:

<soap:Fault> deve existir
faultcode deve ser soap:Client
faultstring deve conter Invalid currency code

Isso é importante porque serviços SOAP frequentemente representam regras de negócio como falhas, por exemplo:

transação recusada;
cartão vencido;
moeda não suportada;
token inválido;
usuário sem permissão.

A documentação de falhas SOAP do W3C descreve a estrutura formal.

Atenção ao WS-Security

Muitos serviços SOAP empresariais exigem WS-Security. Nesses casos, a autenticação pode estar dentro do Header, não apenas em um header HTTP comum.

Exemplo simplificado:

<soap:Header>
  <wsse:Security>
    <wsse:UsernameToken>
      <wsse:Username>usuario</wsse:Username>
      <wsse:Password>senha</wsse:Password>
    </wsse:UsernameToken>
  </wsse:Security>
</soap:Header>

Se suas chamadas retornarem falha de autenticação, verifique:

o WSDL;
a documentação do serviço;
o perfil WS-Security exigido;
necessidade de assinatura;
token;
certificado;
timestamp;
namespace correto.

Ferramentas como SoapUI e Apidog permitem configurar esses headers sem escrever todo o XML manualmente.

Lendo um WSDL sem se perder

Um WSDL pode parecer intimidador, mas você não precisa ler tudo. Foque em quatro partes.

`types`

Define as estruturas de dados, geralmente com XML Schema.

Procure aqui:

campos obrigatórios;
tipos;
tamanho máximo;
enumerações;
formatos aceitos.

`message`

Descreve as mensagens de entrada e saída.

Use para entender:

request;
response;
parâmetros esperados;
elemento raiz da operação.

`portType`

Lista as operações disponíveis.

Exemplo:

ConvertAmount
GetExchangeRate
ValidateCurrency

`binding` e `service`

Indicam:

protocolo;
formato da mensagem;
endpoint real;
endereço para envio da requisição.

Um detalhe importante: um WSDL pode importar outros arquivos:

<xs:import namespace="..." schemaLocation="..."/>

Se a ferramenta informar que um tipo está ausente, provavelmente algum schema importado não foi resolvido. Verifique se todas as URLs referenciadas estão acessíveis a partir do ambiente onde a ferramenta está rodando.

Teste SOAP orientado a dados

Uma única chamada de caminho feliz raramente cobre o comportamento real de um serviço SOAP.

Para um serviço de moeda, teste pelo menos:

Caso	FromCurrency	ToCurrency	Amount	Esperado
Conversão válida	USD	EUR	250.00	Sucesso
Moeda inválida	USD	XXX	250.00	Falha
Valor zero	USD	EUR	0	Regra esperada
Valor negativo	USD	EUR	-10	Falha

Para um serviço de pagamento, teste:

Caso	Entrada	Esperado
Cartão aprovado	cartão válido	sucesso
Cartão recusado	cartão recusado	falha de negócio
Cartão vencido	validade expirada	falha
Token inválido	auth inválida	falha de segurança

O padrão é:

Criar uma requisição SOAP com placeholders.
Alimentar a execução com uma tabela de dados.
Executar uma chamada para cada linha.
Validar a resposta esperada por caso.

Exemplo conceitual de placeholders:

<cur:ConvertAmount>
  <cur:FromCurrency>{{fromCurrency}}</cur:FromCurrency>
  <cur:ToCurrency>{{toCurrency}}</cur:ToCurrency>
  <cur:Amount>{{amount}}</cur:Amount>
</cur:ConvertAmount>

O SoapUI suporta esse padrão há anos, e o Apidog também permite executá-lo por meio de cenários. Para o padrão mais amplo, veja este guia sobre teste de API orientado a dados com CSV e JSON.

Checklist para depurar erros SOAP

Quando uma requisição SOAP falhar, revise nesta ordem:

O WSDL carrega corretamente?
O endpoint usado é o mesmo definido em service?
O método HTTP é POST?
O Content-Type está correto para SOAP 1.1 ou SOAP 1.2?
O SOAPAction está presente quando exigido?
Os namespaces do envelope estão corretos?
A operação está no namespace certo?
Todos os campos obrigatórios foram enviados?
O serviço exige WS-Security?
A resposta contém <soap:Fault>?
O faultstring indica erro de autenticação, schema ou regra de negócio?

Perguntas frequentes

Qual a diferença entre o teste SOAP e REST?

O teste SOAP trabalha com um protocolo XML rígido, contrato WSDL, envelopes obrigatórios e falhas retornadas dentro do corpo da resposta. O teste REST geralmente usa JSON, convenções mais flexíveis e códigos HTTP mais significativos. Em SOAP, sempre analise o corpo da resposta para confirmar se a chamada realmente foi bem-sucedida.

Preciso do WSDL para testar uma API SOAP?

Você pode enviar uma requisição SOAP sem WSDL se souber exatamente como montar o envelope. Mas o WSDL facilita muito, porque ferramentas conseguem gerar modelos corretos automaticamente. A maioria dos serviços expõe o WSDL adicionando ?wsdl à URL do endpoint.

Por que minha requisição SOAP retorna uma falha mesmo com status 200?

Porque SOAP pode reportar erros como <soap:Fault> dentro do corpo da resposta, mesmo com HTTP 200. Causas comuns incluem SOAPAction ausente ou incorreto, envelope malformado, namespace errado, parâmetro inválido ou falha de autenticação.

Posso testar APIs SOAP online gratuitamente?

Sim. Apidog suporta SOAP na versão gratuita e importa arquivos WSDL. A edição open source do SoapUI também é voltada para SOAP. Testadores baseados em navegador servem para verificações rápidas, mas têm limitações em automação e asserções.

Como automatizo testes de API SOAP?

Importe o WSDL, crie cenários com as operações necessárias, adicione asserções sobre o XML da resposta, valide a ausência ou presença de <soap:Fault> e execute a suíte no runner da ferramenta ou em um pipeline de CI. SoapUI e Apidog suportam esse tipo de fluxo para regressão SOAP.

Casos de Uso de API Mocking: Quando e Por Que Simular uma API

Lucas — Fri, 22 May 2026 07:23:07 +0000

A maioria das equipes sabe como simular (mock) uma API. O ponto crítico é decidir quando isso realmente ajuda e quando vira apenas mais uma camada de manutenção. Uma simulação usada no momento certo remove gargalos reais; uma simulação criada por hábito se distancia da produção e passa a validar uma ficção.

Experimente o Apidog hoje

Este guia foca no “quando” e em como aplicar mocks de forma prática: desenvolver frontend e backend em paralelo, exercitar caminhos de erro, substituir serviços de terceiros instáveis, preparar demonstrações e manter o CI rápido e previsível.

Desenvolvimento paralelo de frontend e backend

Este é o caso clássico. O frontend precisa consumir um endpoint que o backend ainda não entregou. Sem mock, a equipe de frontend espera ou implementa com base em suposições que podem quebrar no primeiro contato com o serviço real.

A abordagem mais segura é começar pelo contrato:

Defina o contrato da API em uma especificação compartilhada, como OpenAPI.
Gere ou configure o mock a partir desse contrato.
Faça o frontend consumir o mock usando a mesma estrutura esperada da API real.
Quando o backend estiver pronto, troque apenas a URL base.
Valide se backend e frontend continuam aderentes ao contrato.

Exemplo de separação por ambiente:

const API_BASE_URL =
  process.env.NODE_ENV === "development"
    ? "https://mock.example.com"
    : "https://api.example.com";

const response = await fetch(`${API_BASE_URL}/orders`);
const orders = await response.json();

O ponto essencial é que o mock não deve ser inventado apenas pelo frontend. Ele precisa refletir um contrato compartilhado. Esse é o mesmo princípio por trás do teste de contrato de API: as equipes concordam primeiro no formato, depois cada lado implementa sua parte.

O benefício aparece ao longo do projeto. O frontend não fica bloqueado, o backend evita interrupções por endpoints parcialmente prontos, e produto e design conseguem validar uma versão clicável mais cedo. O custo de manutenção permanece baixo quando o mock é gerado a partir da especificação, em vez de escrito manualmente.

Testando caminhos de erro que você não pode acionar sob demanda

Uma API saudável tende a retornar 200. O problema é que seu cliente também precisa lidar com 429, 500, 503, payloads inválidos e timeouts. Um servidor real funcionando corretamente não vai produzir esses cenários sempre que seus testes precisarem.

Mocks permitem forçar essas respostas de forma controlada.

Exemplos de cenários úteis:

Falha a testar	Configuração da simulação	O que prova
Erro do servidor	Retornar `500`	Cliente tenta novamente e degrada graciosamente
Limitação de taxa	Retornar `429` com `Retry-After`	Cliente respeita o intervalo correto
Rede lenta	Atrasar a resposta em 5s	Cliente trata timeout corretamente
Payload inválido	Retornar JSON quebrado	Parser falha sem derrubar a aplicação

Exemplo de teste de retry:

async function fetchWithRetry(url: string, retries = 2) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    const response = await fetch(url);

    if (response.ok) {
      return response.json();
    }

    if (attempt === retries) {
      throw new Error(`Request failed with status ${response.status}`);
    }
  }
}

Com um mock, você pode configurar a primeira resposta como 500 e a segunda como 200, verificando se o retry realmente acontece.

Este é um dos usos mais importantes de simulação. Tratamento de erro não exercitado é tratamento de erro não validado. Combine mocks com asserções de API para garantir que cada caminho de falha foi testado, não apenas assumido.

Também vale simular respostas HTTP válidas, mas inválidas para o domínio:

200 com preço negativo.
Pedido com status fora do enum esperado.
Lista paginada com cursor next quebrado.
Campo obrigatório ausente.
Tipo incorreto em uma propriedade.

Um servidor real correto nunca deveria enviar isso. Um mock pode enviar esses casos deliberadamente para revelar suposições escondidas no seu código de parsing.

Substituindo uma API de terceiros

Chamar um processador de pagamento real, serviço de mapas ou API de envio dentro da suíte de testes pode ser lento, caro e instável. Além disso, você depende de um sistema que não controla. Se o sandbox do fornecedor cair, seus testes também caem.

A solução prática é simular a API de terceiros:

Registre respostas reais uma vez ou use o esquema publicado pelo fornecedor.
Configure um mock com os principais cenários de sucesso e erro.
Execute seus testes automatizados contra esse mock.
Mantenha uma verificação agendada contra o serviço real para detectar mudanças.

Exemplo de configuração por ambiente:

THIRD_PARTY_API_URL=https://mock-payments.example.com

No código:

const paymentApiUrl = process.env.THIRD_PARTY_API_URL;

await fetch(`${paymentApiUrl}/charges`, {
  method: "POST",
  body: JSON.stringify({
    amount: 4990,
    currency: "BRL",
  }),
});

Isso torna os testes mais rápidos, gratuitos e determinísticos. Eles continuam funcionando mesmo se o fornecedor tiver uma interrupção.

O cuidado necessário é manter o mock atualizado. O terceiro pode alterar a API sem aviso. Para reduzir esse risco, execute um job agendado que chama o serviço real e valida se a resposta ainda corresponde ao formato esperado pelo mock. Essa verificação de contrato deve ser pequena, isolada e separada da suíte principal.

Também vale acompanhar o changelog do fornecedor para detectar mudanças planejadas antes que um teste de contrato falhe.

Alimentando demonstrações e protótipos

Uma demonstração que chama serviços reais na frente de um cliente é uma aposta. Uma consulta lenta, uma resposta vazia ou uma indisponibilidade temporária podem comprometer uma apresentação.

Mocks tornam a demonstração determinística. Você define exatamente quais dados serão retornados:

Um pedido que chega no prazo.
Um dashboard com métricas coerentes.
Uma busca com resultados limpos.
Um fluxo de aprovação sem dados inesperados.
Um usuário com permissões específicas.

O objetivo aqui não é testar. É controlar a experiência.

Para protótipos, o mock permite validar um fluxo de UI antes de qualquer backend existir. A equipe consegue construir telas, testar navegação e coletar feedback sem esperar pela API real.

Exemplo simples de resposta mockada para um dashboard:

{
  "revenue": 128450,
  "orders": 342,
  "conversionRate": 4.8,
  "status": "healthy"
}

Ferramentas dessa categoria são comparadas neste artigo sobre ferramentas de simulação de API online.

Um mock de protótipo também pode funcionar como documento de design. Se ele retorna os mesmos formatos que a API final deverá servir, o código de frontend escrito contra ele não precisa ser descartável. Quando o backend honrar o mesmo contrato, a troca pode se limitar à URL base.

Mantendo o CI rápido e estável

Uma suíte de testes que chama serviços externos no CI herda todos os problemas desses serviços:

Falhas de rede.
Rate limits.
Sandboxes instáveis.
Dados de staging compartilhados.
Builds concorrentes alterando o mesmo estado.

Cada um desses pontos pode gerar falhas intermitentes que não têm relação com o código em revisão.

Mocks tornam a suíte mais hermética. Cada execução começa do mesmo estado, evita ida e volta pela rede e falha apenas quando o código testado realmente quebra.

Uma estratégia prática:

Use mocks na suíte executada a cada commit.
Mantenha os testes rápidos e determinísticos.
Execute uma suíte menor de contrato contra APIs reais em um agendamento.
Use essa suíte agendada para validar se os mocks continuam fiéis à produção.

Exemplo de divisão no pipeline:

name: tests

on:
  pull_request:
  push:

jobs:
  unit-and-component-tests:
    runs-on: ubuntu-latest
    env:
      API_BASE_URL: https://mock-api.example.com
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm test

E uma verificação separada para contrato:

name: contract-tests

on:
  schedule:
    - cron: "0 */6 * * *"

jobs:
  contract-tests:
    runs-on: ubuntu-latest
    env:
      API_BASE_URL: https://api.example.com
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:contract

Essa separação é central para um pipeline de testes CI/CD saudável.

O ganho de velocidade não é apenas conveniência. Uma suíte que cai de doze minutos para noventa segundos muda o comportamento da equipe. Desenvolvedores rodam os testes antes do push, revisores recebem feedback mais rápido, e falhas passam a ser levadas a sério.

Quando não simular

Mocks têm um modo de falha claro: ficarem diferentes da realidade. Quando isso acontece, os testes continuam verdes enquanto produção quebra.

Evite simular quando o objetivo do teste é validar a integração real. Testes de contrato e ponta a ponta existem para verificar o limite real entre sistemas. Se você simula esse limite, remove o propósito do teste.

Também evite mocks quando:

A dependência real é rápida, gratuita e confiável no ambiente de teste.
Você nunca valida o mock contra a API real.
O comportamento testado depende de detalhes reais da infraestrutura.
O custo de manter o mock é maior do que chamar o serviço real.

A regra prática é:

Simule para velocidade, isolamento e controle.
Teste contra a realidade para confirmar que os mocks continuam verdadeiros.

Se você quiser manter simulação e verificação de contrato no mesmo fluxo, o Apidog gera mocks a partir do design da sua API e executa testes tanto contra a simulação quanto contra o endpoint real. Para configurar isso, baixe o Apidog e comece com sua especificação existente. Para a base conceitual, veja o que é uma API simulada.

Perguntas frequentes

Quando devo simular uma API em vez de chamar a real?

Simule quando você precisa de velocidade, isolamento ou controle. Os principais casos são desenvolvimento paralelo contra um backend inacabado, testes de caminhos de erro, substituição de serviços de terceiros lentos ou pagos, demonstrações previsíveis e CI estável.

Chame a API real para testes de contrato, integração e ponta a ponta.

A simulação substitui os testes de integração?

Não. Simulação é mais útil em testes de unidade, componentes e fluxos controlados. Testes de integração e contrato devem atingir o limite real, porque o objetivo deles é confirmar que o serviço real corresponde ao contrato.

Como evito que uma simulação fique desatualizada?

Gere o mock a partir de um esquema compartilhado, como OpenAPI. Depois, execute testes de contrato agendados contra a API real para confirmar que a resposta em produção continua compatível com o esquema.

Posso simular uma API de terceiros que não controlo?

Sim. Esse é um dos melhores usos de mocks. Registre respostas reais ou use o esquema publicado pelo fornecedor, teste contra o mock no dia a dia e mantenha uma verificação agendada contra o serviço real para detectar mudanças.

A simulação é útil para demonstrações e protótipos?

Sim. Em demonstrações, mocks tornam os dados previsíveis e evitam falhas causadas por serviços externos. Em protótipos, permitem validar fluxos de UI antes do backend existir.

Postman CLI vs Newman: Qual Runner de Linha de Comando Usar?

Lucas — Fri, 22 May 2026 07:22:54 +0000

Por anos, executar coleções Postman fora do aplicativo desktop significava usar uma ferramenta: Newman. Depois, o Postman lançou o Postman CLI, sua ferramenta oficial de linha de comando. Hoje, as duas opções executam coleções sem GUI, funcionam em CI/CD e rodam scripts pm.test. A diferença prática é o modelo operacional: Newman executa arquivos locais sem conta; Postman CLI se conecta à conta Postman, busca coleções na nuvem e envia resultados de volta para o workspace. A escolha depende de onde você quer manter a fonte da verdade dos testes e onde quer consultar os resultados.

Experimente o Apidog hoje

O que é Newman

Newman é o executor de coleções de linha de comando original do Postman. Ele é open source, distribuído via npm e gratuito.

Use Newman quando você quer executar uma coleção exportada do Postman como arquivo JSON:

npm install -g newman

newman run checkout-api.postman_collection.json \
  --environment staging.postman_environment.json

Na prática, Newman:

executa cada requisição da coleção;
roda scripts e asserções pm.test;
retorna código de saída diferente de zero quando há falha;
funciona sem conta Postman;
não precisa de chave de API;
pode rodar offline se os arquivos estiverem disponíveis localmente.

Esse modelo é simples para CI/CD: você versiona a coleção e o ambiente no repositório, instala Newman no job e deixa o pipeline falhar quando algum teste falhar.

Exemplo com saída JUnit para ferramentas de CI:

newman run checkout-api.postman_collection.json \
  --environment staging.postman_environment.json \
  --reporters cli,junit \
  --reporter-junit-export reports/newman-results.xml

Para relatório HTML, você pode usar um reporter da comunidade:

npm install -g newman newman-reporter-htmlextra

newman run checkout-api.postman_collection.json \
  --environment staging.postman_environment.json \
  --reporters cli,htmlextra \
  --reporter-htmlextra-export reports/newman-report.html

Nosso guia sobre a diferença entre Newman e Postman explica como Newman se relaciona com o aplicativo desktop.

O que é Postman CLI

Postman CLI é a ferramenta oficial de linha de comando do Postman. Ao contrário do Newman, ela é instalada como um binário e se autentica com uma chave de API da sua conta Postman.

Exemplo básico:

# instalar no macOS/Linux
curl -o- "https://dl-cli.pstmn.io/install/osx_64.sh" | sh

# autenticar
postman login --with-api-key YOUR_API_KEY

# executar coleção
postman collection run checkout-api

A principal diferença é a integração com a nuvem Postman. Com o Postman CLI, você pode:

executar coleções armazenadas no workspace Postman;
buscar coleções por ID;
enviar resultados de execução de volta para a plataforma Postman;
consultar histórico e dashboards no Postman;
executar verificações de governança e linting de definições de API.

Ou seja: o Postman CLI não é apenas um executor de coleção. Ele funciona como um agente de pipeline conectado à plataforma Postman.

Use-o quando sua equipe já trabalha no workspace Postman e quer centralizar lá a execução, o histórico e as regras de governança.

Comparação lado a lado

Aspecto	Postman CLI	Newman
Fonte	Código fechado, ferramenta oficial Postman	Código aberto
Instalação	Script de instalação, binário único	Pacote npm
Conta Postman	Obrigatória, via chave de API	Não obrigatória
Fonte da coleção	Nuvem Postman por ID ou arquivo local	Arquivo JSON local
Resultados da execução	Enviados para a plataforma Postman	Terminal e arquivos de relatório
Governança/linting de API	Incluído	Não incluído
Reporters	Mais limitado; resultados ficam no Postman	CLI, JUnit e reporters HTML da comunidade
Uso offline	Limitado; projetado para a nuvem	Funciona offline com arquivos locais
Maturidade	Mais recente	Padrão da comunidade há mais tempo
Custo	Gratuito, mas vinculado aos limites do plano Postman	Gratuito, sem conta

O eixo decisivo é a dependência da nuvem Postman.

Se você quer rodar arquivos locais de forma independente, use Newman.
Se você quer integrar execução, histórico e governança ao workspace Postman, use Postman CLI.

Como usar Newman no CI/CD

Com Newman, o fluxo recomendado é:

exportar a coleção Postman como JSON;
exportar o ambiente como JSON, se necessário;
salvar esses arquivos no repositório;
instalar Newman no pipeline;
executar os testes;
falhar o job se algum teste falhar.

Estrutura simples de repositório:

.
├── postman
│   ├── checkout-api.postman_collection.json
│   └── staging.postman_environment.json
└── .github
    └── workflows
        └── api-tests.yml

Exemplo com GitHub Actions:

name: API tests

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  newman:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20

      - name: Install Newman
        run: npm install -g newman newman-reporter-htmlextra

      - name: Run API tests
        run: |
          mkdir -p reports
          newman run postman/checkout-api.postman_collection.json \
            --environment postman/staging.postman_environment.json \
            --reporters cli,junit,htmlextra \
            --reporter-junit-export reports/newman-results.xml \
            --reporter-htmlextra-export reports/newman-report.html

Esse padrão deixa os testes versionados junto com o código. É útil quando você quer revisar alterações de coleção em pull requests.

Veja também nossos guias sobre automação de testes de API em CI/CD e automação de testes de API com GitHub Actions.

Como usar Postman CLI no CI/CD

Com Postman CLI, o fluxo muda:

a coleção fica no workspace Postman;
você cria uma chave de API do Postman;
salva essa chave como secret no provedor de CI;
autentica o CLI durante o job;
executa a coleção por ID ou referência;
consulta resultados no Postman.

Exemplo conceitual com GitHub Actions:

name: API tests with Postman CLI

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  postman-cli:
    runs-on: ubuntu-latest

    steps:
      - name: Install Postman CLI
        run: curl -o- "https://dl-cli.pstmn.io/install/linux64.sh" | sh

      - name: Login to Postman
        run: postman login --with-api-key "${{ secrets.POSTMAN_API_KEY }}"

      - name: Run collection
        run: postman collection run YOUR_COLLECTION_ID

Esse modelo faz sentido quando o workspace Postman é a fonte da verdade. A coleção não precisa estar no repositório, mas o pipeline passa a depender da conta, da chave de API e da disponibilidade da plataforma Postman.

Como decidir a fonte da verdade

Antes de escolher a ferramenta, responda:

Os testes de API devem ser revisados junto com o código?
A equipe quer versionar coleções no Git?
O histórico de execução precisa ficar no Postman?
O pipeline pode depender da nuvem Postman?
A equipe precisa de governança ou linting de API no CI?

Se você quer que o Git seja a fonte da verdade, Newman se encaixa melhor.

Se você quer que o Postman seja a fonte da verdade, Postman CLI se encaixa melhor.

O ângulo da governança

A funcionalidade que mais diferencia o Postman CLI é a governança de API.

Com ele, você pode executar verificações como linting de definição de API contra regras do workspace Postman. Esse tipo de validação pode detectar problemas de nomenclatura, segurança, completude de schema e consistência antes do merge.

Em um pipeline, isso permite bloquear alterações que violam padrões internos.

Newman não tem equivalente. Ele executa coleções e reporta resultados de testes. Esse é o escopo dele.

Portanto:

se você precisa aplicar regras de design de API no pipeline, Postman CLI é a opção alinhada;
se você só precisa executar testes funcionais de coleção, Newman é mais simples.

Essa distinção evita uma comparação injusta. Postman CLI não é apenas “Newman mais novo”. Ele é uma ferramenta de pipeline para a plataforma Postman. Newman é um executor de coleções.

Considerações de migração

Se sua equipe já usa Newman, migrar para Postman CLI só vale a pena se houver um ganho claro.

A migração normalmente exige:

criar e gerenciar uma chave de API Postman;
adicionar secrets ao CI;
alterar como as coleções são obtidas;
aceitar dependência da nuvem Postman;
mover ou sincronizar a fonte da verdade dos testes.

Se você não precisa de histórico centralizado no Postman nem de governança de API, a migração pode adicionar complexidade sem retorno suficiente.

Para equipes começando agora, a decisão depende do fluxo de trabalho:

equipe já usa Postman como plataforma principal: Postman CLI tende a ser natural;
equipe quer versionamento no repositório e independência: Newman tende a ser melhor;
equipe quer evitar dependência do ecossistema Postman: avalie alternativas fora do Postman.

Qual você deve escolher

Escolha Newman se você precisa de:

execução sem conta Postman;
testes versionados no repositório;
execução offline ou em ambientes restritos;
relatórios JUnit ou HTML flexíveis;
pipeline simples e autocontido;
menor dependência de fornecedor.

Escolha Postman CLI se você precisa de:

integração direta com o workspace Postman;
histórico de execução na plataforma Postman;
dashboards centralizados;
governança e linting de API no pipeline;
coleções gerenciadas na nuvem Postman;
fluxo totalmente orientado ao ecossistema Postman.

Se você está avaliando outras opções, consulte também nosso guia sobre como executar coleções Postman em CI sem Newman e nossa análise sobre testes de API sem Postman.

Uma alternativa de ferramenta única: Apidog

Tanto Postman CLI quanto Newman assumem que você criou seus testes no Postman. O Apidog remove essa divisão.

Com o Apidog, você pode:

projetar APIs;
depurar requisições;
criar cenários de teste automatizados;
adicionar asserções visuais;
executar testes em CI/CD com o executor CLI embutido;
usar mock servers;
executar testes de desempenho.

A vantagem prática é reduzir etapas entre design, teste e execução. Não é necessário exportar coleção para depois rodar com outro executor, porque os cenários de teste e o mecanismo de execução fazem parte do mesmo produto.

Você pode baixar o Apidog e usar recursos de teste gratuitamente, incluindo o executor CLI para pipelines.

Perguntas frequentes

O Postman CLI está substituindo o Newman?

O Postman posiciona o Postman CLI como sua ferramenta de linha de comando oficialmente recomendada, mas Newman ainda é mantido e amplamente usado. Newman continua sendo uma boa escolha quando você quer execução sem conta e testes versionados no repositório.

O Postman CLI requer uma conta Postman?

Sim. O Postman CLI autentica com uma chave de API do Postman e foi projetado para conectar execuções ao workspace Postman. Newman não precisa de conta e executa a partir de arquivos locais.

Qual ferramenta oferece melhores relatórios?

Newman é mais flexível para relatórios autônomos, especialmente com JUnit e newman-reporter-htmlextra. Postman CLI envia resultados para a plataforma Postman, o que é conveniente para equipes que já trabalham lá, mas menos flexível se você precisa gerar arquivos de relatório independentes.

O Postman CLI pode executar um arquivo de coleção local?

Sim, o Postman CLI pode executar coleções locais. Porém, seu modelo principal é buscar coleções da nuvem Postman e enviar resultados de volta para a plataforma. Se você quer usar o JSON local como fonte da verdade, Newman se encaixa melhor.

Qual é mais rápido no CI?

Para execução pura de coleções, a diferença costuma ser pequena e depende do tamanho da coleção, da rede e do ambiente de CI. Newman tem uma pegada menor e não precisa sincronizar resultados com a nuvem. Postman CLI adiciona autenticação e envio de resultados para a plataforma. Na maioria dos casos, escolha pela arquitetura do fluxo de trabalho, não por velocidade bruta.

Validação vs Verificação: A Diferença Crucial em Testes

Lucas — Fri, 22 May 2026 07:22:33 +0000

Uma equipe pode implementar exatamente o que está na especificação e ainda assim entregar o produto errado. Também pode construir o produto certo em cima de um código cheio de defeitos. A primeira falha é de validação; a segunda é de verificação. Confundir as duas deixa o processo de qualidade ocupado, mas pouco eficaz.

Experimente o Apidog hoje

Este guia define os dois conceitos, mostra as diferenças práticas e explica como aplicá-los em testes de API com Apidog.

O que é verificação?

A verificação pergunta:

Estamos construindo corretamente?

Ela confirma se uma parte do software está em conformidade com a especificação, o design e os padrões definidos. Em outras palavras, compara a implementação com uma intenção documentada.

A verificação não responde se a intenção estava correta. Ela apenas confirma se o código corresponde ao que foi especificado.

Atividades comuns de verificação:

Revisão de código
Walkthroughs técnicos
Análise estática
Linting
Revisões de design e arquitetura
Verificações de esquema e contrato
Testes unitários
Asserções de status, cabeçalhos e payloads

Exemplo simples:

POST /users

Se a especificação diz que esse endpoint deve retornar:

201 Created
Location: /users/{id}

A verificação confirma se a implementação realmente retorna 201 e o cabeçalho Location.

Ela é principalmente interna: compara artefato com artefato.

Exemplos:

Código vs. design
Resposta da API vs. esquema
Implementação vs. contrato
Endpoint vs. especificação OpenAPI

O que é validação?

A validação pergunta:

Estamos construindo a coisa certa?

Ela verifica se o software realmente atende à necessidade do usuário e resolve o problema real, independentemente do que estava escrito na especificação.

A validação compara o produto com o uso real.

Atividades comuns de validação:

Testes de aceitação do usuário
Testes beta
Testes de usabilidade
Testes ponta a ponta
Demonstrações para stakeholders
Aprovação de fluxos reais de negócio

Exemplo:

Uma API pode seguir perfeitamente a especificação OpenAPI e ainda assim falhar na validação se:

O modelo de paginação for difícil de usar
O fluxo de autenticação não funcionar bem para clientes reais
A resposta não trouxer os dados que os consumidores precisam
O processo exigir workarounds complicados

Nesse caso, o problema não está necessariamente no código. Pode estar na própria especificação.

Validação vs. verificação: diferenças práticas

Dimensão	Verificação	Validação
Pergunta central	Estamos construindo corretamente?	Estamos construindo a coisa certa?
Compara com	Especificação, design, padrões	Necessidades do usuário e uso real
Momento	Contínuo, durante o desenvolvimento	Quando já existe algo utilizável
Métodos típicos	Revisão, linting, testes unitários, schema checks, contrato	Aceitação, beta, ponta a ponta, demonstrações
Direção	Interna: artefato vs. artefato	Externa: produto vs. realidade
Detecta	Bugs, desvios da especificação, quebra de contrato	Requisitos errados, problemas de usabilidade, produto inadequado
Risco ao ignorar	Código instável ou inconsistente	Produto correto tecnicamente, mas inútil

As duas práticas não são intercambiáveis.

Verificação forte com validação fraca gera um produto tecnicamente correto que talvez ninguém queira.
Validação forte com verificação fraca gera a ideia certa implementada em código instável.

Um mnemônico útil:

Verificação testa contra o documento.

Validação testa contra o propósito.

Como aplicar isso em testes de API

APIs tornam essa diferença mais concreta porque normalmente têm um contrato explícito: OpenAPI, JSON Schema ou outra definição de interface.

Esse contrato é a base da verificação.

Verificação em APIs

Verificar uma API significa confirmar se a implementação cumpre o contrato.

Checklist de verificação:

O endpoint retorna os status codes documentados?
A resposta segue o schema esperado?
Os campos têm os nomes e tipos corretos?
Os parâmetros obrigatórios são realmente obrigatórios?
O formato de erro segue o padrão documentado?
Headers importantes estão presentes?
O contrato continua compatível com consumidores existentes?

Exemplo de contrato esperado:

{
  "id": "usr_123",
  "email": "dev@example.com",
  "created_at": "2026-01-10T12:00:00Z"
}

Asserções de verificação poderiam validar:

status === 201
body.id is string
body.email is string
body.created_at is ISO datetime
header.Location exists

Também é aqui que entra o teste de contrato de API. Ele confirma que o produtor da API continua honrando o acordo usado pelos consumidores.

Para consistência de status codes, veja também quais códigos de status HTTP as APIs REST devem usar.

As asserções de API são a unidade prática da verificação: status, schema, headers e conteúdo.

Validação em APIs

Validar uma API significa confirmar se ela atende ao consumidor em um fluxo real.

Checklist de validação:

Um cliente consegue completar o fluxo principal sem workaround?
O fluxo de autenticação funciona para integrações reais?
Os dados retornados respondem às perguntas do consumidor?
A API permite criar, atualizar, consultar e excluir recursos de forma coerente?
Os exemplos da documentação refletem o uso real?
O contrato faz sentido para o domínio do problema?

Exemplo de cenário de validação:

Registrar um usuário
Fazer login
Criar um recurso
Consultar o recurso criado
Atualizar o recurso
Confirmar que a alteração foi persistida
Excluir o recurso
Confirmar que ele não está mais disponível

Esse tipo de cenário valida um fluxo de uso, não apenas um endpoint isolado.

Um teste de schema de GET /users/{id} é verificação. Um fluxo completo de onboarding de usuário é validação.

Para separar melhor esses níveis, veja cenários de teste vs. casos de teste.

Onde o Apidog se encaixa

O Apidog ajuda a aplicar os dois lados porque centraliza design, teste e documentação de API em um mesmo workspace.

Usando Apidog para verificação

Para verificação, o design da API funciona como a fonte da verdade.

Fluxo prático:

Defina ou importe a especificação da API.
Crie testes para os endpoints.
Adicione asserções de status, schema, headers e payload.
Compare as respostas reais com o contrato.
Execute os testes continuamente.

Exemplo de verificações para POST /payments:

Status esperado: 201
Campo obrigatório: payment_id
Tipo de payment_id: string
Header esperado: Location
Formato de erro para moeda inválida: conforme especificação

Como o teste usa o mesmo contrato que define a API, você reduz o risco de manter duas versões divergentes da verdade.

Para manter isso no fluxo de entrega, execute os testes em CI/CD. Veja como automatizar testes de API em CI/CD.

Usando Apidog para validação

Para validação, use cenários que encadeiam múltiplas requisições.

Exemplo de cenário:

1. Criar usuário
2. Fazer login
3. Criar recurso
4. Consultar recurso
5. Atualizar recurso
6. Confirmar atualização
7. Excluir recurso

Esse teste se aproxima do comportamento de um cliente real. Ele ajuda a responder se a API resolve o problema completo, e não apenas se cada endpoint individual está tecnicamente correto.

Os relatórios por etapa ajudam a separar os tipos de falha:

Incompatibilidade de schema: falha de verificação
Fluxo multi-etapas quebrado: falha de validação
Status code incorreto: falha de verificação
Fluxo impossível para o consumidor: falha de validação

Baixe o Apidog para configurar verificações de contrato e validações de fluxo na sua própria API.

Exemplo real: API de pagamentos

Imagine uma equipe criando uma API de pagamentos.

A especificação diz:

POST /payments

Entrada:

{
  "amount": 19.99,
  "currency": "BRL"
}

Resposta esperada:

201 Created

{
  "payment_id": "pay_123"
}

Moedas inválidas devem retornar:

400 Bad Request

Verificação

A equipe verifica a API:

O handler segue o design.
O endpoint retorna 201.
O campo payment_id existe.
O tipo de payment_id é string.
O erro 400 segue o formato documentado.
Os testes de contrato passam.

Resultado: a API está construída corretamente segundo a especificação.

Falha de validação

Então um cliente real integra a API.

Ele percebe que amount é um número de ponto flutuante. Em alguns casos, operações como 0.1 + 0.2 geram arredondamentos incompatíveis com a fatura.

A especificação dizia:

amount:
  type: number

A implementação obedeceu perfeitamente.

O problema é que a especificação estava errada. Dinheiro não deveria ser representado como float. Uma abordagem mais segura seria usar unidades menores inteiras, por exemplo:

{
  "amount_cents": 1999,
  "currency": "BRL"
}

Esse não é um bug simples de implementação. É uma falha de validação.

A correção não é “ajustar o código para seguir a especificação”. A correção é mudar a especificação.

Checklist prático para releases de API

Antes de publicar uma API, execute as duas listas.

Verificação: contra a especificação

Confirme que:

Todos os endpoints retornam os status codes documentados
Todas as respostas seguem os schemas definidos
Campos obrigatórios são realmente obrigatórios
Parâmetros inválidos geram os erros esperados
Headers documentados são retornados
O formato de erro é consistente
Testes de contrato passam para endpoints consumidos externamente
A suíte roda no pipeline de CI/CD

Validação: contra o propósito

Confirme que:

Um novo consumidor consegue completar o fluxo principal
A API resolve o caso de uso real
O fluxo de autenticação é viável para integrações existentes
Os dados retornados são suficientes para o cliente
A documentação mostra exemplos realistas
Stakeholders aprovam o comportamento final
Não há workarounds obrigatórios para tarefas comuns

Se apenas a verificação passa, você pode ter uma implementação correta de um design errado.

Se apenas a validação passa, você pode ter a ideia certa em uma implementação frágil.

Para entregar com confiança, você precisa das duas.

Perguntas frequentes

A verificação ou a validação vem primeiro?

A verificação começa primeiro e continua durante todo o desenvolvimento. Assim que existe código, ele pode ser comparado com a especificação.

A validação acontece quando há algo utilizável para exercitar contra necessidades reais.

Teste é o mesmo que validação?

Não.

Teste é um termo mais amplo. Ele pode incluir verificação e validação.

Exemplos:

Teste unitário: verificação
Schema check: verificação
Teste de contrato: verificação
Teste de aceitação: validação
Teste ponta a ponta: validação

Um software pode passar na verificação e falhar na validação?

Sim.

Isso acontece quando a implementação segue perfeitamente a especificação, mas a especificação resolve o problema errado.

Nesse caso, o produto está verificado, mas não validado.

Como isso se aplica a teste de contrato de API?

Teste de contrato é verificação.

Ele confirma que a API continua honrando o acordo documentado com os consumidores. Mas não confirma se esse acordo é o melhor para o uso real.

Essa segunda parte é validação.

Qual encontra mais bugs?

A verificação costuma encontrar mais defeitos em quantidade, porque roda continuamente e captura desvios pequenos cedo.

A validação tende a encontrar menos problemas, mas mais caros. Uma falha de validação geralmente indica requisito errado, design inadequado ou problema de produto.

Automação cobre os dois?

A automação cobre muito bem a verificação:

Schema checks
Testes de contrato
Asserções de status
Validação de headers
Testes em CI/CD

A validação é mais difícil de automatizar completamente porque depende de julgamento sobre uso real. Ainda assim, testes ponta a ponta automatizados cobrem uma parte importante dos fluxos principais.