DEV Community

Cover image for Como Testar APIs com Postman: Um Guia Prático
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Testar APIs com Postman: Um Guia Prático

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:

  1. Abra o Postman.
  2. Clique em New.
  3. Escolha HTTP Request.
  4. Selecione o método GET.
  5. Informe a URL: 
GET https://jsonplaceholder.typicode.com/users/1
Enter fullscreen mode Exit fullscreen mode

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:

  1. Altere o método para POST.
  2. Abra a aba Body.
  3. Selecione raw.
  4. Escolha JSON no seletor de formato.
  5. Cole um payload: 
{
  "name": "Maria Chen",
  "email": "maria.chen@example.com"
}
Enter fullscreen mode Exit fullscreen mode

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

Content-Type: application/json
Enter fullscreen mode Exit fullscreen mode

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

Authorization: Bearer {{auth_token}}
Enter fullscreen mode Exit fullscreen mode

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:

  1. criar um usuário;
  2. buscar o usuário;
  3. atualizar o usuário;
  4. excluir o usuário.

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

Para criar uma coleção:

  1. Clique em Collections na barra lateral.
  2. Clique no ícone +.
  3. Dê um nome descritivo, como Testes de fumaça da API de Usuários.
  4. Salve cada requisição com Ctrl/Cmd + S.
  5. 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
Enter fullscreen mode Exit fullscreen mode

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);
});
Enter fullscreen mode Exit fullscreen mode

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
});
Enter fullscreen mode Exit fullscreen mode

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");
});
Enter fullscreen mode Exit fullscreen mode

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);
Enter fullscreen mode Exit fullscreen mode

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;
});
Enter fullscreen mode Exit fullscreen mode

Evite nomes genéricos:

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

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
Enter fullscreen mode Exit fullscreen mode

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

  1. Abra a área de ambientes no Postman.
  2. Crie um ambiente chamado Staging.
  3. Adicione a variável: 
base_url = https://jsonplaceholder.typicode.com
Enter fullscreen mode Exit fullscreen mode
  1. Crie outro ambiente chamado Production com outro valor de base_url.

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

GET {{base_url}}/users/1
Enter fullscreen mode Exit fullscreen mode

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);
});
Enter fullscreen mode Exit fullscreen mode

Depois, outras requisições podem usar:

Authorization: Bearer {{auth_token}}
Enter fullscreen mode Exit fullscreen mode

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

  1. fazer login;
  2. salvar token;
  3. criar recurso;
  4. salvar ID criado;
  5. buscar recurso pelo ID;
  6. 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);
});
Enter fullscreen mode Exit fullscreen mode

Uso posterior:

GET {{base_url}}/users/{{user_id}}
Enter fullscreen mode Exit fullscreen mode

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:

  1. Abra a coleção.
  2. Clique em Run ou no menu de três pontos e escolha Run collection.
  3. Selecione o ambiente.
  4. Defina o número de iterações.
  5. Opcionalmente, anexe um arquivo de dados CSV ou JSON.
  6. 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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

{
  "email": "{{email}}",
  "password": "{{password}}"
}
Enter fullscreen mode Exit fullscreen mode

No teste, valide o status esperado:

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

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
Enter fullscreen mode Exit fullscreen mode

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.

Top comments (0)