Testes automatizados com pm.*: asserts, status codes e tempos de resposta

O que é o objeto pm e por que ele é a base dos testes no Postman

No Postman, os testes automatizados são escritos no script da aba Tests usando JavaScript e a API de runtime exposta pelo objeto pm. Pense no pm como a “ponte” entre o seu código de teste e o que aconteceu na requisição: ele dá acesso à resposta recebida, ao tempo de execução, a utilitários de asserção e ao registro de resultados no runner. A ideia central é transformar verificações manuais (olhar status, conferir campos, medir performance) em verificações repetíveis e executáveis em lote.

O padrão mais comum é agrupar verificações dentro de pm.test, que registra um teste com nome e executa uma função. Dentro dessa função, você usa pm.expect (estilo Chai BDD) ou outras helpers para validar condições. Quando uma condição falha, o teste é marcado como falho, e isso aparece no Runner/Newman com detalhes do erro.

pm.test("Status e tempo básicos", function () {  pm.response.to.have.status(200);  pm.expect(pm.response.responseTime).to.be.below(800);});

Estrutura mínima de um teste: pm.test e pm.expect

Um teste no Postman costuma seguir esta estrutura: dar um nome descritivo, executar validações e, se necessário, extrair informações para uso posterior. O nome do teste é importante porque ele vira documentação executável: quando algo falha no pipeline, você quer bater o olho e entender o que quebrou.

Boas práticas para nomes de testes

• Use nomes orientados a comportamento: “Retorna 200 ao buscar usuário existente”.
• Inclua a condição e o resultado esperado: “Tempo de resposta < 500ms”.
• Evite nomes genéricos: “Teste 1”, “OK”, “Validação”.

Exemplo de padrão de escrita

pm.test("Retorna 200 e JSON", function () {  pm.response.to.have.status(200);  pm.response.to.be.json;});

O pm.expect é usado para asserções mais flexíveis, como comparar números, strings, arrays, verificar existência de propriedades e padrões. Ele segue o estilo: pm.expect(valor).to.....

