Qual a Diferença Entre Newman e Postman?

Newman e Postman não são concorrentes. Eles são duas metades de um mesmo fluxo de trabalho. Postman é o aplicativo de desktop onde você projeta requisições, escreve testes e explora APIs manualmente. Newman é a ferramenta de linha de comando que pega as coleções que você construiu no Postman e as executa sem a GUI. Se o Postman é a oficina, Newman é a máquina que executa seu trabalho concluído em um cronograma.

A confusão geralmente vem da pergunta “qual devo usar?” A resposta honesta é ambos, em diferentes estágios. Você cria no Postman porque uma interface gráfica torna isso rápido. Você executa no Newman porque um pipeline não pode clicar em botões. Este artigo explica a relação precisamente, mostra onde cada um se encaixa e descreve como integrar o Newman em um pipeline de CI/CD.

O que é Postman

Postman é uma plataforma gráfica de API. Você o instala como um aplicativo de desktop, cria requisições, as organiza em coleções e pastas, e anexa ambientes que contêm variáveis como URLs base e tokens. Após cada resposta, o Postman executa scripts de teste JavaScript que você escreve na aba Tests da requisição.

Um script de teste do Postman verifica a resposta:

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

pm.test("Order total is a positive number", function () {
    const body = pm.response.json();
    pm.expect(body.total).to.be.a("number");
    pm.expect(body.total).to.be.above(0);
});

Postman é feito para trabalho interativo. Um desenvolvedor depurando um novo endpoint envia requisições, inspeciona respostas, ajusta cabeçalhos e itera em segundos. Um engenheiro de QA transforma essas requisições em um conjunto de regressão salvo. As equipes compartilham workspaces para que todos trabalhem a partir da mesma coleção. Tudo isso se beneficia de uma interface visual. Nosso guia sobre como testar APIs com Postman aborda esse fluxo de trabalho em profundidade.

O que o Postman não foi feito para é a execução autônoma. Executar um conjunto significa abrir o aplicativo e clicar no Collection Runner. Isso é bom para uma pessoa em uma mesa. É inútil para um servidor de compilação.

O que é Newman

Newman é o executor de coleções de linha de comando oficial do Postman. É um pacote npm de código aberto, gratuito para usar, que executa exatamente os mesmos arquivos de coleção que o Postman produz. Você exporta uma coleção como um arquivo JSON, entrega ao Newman, e o Newman executa cada requisição e cada script de teste, então relata os resultados para o seu terminal.

Instale-o com npm:

npm install -g newman

Execute uma coleção:

newman run orders-api.postman_collection.json \
  --environment staging.postman_environment.json

Newman executa cada requisição, executa as mesmas asserções pm.test que o Postman faria e imprime um resumo. O detalhe chave é que Newman usa o mesmo motor de execução que o Postman, então uma coleção que passa na GUI se comporta de forma idêntica na linha de comando. Não há reescrita e nenhuma linguagem de teste separada.

Newman também sai com um código de status diferente de zero quando qualquer teste falha. Esse único comportamento é o que o torna valioso para a automação: um sistema de compilação lê esse código de saída e falha a compilação em uma asserção quebrada. Uma execução bem-sucedida sai com zero e o pipeline continua.

Comparação lado a lado

O arquivo JSON da coleção é a ponte entre eles. Você o constrói uma vez no Postman, e o Newman o executa para sempre na automação.

Como o Newman se encaixa no CI/CD

Newman existe principalmente para integrar testes de API na integração contínua. O padrão é consistente entre os provedores. Você faz commit dos arquivos de coleção e ambiente exportados para seu repositório, instala o Newman no pipeline, o executa e permite que o código de saída barre a compilação.

Aqui está o fluxo de trabalho em etapas numeradas:

1. Exportar do Postman. No Postman, exporte sua coleção e seu ambiente como arquivos JSON.
2. Fazer commit para o repositório. Armazene-os junto ao seu código para que sejam versionados com a API.
3. Instalar Newman no pipeline. Adicione npm install -g newman ao job de CI, ou use a imagem Docker postman/newman.
4. Executar a coleção. Chame newman run com os arquivos de coleção e ambiente.
5. Controlar pelo código de saída. Se algum teste falhar, o Newman sai com um valor diferente de zero e o provedor de CI marca a compilação como falha.

Uma etapa do GitHub Actions se parece com isto:

- name: Run API tests
  run: |
    npm install -g newman
    newman run orders-api.postman_collection.json \
      --environment staging.postman_environment.json \
      --reporters cli,junit \
      --reporter-junit-export results.xml

A flag --reporters vale a pena conhecer. Newman vem com reporters integrados para CLI e JUnit XML, e reporters da comunidade adicionam saída HTML e mais. O JUnit XML, em particular, permite que os painéis de CI exibam os resultados dos testes nativamente. Para um guia completo, veja nosso guia sobre automação de testes de API em CI/CD e as especificidades da automação de testes de API com GitHub Actions.

Opções úteis de linha de comando do Newman

Newman possui um conjunto de flags que lidam com as arestas de execuções automatizadas. Conhecer algumas delas faz a diferença entre um trabalho frágil e um confiável.

A flag --iteration-data aponta o Newman para um arquivo CSV ou JSON e executa toda a coleção uma vez por linha, substituindo os valores da linha como variáveis. É assim que você orienta uma execução do Newman por dados: uma coleção, muitas entradas. A flag --iteration-count simplesmente repete a coleção um número fixo de vezes.

