Postman é uma das ferramentas mais usadas para enviar requisições HTTP e verificar o comportamento de uma API. Começou como uma extensão de navegador e evoluiu para um aplicativo de desktop completo que lida com tudo, desde uma requisição GET rápida até conjuntos de testes roteirizados que rodam em CI. Se você constrói ou consome APIs, você quase certamente o encontrará.
Este guia percorre o processo de teste de uma API no Postman da maneira que você faria no dia a dia. Você enviará uma requisição, inspecionará a resposta, escreverá asserções na aba Testes, configurará ambientes para poder alternar entre staging e produção, e executará uma coleção inteira de uma vez com o Collection Runner. Os exemplos usam uma API pública para que você possa acompanhar sem precisar configurar nada primeiro.
Configure o Postman e envie sua primeira requisição
Baixe o Postman no site oficial e instale o aplicativo para desktop. Você pode usá-lo sem uma conta para trabalho local, embora o login sincronize suas coleções entre dispositivos. Abra o aplicativo e clique no botão Novo, então escolha Requisição HTTP.
Uma requisição precisa de no mínimo três coisas: um método, uma URL e, às vezes, um corpo (body). Selecione GET no menu suspenso de métodos e insira um endpoint real. O serviço JSONPlaceholder é útil para a prática:
GET https://jsonplaceholder.typicode.com/users/1
Clique em Enviar. O painel de resposta será preenchido com o corpo (body), o código de status (200 OK), o tempo de resposta e o tamanho. Alterne a visualização do corpo entre Pretty, Raw e Preview para ver o JSON formatado ou como o servidor o enviou.
Para uma requisição POST, mude o método, abra a aba Corpo (ou Body), escolha raw e selecione JSON no menu suspenso de formato. Cole um payload como este:
{
"name": "Maria Chen",
"email": "maria.chen@example.com"
}
Cabeçalhos como Content-Type: application/json são adicionados automaticamente para você quando você escolhe o tipo de corpo JSON. A aba Cabeçalhos (ou Headers) permite que você adicione qualquer outra coisa que a API precise, como um cabeçalho Authorization. Se você é novo em relação a quais códigos de resposta esperar, o guia sobre códigos de status HTTP que APIs REST devem usar é uma referência útil.
Organize requisições em coleções
Uma única requisição é suficiente para uma verificação rápida. Testes reais significam muitas requisições que pertencem juntas: criar um usuário, buscar esse usuário, atualizá-lo, excluí-lo. O Postman agrupa estas em coleções.Clique em Coleções na barra lateral, então no ícone + para criar uma. Dê um nome concreto como "Testes de fumaça da API de Usuários". Salve cada requisição na coleção com Ctrl/Cmd + S e dê um nome claro a ela. Você pode aninhar pastas dentro de uma coleção para separar, por exemplo, requisições de autenticação de requisições de recursos.
As coleções também são a unidade que você compartilha. Exporte uma como um arquivo JSON, ou compartilhe um link se você sincronizar com a nuvem. Colegas de equipe a importam e terão exatamente as mesmas requisições que você. Esta é a base para todo o resto, porque o Collection Runner e os testes automatizados operam em coleções, e não em requisições avulsas.
Uma coleção também pode carregar comportamentos compartilhados. O Postman permite que você anexe scripts no nível da coleção ou da pasta, não apenas em uma única requisição. Um script de pré-requisição (pre-request script) na coleção é executado antes de cada requisição dentro dela, o que é útil para atualizar um token ou marcar um timestamp. Um script de teste no nível da coleção é executado após cada requisição, o que é útil para uma asserção que você deseja em todos os lugares, como "o tempo de resposta é razoável". Definir isso uma vez mantém suas requisições individuais focadas no que é exclusivo delas.
Escreva testes na aba Testes
Enviar uma requisição informa o que foi recebido. Um teste informa se o que foi recebido está correto, automaticamente, todas as vezes. O Postman executa JavaScript na área de Scripts de uma requisição (versões mais antigas chamavam isso de aba Testes) após a chegada da resposta.
O Postman expõe um objeto pm para escrever asserções. O padrão principal é pm.test(name, callback), onde o callback lança um erro se uma expectativa falhar. Aqui estão as asserções que você usará constantemente:
// 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 cabeçalho
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, então pm.expect suporta .to.eql, .to.include, .to.be.above, e o restante. Clique em Enviar e os resultados aparecerão na aba Resultados do Teste, com cada teste em verde ou vermelho.
Alguns hábitos mantêm os testes úteis. Nomeie cada bloco pm.test de acordo com o comportamento que ele verifica, e não o endpoint, para que uma mensagem de falha seja lida como uma frase. Verifique as coisas que realmente quebrariam um consumidor da API: o código de status, a estrutura do corpo (body) e os campos dos quais um cliente depende. Evite fazer asserções sobre valores que você não controla, como um timestamp gerado pelo servidor, pois isso produz falhas intermitentes que "treinam" as pessoas a ignorar o vermelho. O Postman também oferece um painel de Snippets ao lado do editor com asserções prontas que você pode clicar para inserir, que é a maneira mais rápida de aprender a API pm. Se você quiser um olhar mais aprofundado sobre o design de asserções, veja a análise de asserções de API e como escrevê-las bem. Para a ideia mais ampla de estruturar verificações em casos nomeados, o guia de exemplo de caso de teste de API vale a pena ser lido em conjunto com este.
Use ambientes e variáveis
Programar diretamente (hardcoding) https://api.staging.example.com em cada requisição é doloroso no momento em que você precisa apontar para a produção. Ambientes resolvem isso. Um ambiente é um conjunto nomeado de variáveis.
Clique no ícone de ambientes na barra lateral e crie um chamado "Staging". Adicione uma variável base_url com o valor https://jsonplaceholder.typicode.com. Crie um segundo ambiente chamado "Production" com uma base_url diferente. Agora, referencie a variável em suas requisições usando chaves duplas:
GET {{base_url}}/users/1
Selecione o ambiente ativo no menu suspenso no canto superior direito, e cada requisição usando {{base_url}} será alterada junto com ele.
Variáveis também transportam dados entre requisições. Uma requisição de login pode capturar um token de sua resposta e armazená-lo para ser usado em requisições posteriores:
pm.test("Salva o token de autenticação", function () {
const token = pm.response.json().token;
pm.environment.set("auth_token", token);
});
Qualquer requisição posterior pode então enviar Authorization: Bearer {{auth_token}}. Essa encadeamento é como você testa fluxos que dependem de estado, como criar um recurso e depois verificar se ele existe.
O Postman possui dois escopos de variáveis relacionados que vale a pena conhecer. Variáveis de ambiente pertencem ao ambiente selecionado e mudam quando você troca de ambiente. Variáveis de coleção pertencem a uma coleção independentemente do ambiente, o que é adequado para valores que são constantes para aquela API. Existem também variáveis globais, que se aplicam em todos os lugares, e variáveis locais de curta duração que existem apenas para uma execução. Escolher o escopo certo mantém um valor onde ele deve estar e evita surpresas ao mudar de alvos.
Execute uma coleção inteira com o Collection Runner
Clicar em "Enviar" em cada requisição rapidamente se torna tedioso. O Collection Runner executa cada requisição em uma coleção em ordem, executa todos os seus testes e fornece um resumo de aprovação/reprovação.
Abra uma coleção, clique no botão Executar (ou no menu de três pontos, depois em Executar coleção). O runner mostra suas requisições em sequência. Escolha o ambiente, defina quantas iterações executar e, opcionalmente, anexe um arquivo de dados. Clique em Executar e o Postman dispara cada requisição, de cima para baixo, executando os testes de cada requisição.
A página de resultados lista cada asserção em todas as requisições, com totais para aprovados e reprovados. Esta é sua verificação de regressão. Execute-a após um deploy e você saberá em segundos se a API ainda se comporta como esperado. O runner também mantém um histórico de execuções anteriores, para que você possa comparar o resultado de hoje com o de ontem e identificar quando um conjunto de testes que antes estava verde começou a falhar.
A ordem importa no runner. Como as requisições são executadas de cima para baixo, você pode colocar uma requisição de login primeiro para que ela preencha um auth_token, e então permitir que todas as requisições abaixo usem esse token. O mesmo se aplica à configuração e limpeza: crie um recurso próximo ao início, utilize-o no meio, exclua-o no final. Uma coleção bem ordenada efetivamente roteiriza uma jornada completa do usuário.
Para testes orientados por dados (data-driven testing), anexe um arquivo CSV ou JSON no runner. Cada linha se torna uma iteração, e você referencia as colunas como variáveis como {{username}}. Isso permite que uma requisição teste dezenas de combinações de entrada sem duplicar a requisição. Um endpoint de login, por exemplo, pode ser acessado com uma linha de credenciais válidas e várias linhas de credenciais inválidas, cada linha afirmando o código de status que espera. O artigo sobre testes de API orientados a dados com CSV e JSON aborda o padrão em detalhes. Para executar a mesma coleção em CI sem a GUI, o Postman fornece a ferramenta de linha de comando Newman, descrita na comparação Newman versus Postman.
Onde o Postman se torna pesado, e o que considerar
O Postman é excelente para testes exploratórios e suítes de teste de pequeno a médio porte. Dois pontos de atrito surgem à medida que os projetos crescem. Primeiro, as asserções são escritas em JavaScript, então não-desenvolvedores e profissionais de QA que preferem uma abordagem visual têm uma curva de aprendizado. Segundo, o Postman mantém o design da API, testes, mocking e documentação em lugares separados, o que significa que seus dados de teste e seu contrato de API podem se desalinhar.
Apidog é uma plataforma de API completa que aborda ambos os pontos. Ela importa coleções do Postman diretamente, então a migração não é uma reescrita. As asserções podem ser construídas visualmente sem código, enquanto ainda permite scripts quando você precisar deles. Como o design, depuração, mocking, testes e documentação compartilham uma única fonte de verdade, seus testes permanecem alinhados com a especificação real da API. Se você está avaliando opções, a lista de alternativas ao Postman para testes de API apresenta as compensações. Você pode baixar o Apidog e importar uma coleção existente para comparar diretamente.
Nada disso significa que você deve abandonar o Postman. Ele continua sendo uma escolha sólida, especialmente para verificações rápidas e equipes que já investem nele. O objetivo é saber onde cada ferramenta se encaixa.
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, pelo menos um pouco. A aba Testes do Postman executa JavaScript e usa o objeto pm. Os padrões são simples e você pode copiá-los do painel de snippets integrado do Postman, mas ainda é JavaScript. Se você deseja um construtor de asserções visuais sem código, uma plataforma dedicada como o Apidog lida com isso.
Qual é a diferença entre uma coleção do Postman e um ambiente?
Uma coleção é um conjunto de requisições agrupadas, frequentemente com seus testes. Um ambiente é um conjunto nomeado de variáveis, como base_url ou auth_token. Coleções contêm o que você envia. Ambientes contêm os valores que mudam entre staging, produção e local. Você aponta uma coleção para diferentes ambientes para testar as mesmas requisições contra diferentes servidores.
Como executo testes do Postman automaticamente em CI?
Use o Newman, o executor de linha de comando do Postman. Exporte sua coleção e ambiente, então execute newman run collection.json -e environment.json. O Newman sai com um código diferente de zero se algum teste falhar, o que é o que seu pipeline de CI verifica. O guia sobre automação de testes de API em CI/CD explica como integrar isso em um pipeline.
O Postman pode testar mais do que APIs REST?
Sim. O Postman moderno suporta requisições GraphQL, gRPC, WebSocket e SOAP, além de HTTP e REST. A aba Testes e as asserções funcionam na maioria deles, embora a configuração exata da requisição difira por protocolo.
Quantas asserções uma requisição deve ter?
O suficiente para confirmar que a resposta está correta, não tantas a ponto de uma única mudança quebrar uma dúzia de testes. Uma base comum é o código de status, o tempo de resposta e os dois ou três campos que importam para aquele endpoint. Mantenha cada bloco pm.test focado em uma única expectativa para que uma falha indique exatamente o que quebrou.