pm.test("Cabeçalho Content-Type indica JSON", function () {  pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");});

Asserções de status code: validando o contrato mais básico

Status code é a primeira linha de defesa em testes de API. Ele indica se a operação foi bem-sucedida, se houve erro do cliente, do servidor, ou se o recurso não existe. Em testes automatizados, você normalmente valida o status esperado para cada cenário e, em alguns casos, aceita uma faixa (por exemplo, qualquer 2xx) quando o contrato permite variação.

Continue em nosso aplicativo

Você poderá ouvir o audiobook com a tela desligada, ganhar gratuitamente o certificado deste curso e ainda ter acesso a outros 5.000 cursos online gratuitos.

ou continue lendo abaixo...

Baixar o aplicativo

Validando um status específico com pm.response.to.have.status

pm.test("Status 201 ao criar recurso", function () {  pm.response.to.have.status(201);});

Validando que o status está em uma lista permitida

Alguns endpoints podem retornar 200 ou 204 dependendo de haver corpo na resposta. Nesses casos, valide por lista para evitar falsos negativos.

pm.test("Status é 200 ou 204", function () {  pm.expect([200, 204]).to.include(pm.response.code);});

Validando faixa de status (2xx, 4xx)

pm.test("Retorna sucesso (2xx)", function () {  pm.expect(pm.response.code).to.be.within(200, 299);});

pm.test("Retorna erro de cliente (4xx)", function () {  pm.expect(pm.response.code).to.be.within(400, 499);});

Passo a passo prático: criando uma bateria de testes de status para um endpoint

Objetivo: padronizar testes de status para um endpoint de consulta (GET) e um endpoint de criação (POST), garantindo que o contrato básico está sendo respeitado.

• Passo 1: Abra a requisição no Postman e vá até a aba Tests.
• Passo 2: Adicione um teste para o status esperado (ex.: 200 no GET, 201 no POST).
• Passo 3: Adicione um teste para garantir que não houve erro de servidor (evita mascarar falhas intermitentes).
• Passo 4: Execute no Runner para validar repetibilidade.

// GET - contrato básico de sucesso
pm.test("GET retorna 200", function () {  pm.response.to.have.status(200);});

pm.test("GET não retorna 5xx", function () {  pm.expect(pm.response.code).to.not.be.within(500, 599);});

// POST - contrato básico de criação
pm.test("POST retorna 201", function () {  pm.response.to.have.status(201);});

pm.test("POST não retorna 5xx", function () {  pm.expect(pm.response.code).to.not.be.within(500, 599);});

Asserções de tempos de resposta: performance como critério de qualidade

Além de “funcionar”, uma API precisa responder dentro de limites aceitáveis. No Postman, o tempo de resposta pode ser acessado por pm.response.responseTime, normalmente em milissegundos. Testes de tempo não substituem testes de carga, mas são úteis para detectar regressões óbvias: um endpoint que antes respondia em 200ms e passou a responder em 2s pode ser sinal de problema de banco, cache, dependência externa ou mudança de query.

Validando um limite absoluto

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

Validando um intervalo aceitável

pm.test("Tempo de resposta entre 50ms e 1200ms", function () {  pm.expect(pm.response.responseTime).to.be.within(50, 1200);});

Cuidados ao testar tempo de resposta

• Evite limites agressivos em ambientes instáveis: rede, VPN e latência podem variar.
• Prefira limites por ambiente (ex.: local, homologação, produção) quando fizer sentido.
• Use o teste como “alarme” de regressão, não como benchmark definitivo.
• Se o endpoint depende de terceiros, considere limites mais folgados ou testes separados.

Passo a passo prático: criando um “guardrail” de performance no Runner

Objetivo: rodar uma collection e falhar rapidamente se um endpoint crítico ultrapassar o tempo máximo.

• Passo 1: Identifique as requisições críticas (login, busca principal, criação de pedido, etc.).
• Passo 2: Em cada uma, adicione um teste de tempo com um limite realista.
• Passo 3: Rode a collection no Runner com 5 a 10 iterações para observar variação.
• Passo 4: Ajuste o limite para reduzir falsos positivos, mantendo sensibilidade a regressões.

pm.test("Guardrail: resposta < 1000ms", function () {  pm.expect(pm.response.responseTime, "responseTime").to.be.below(1000);});

Asserções (asserts) com pm.expect: padrões úteis para QA

Asserções são as regras que você aplica para decidir se a resposta está correta. Com pm.expect, você valida desde condições simples (igualdade) até estruturas complexas (arrays, objetos, padrões de texto). Mesmo sem repetir conteúdo de leitura de JSON, é importante entender que você pode validar tanto metadados (status, headers, tempo) quanto dados do corpo, desde que você já tenha o valor em mãos.

Asserções de igualdade e comparação

pm.test("Campo total é maior que zero", function () {  const total = 10; // exemplo: valor já obtido do corpo  pm.expect(total).to.be.a("number");  pm.expect(total).to.be.above(0);});

Asserções de existência e nulidade

pm.test("ID existe e não é nulo", function () {  const id = "123"; // exemplo  pm.expect(id).to.exist;  pm.expect(id).to.not.be.null;  pm.expect(id).to.not.be.undefined;});

Asserções em arrays: tamanho e conteúdo

pm.test("Lista contém pelo menos 1 item", function () {  const items = ["a"]; // exemplo  pm.expect(items).to.be.an("array");  pm.expect(items.length).to.be.at.least(1);});

pm.test("Lista contém status 'ACTIVE'", function () {  const statuses = ["ACTIVE", "INACTIVE"]; // exemplo  pm.expect(statuses).to.include("ACTIVE");});

Asserções de string: padrões e conteúdo

pm.test("Mensagem contém palavra-chave", function () {  const msg = "User created successfully"; // exemplo  pm.expect(msg).to.be.a("string");  pm.expect(msg).to.match(/created/i);});

Asserções em headers: segurança e contrato

Validar headers é útil para garantir comportamento consistente (por exemplo, tipo de conteúdo) e alguns aspectos de segurança (por exemplo, não expor informações indevidas). Um exemplo comum é validar que o servidor retorna JSON quando prometido e que não há cache indevido em respostas sensíveis.

pm.test("Content-Type inclui application/json", function () {  pm.expect(pm.response.headers.get("Content-Type")).to.include("application/json");});

pm.test("Resposta sensível não deve ser cacheada", function () {  const cacheControl = pm.response.headers.get("Cache-Control") || "";  pm.expect(cacheControl.toLowerCase()).to.not.include("public");});

Combinando asserts: testes mais expressivos e com mensagens melhores

Um erro comum é colocar muitas verificações em um único teste com um nome genérico. Isso dificulta diagnosticar falhas. Em geral, prefira testes pequenos e específicos. Quando fizer sentido agrupar, adicione mensagens de erro para facilitar a leitura no relatório.

Exemplo: um teste por regra

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

pm.test("Tempo < 800ms", function () {  pm.expect(pm.response.responseTime, "responseTime").to.be.below(800);});

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

Exemplo: agrupando com mensagens detalhadas

pm.test("Contrato mínimo da resposta", function () {  pm.expect(pm.response.code, "status code").to.equal(200);  pm.expect(pm.response.responseTime, "responseTime").to.be.below(800);  pm.expect(pm.response.headers.get("Content-Type"), "Content-Type").to.include("application/json");});

Passo a passo prático: criando um template reutilizável de testes com pm.*

Objetivo: criar um bloco de testes que você consegue copiar para várias requisições e adaptar rapidamente. Isso acelera a criação de suites e reduz inconsistência entre endpoints.

• Passo 1: Na aba Tests, cole o template abaixo.
• Passo 2: Ajuste o status esperado e o limite de tempo conforme o endpoint.
• Passo 3: Se o endpoint puder retornar mais de um status de sucesso (ex.: 200/204), troque a validação para lista.
• Passo 4: Rode no Runner e verifique se os nomes dos testes estão claros no relatório.

// Template de testes básicos
const expectedStatus = 200;
const maxResponseTimeMs = 1000;

pm.test("Status esperado", function () {  pm.expect(pm.response.code, "status code").to.equal(expectedStatus);});

pm.test("Não é erro 5xx", function () {  pm.expect(pm.response.code, "status code").to.not.be.within(500, 599);});

pm.test("Tempo de resposta dentro do limite", function () {  pm.expect(pm.response.responseTime, "responseTime").to.be.below(maxResponseTimeMs);});

pm.test("Content-Type indica JSON", function () {  const ct = pm.response.headers.get("Content-Type") || "";  pm.expect(ct, "Content-Type").to.include("application/json");});

Erros comuns ao escrever asserts no Postman e como evitar

Confundir pm.response.code com pm.response.to.have.status

Ambos funcionam, mas têm estilos diferentes. pm.response.to.have.status(200) é mais “legível” e expressivo. pm.response.code é útil quando você quer fazer validações mais customizadas (listas, faixas, lógica condicional). Escolha um padrão e mantenha consistência na collection.

Testar tempo de resposta sem contexto

Um limite de 200ms pode falhar em ambientes de CI com rede compartilhada. Prefira limites que reflitam o objetivo do teste: detectar regressões grandes. Se você precisa de precisão, use ferramentas de performance dedicadas e mantenha no Postman apenas um guardrail.

Um único teste gigante para tudo

Quando um teste gigante falha, você perde o “sinal” do que exatamente quebrou. Para suites de QA, é comum separar em: status, headers, tempo, e regras de dados. Assim, o relatório aponta a categoria do problema.

Não colocar mensagens de erro

Adicionar um segundo argumento em pm.expect ajuda muito na leitura do relatório. Em vez de um erro genérico, você vê rapidamente qual campo ou métrica estava fora do esperado.

pm.test("Tempo abaixo do limite", function () {  pm.expect(pm.response.responseTime, "responseTime (ms)").to.be.below(900);});

Estratégias para status codes e tempos em cenários reais

Endpoints que podem retornar 200, 202 ou 204

Algumas APIs retornam 202 Accepted para processamento assíncrono, ou 204 No Content quando não há corpo. Em vez de “forçar” um único status, modele o teste para aceitar o conjunto permitido e, se necessário, validar comportamento adicional (por exemplo, presença/ausência de body) em testes separados.

pm.test("Status de sucesso permitido", function () {  pm.expect([200, 202, 204]).to.include(pm.response.code);});

Timeouts e respostas lentas intermitentes

Se você observa falhas intermitentes no teste de tempo, verifique se o limite está muito baixo ou se a requisição depende de fatores externos. Uma prática útil é registrar o tempo no console para análise durante a estabilização da suite.

pm.test("Log do tempo de resposta", function () {  console.log("responseTime(ms):", pm.response.responseTime);  pm.expect(pm.response.responseTime).to.be.below(1200);});

Separando testes de contrato e testes de performance

Para manter a suite confiável, trate status code e headers como “contrato” (devem ser estáveis) e tempo de resposta como “indicador” (pode variar). Isso ajuda a decidir o que deve falhar o build imediatamente e o que pode gerar alerta para investigação.