A flag --bail instrui o Newman a parar na primeira falha em vez de executar o restante da coleção. Em um pipeline de feedback rápido, isso é geralmente o que você deseja, já que uma única requisição quebrada geralmente significa que a compilação já irá falhar. A flag --timeout-request limita o tempo que qualquer requisição individual pode levar, o que protege o job de travar em um serviço que não responde.

A flag --delay-request insere uma pausa entre as requisições, útil quando uma API impõe limites de taxa. E --folder permite que você execute apenas uma pasta nomeada dentro de uma coleção, para que um job de teste de fumaça possa executar um pequeno subconjunto enquanto o job de regressão completo executa tudo. Nenhuma dessas opções existe no Collection Runner da GUI do Postman na mesma forma scriptável, e juntas elas são o motivo pelo qual Newman é a escolha prática para execução autônoma.

Erros comuns ao migrar do Postman para o Newman

Alguns problemas surgem repetidamente quando as equipes levam uma coleção da GUI para o Newman pela primeira vez. O mais comum são os valores codificados. Uma requisição que funcionou no Postman porque uma variável estava configurada no ambiente ativo falhará no Newman se esse arquivo de ambiente não for passado com --environment. Sempre exporte e forneça o ambiente explicitamente.

O segundo é depender da nuvem do Postman. Coleções que referenciam variáveis sincronizadas na nuvem ou usam recursos vinculados a uma sessão do Postman logada podem não se comportar da mesma forma quando executadas a partir de um arquivo JSON simples. Teste o arquivo exportado localmente com o Newman antes de confiar nele no CI.

O terceiro é esquecer que arquivos exportados ficam desatualizados. O JSON da coleção no seu repositório é um instantâneo. Se alguém editar a coleção no Postman e não reexportar, o pipeline continua executando a versão antiga. As equipes resolvem isso com disciplina, tratando a exportação como um commit deliberado, ou migrando para uma ferramenta onde a definição do teste e o executor são a mesma coisa.

Quando usar cada um

Use o Postman quando um humano estiver realizando o trabalho. Projetar uma nova API, depurar uma chamada que falha, explorar um serviço de terceiros, construir e refinar um conjunto de testes: tudo isso é interativo e pertence à GUI.

Use o Newman quando nenhum humano estiver presente. Executar o conjunto em cada pull request, em um cronograma noturno ou como um teste de fumaça pós-implantação: tudo isso precisa de uma ferramenta que execute a partir de um script e relate através de um código de saída.

Na prática, a fronteira é “autoria versus execução”. Você não escolherá um em detrimento do outro. Você usará o Postman para criar e o Newman para automatizar, e o arquivo da coleção levará seu trabalho entre eles. Se você preferir não manter um executor separado, nosso guia sobre executar coleções Postman em CI sem Newman aborda outras opções.

Uma alternativa unificada: Apidog

Manter uma configuração Postman-mais-Newman significa exportar coleções, manter arquivos JSON sincronizados e gerenciar um executor separado. O Apidog une tudo isso em uma única plataforma. Você projeta APIs, depura requisições e constrói cenários de teste automatizados com asserções visuais no mesmo aplicativo, e então executa esses cenários em CI/CD com o executor de linha de comando integrado. Não há etapa de exportação e sincronização porque as definições de teste e o motor de execução vivem juntos.

O Apidog também abrange design de API, servidores mock e testes de desempenho no mesmo workspace, de modo que os testes funcionais que você cria são os mesmos que seu pipeline executa. Você pode baixar o Apidog e usar seus recursos de teste gratuitamente. Para uma comparação de ferramentas neste espaço, veja nossa lista das melhores alternativas ao Postman para testes de API.

Perguntas frequentes

O Newman é um substituto para o Postman?

Não. O Newman não pode criar ou editar coleções; ele apenas as executa. Você ainda precisa do Postman, ou de outra ferramenta, para criar a coleção e escrever os scripts de teste. O trabalho do Newman é executar esse trabalho concluído sem interface. Eles são complementares, não intercambiáveis.

O Newman custa dinheiro?

Não. O Newman é de código aberto e totalmente gratuito. Ele é distribuído como um pacote npm. O Postman possui uma camada gratuita mais planos pagos para equipes maiores, mas o Newman em si não tem custo, independentemente de como você o use.

Meus testes do Postman se comportarão da mesma forma no Newman?

Sim. O Newman usa o mesmo motor de execução do Postman, então as asserções pm.test e a lógica de requisição funcionam de forma idêntica. Uma coleção que passa no Postman Collection Runner produzirá os mesmos resultados no Newman, o que o torna seguro para CI.

Como o Newman relata falhas de teste?

O Newman imprime um resumo no terminal e sai com um código de status diferente de zero quando qualquer teste falha. Esse código de saída é como os sistemas de CI detectam falhas. O Newman também suporta reporters, incluindo JUnit XML e HTML, para que os resultados possam alimentar dashboards e relatórios de build.

Posso executar o Newman sem instalar o Node.js?

O Newman é um pacote npm, portanto, uma instalação direta requer Node.js. Para evitar isso, use a imagem Docker oficial postman/newman, que inclui tudo. A abordagem Docker é comum em ambientes de CI onde você não deseja gerenciar um tempo de execução Node.js no job de build.