Postman CLI vs Newman: Qual Runner de Linha de Comando Usar?

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 é:

1. exportar a coleção Postman como JSON;
2. exportar o ambiente como JSON, se necessário;
3. salvar esses arquivos no repositório;
4. instalar Newman no pipeline;
5. executar os testes;
6. 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:

1. a coleção fica no workspace Postman;
2. você cria uma chave de API do Postman;
3. salva essa chave como secret no provedor de CI;
4. autentica o CLI durante o job;
5. executa a coleção por ID ou referência;
6. 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.