Apidog CLI vs Newman: Como Rodar Testes de API na CI (2026)

Seus testes de API passam no seu laptop. A pergunta mais difícil é se eles rodam em cada pull request, cada merge e cada build noturno sem que um humano precise clicar em nada. Essa tarefa pertence a um executor de linha de comando. Ele pega os testes que você já escreveu, os executa sem interface gráfica (headless) dentro do seu pipeline, sai com um código de status que sua CI pode ler e escreve um relatório que seu painel pode analisar. Sem GUI, sem etapa manual, sem desculpas para pular a execução.

Por anos, a resposta padrão para essa necessidade tem sido o Newman, o executor de coleção de linha de comando de código aberto do Postman. É uma ferramenta sólida e bem compreendida, e muitas equipes ainda a buscam primeiro. Mas se você cria seus testes no Apidog em vez do Postman, você tem uma segunda opção: o Apidog CLI, que executa os mesmos cenários de teste que você constrói visualmente no aplicativo, sem interface gráfica (headless) na CI. Este artigo é uma comparação honesta, em nível de comando, dos dois. Ele aborda o que o Newman faz bem, onde o Apidog CLI se encaixa e como cada um se comporta quando conectado a um pipeline real.

TL;DR

• Newman (`newman`, instalado via `npm install -g newman`) executa um arquivo JSON de coleção Postman exportado. É de código aberto, gratuito e lê uma coleção mais um arquivo de ambiente do disco ou de uma URL. Ele suporta ambientes, arquivos de dados, contagens de iteração e relatórios JUnit/JSON/HTML, e sai com um código diferente de zero quando um teste falha.
• Apidog CLI (`apidog-cli`, binário `apidog`) executa os cenários de teste que você projeta no aplicativo Apidog, buscados por ID usando um token de acesso. Você não exporta nada ou mantém um arquivo JSON manualmente; o cenário visual é o teste, e o CLI o executa exatamente como o aplicativo faria.
• Ambos se conectam a GitHub Actions, GitLab CI, Jenkins e qualquer coisa com Node.js. Ambos falham o build em caso de teste falho. O XML JUnit é o que se conecta aos painéis de CI em ambos os lados.
• Escolha **Newman** quando seus testes já existirem como coleções Postman e você quiser um executor gratuito, amigável ao repositório e sem a necessidade de uma nova conta.
• Escolha **Apidog CLI** quando você quiser autoria visual, encadeamento de requisições, gerenciamento de ambiente e execuções orientadas por dados que permaneçam em sincronia com o mesmo cenário que sua equipe depura todos os dias.

O problema real: testes que existem mas nunca rodam

Um teste que você executa manualmente é um teste que se deteriora. Alguém o construiu, ele passou uma vez, e então permaneceu intocado enquanto a API mudava por baixo. Mais testes não resolvem isso. Testes que são executados automaticamente a cada alteração sim, porque eles produzem um sinal de aprovação ou falha sobre o qual seu pipeline pode agir.

Um executor CLI fecha essa lacuna. Para ser útil na CI, ele precisa fazer três coisas: executar sem GUI, sair com código diferente de zero quando algo falha para que o build fique vermelho, e escrever um relatório legível por máquina para que os revisores possam ver o que quebrou. Newman e Apidog CLI cumprem esses requisitos com louvor. Onde eles diferem é antes do comando de execução, em como o teste foi escrito e onde ele vive. Se você está configurando a CI do zero, os padrões mais amplos em como automatizar testes de API em CI/CD combinam bem com esta comparação. Aqui, nos mantemos focados nos dois executores.

O que o Newman faz bem

O Newman conquistou seu lugar. É o companheiro oficial de código aberto do Postman, e para equipes cujos testes já existem como coleções Postman, é o caminho mais direto de “testes na minha máquina” para “testes na CI”. Vale a pena destacar seus pontos fortes claramente antes de qualquer comparação.

É gratuito e de código aberto. Você o instala via npm e o executa em qualquer lugar onde o Node.js funcione, sem licença separada para o próprio executor. Sua coleção é um arquivo JSON portátil que você pode fazer commit em um repositório, armazenar como um artefato de build ou buscar de uma URL. Essa portabilidade é real e significa que o Newman se encaixa em quase qualquer pipeline sem atrito.

Ele reutiliza o que você já construiu. Se sua equipe escreve requisições, scripts de pré-requisição e asserções de teste no Postman, o Newman executa essas mesmas coleções sem alterações. Não há reescrita. Os scripts que você escreveu no editor do Postman são executados da mesma forma na execução headless, o que mantém a curva de aprendizado baixa para usuários do Postman.

A instalação é um comando:

npm install -g newman

O binário é `newman`. Você executa uma coleção exportada apontando-o para o arquivo JSON, geralmente com um arquivo de ambiente ao lado:

newman run api-tests.postman_collection.json -e staging.postman_environment.json

Esse é o ciclo principal. Exporte a coleção do Postman, faça commit do JSON e execute-a. O Newman lê as requisições e asserções do arquivo e as executa em ordem. Para o caminho de configuração completo, o próprio guia do Apidog sobre como instalar o Newman e executar coleções Postman cobre o fluxo de exportação e execução passo a passo.

O Newman também suporta os itens essenciais de CI que você esperaria. As execuções orientadas por dados vêm de um arquivo CSV ou JSON:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -d users.csv \
  -n 5

Aqui, `-d` fornece o arquivo de dados e `-n` define a contagem de iterações, de modo que a coleção é executada uma vez por linha ou um número fixo de vezes. Estes são os mesmos primitivos que qualquer executor sério precisa, e o Newman os possui há anos.

Onde o Newman começa a custar caro

Os pontos fortes acima são honestos, mas os compromissos também o são, e eles aparecem na manutenção diária, e não em qualquer comando único.

O maior deles é a etapa de exportação. Uma coleção Postman na CI é um snapshot. Você cria e depura no aplicativo Postman, e depois exporta um arquivo JSON para executar sem interface gráfica (headless). No momento em que alguém edita uma requisição no aplicativo e esquece de re-exportar, sua coleção commitada se desvia da fonte da verdade. A execução da CI continua passando contra uma definição antiga enquanto a API real avançou. Nada nas ferramentas força os dois a se sincronizarem novamente; a responsabilidade recai sobre quem se lembra de exportar.

A criação de scripts é o outro ponto. A lógica de teste do Postman reside em trechos de JavaScript anexados a cada requisição, e esses scripts são onde o encadeamento, a extração de variáveis e as asserções acontecem. Isso é flexível, mas significa que seu conjunto de testes é um monte de pequenos scripts para escrever, depurar e manter manualmente. À medida que os cenários crescem, o mesmo acontece com a superfície de scripts que você possui. Isso faz parte de um padrão mais amplo que as equipes encontram à medida que as coleções escalam, o que abordamos em Restrições do Postman Collection Runner e como contorná-las.

Nada disso torna o Newman uma ferramenta ruim. Isso o torna um executor cujas ergonomias estão ligadas ao modelo de autoria do Postman: scripts mais uma etapa de exportação. Se esse modelo se encaixa na sua equipe, o Newman é bom. Se a dança de exportar e sincronizar é a parte que continua quebrando, é exatamente aí que um executor diferente ajuda.

O que o Apidog CLI faz de diferente

O Apidog segue um caminho diferente para o mesmo pipeline. Você constrói testes visualmente no aplicativo Apidog. Você encadeia requisições em um cenário de teste, adiciona asserções em um editor sem código, extrai um valor de uma resposta para a próxima requisição e repete tudo sobre um arquivo de dados. O CLI é o executor headless para esses cenários. Ele não tem um formato de arquivo separado e nada a exportar. Ele busca o cenário que você nomeia por ID do seu projeto Apidog e o executa exatamente como o aplicativo faria.

Isso remove o problema de desvio. O cenário no projeto é o teste. Não há um snapshot exportado para sair de sincronia, porque o CLI executa o cenário ao vivo, e não uma cópia dele. Você o cria uma vez em um construtor visual que gerencia o encadeamento de requisições e asserções para você, então o mesmo cenário é executado na CI. O ciclo rápido de autoria e o ciclo de automação compartilham uma única fonte da verdade.

A instalação é um comando npm:

npm install -g apidog-cli

O binário é `apidog`. Uma execução típica nomeia um cenário por ID, escolhe um ambiente e se autentica com um token de acesso:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit

Você não digita esses IDs manualmente. Abra o cenário de teste no Apidog, vá para a aba CI/CD, gere um token de acesso e o Apidog construirá o comando completo para você com o ID do cenário e o ID do ambiente já preenchidos. Você o copia uma vez, depois move o token para um segredo de CI e o referencia como `$APIDOG_ACCESS_TOKEN`. Se você não tem certeza de quais flags sua versão instalada suporta, execute `apidog run --help` e ele imprimirá as opções exatas disponíveis.

O modelo baseado em token, de busca por ID, é a diferença mais clara em relação ao Newman. O Newman lê um arquivo de coleção do disco; o Apidog CLI acessa um projeto pela rede, autenticado, e executa o cenário ali armazenado. Nenhum dos dois está errado. Eles se adequam a diferentes configurações de equipe, e a escolha é principalmente sobre se você quer que o teste viva como um arquivo exportado ou como um cenário ao vivo em um espaço de trabalho compartilhado.

Lado a lado

Duas coisas se destacam. Primeiro, ambos os executores cobrem os mesmos itens essenciais da CI: seleção de ambiente, iteração orientada por dados, os formatos de relatório importantes e uma saída não-zero em caso de falha. Os nomes das flags são até próximos o suficiente para que a memória muscular seja transferida (`-e`, `-d`, `-n`, `-r`). Segundo, a verdadeira divisão não é a capacidade bruta. É onde o teste vive e como você o escreveu. O Newman executa uma coleção exportada e criada com scripts. O Apidog executa um cenário visual ao vivo por referência. A versão mais aprofundada desta comparação, enquadrada em torno dos dois executores do mundo Postman, está em Postman CLI vs Newman, se você quiser essa perspectiva também.

Relatores e códigos de saída: as partes que a CI realmente lê

Um executor conquista seu lugar em um pipeline através de dois comportamentos: o relatório que ele escreve e o código de saída que ele retorna. Acertando isso, o resto é apenas conexão.

O Newman seleciona os relatores com a flag `-r` e uma lista separada por vírgulas. JUnit e JSON vêm na caixa; o relator HTML é o complemento mais comum:

newman run api-tests.postman_collection.json \
  -e staging.postman_environment.json \
  -r cli,junit \
  --reporter-junit-export ./results/junit.xml

O XML JUnit é o que o seu painel de CI analisa, transformando-o em uma árvore de aprovação ou falha. A flag `--bail` do Newman interrompe a execução após a primeira falha, o que mantém o feedback rápido em um teste de fumaça. Sem ela, a execução é concluída e relata todas as falhas de uma vez.

O Apidog CLI usa a mesma flag `-r` separada por vírgulas e escreve tudo em um único diretório de saída:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 \
  -r html,junit --out-dir ./apidog-reports

Sua flag `--on-error` define o comportamento no meio do cenário: `end` para na primeira falha e é o padrão, `continue` executa cada etapa para que você colete todas as falhas em um único relatório, e `ignore` pula uma etapa conhecida por ser instável. De qualquer forma, a execução termina com código diferente de zero se algo falhar.

O contrato do código de saída é o mesmo em ambos os lados, e é a parte crucial. Quando uma asserção falha, o executor sai com um código diferente de zero. A CI lê esse código, marca a etapa como falha, falha o trabalho e bloqueia o merge ou deploy. Você não configura nada extra. A única armadilha, idêntica para ambos, é engolir o código de saída: envolver a execução em um pipeline de shell ou adicionar `|| true` e a saída não-zero é ignorada, de modo que o portão para de funcionar silenciosamente. Não faça isso. Para um contexto mais amplo sobre formatos de relatório, testes de API orientados por dados com CSV ou JSON mostra como o relatório se conecta aos dados de iteração.

Newman no GitHub Actions

Como a coleção é um arquivo exportado no repositório, o workflow é curto. Faça o checkout do código, instale o Newman, execute a coleção, faça o upload do relatório mesmo em caso de falha.

name: Testes de API

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Instalar Newman
        run: npm install -g newman

      - name: Executar testes de API
        run: |
          newman run ./tests/api-tests.postman_collection.json \
            -e ./tests/staging.postman_environment.json \
            -r cli,junit \
            --reporter-junit-export ./results/junit.xml

      - name: Upload do relatório
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: relatorio-newman
          path: ./results

Nenhum segredo é necessário se os arquivos de coleção e ambiente estiverem commitados no repositório. A linha `if: always()` mantém o upload do relatório em execução mesmo quando os testes falham, que é exatamente quando você quer lê-lo. O custo que você assume é a etapa de exportação que produziu esses arquivos JSON em primeiro lugar, e a lembrança de atualizá-los quando a API muda.

Apidog CLI no GitHub Actions

O workflow do Apidog tem a mesma estrutura, com uma alteração: o token de acesso vem dos segredos do repositório, e você seleciona o cenário por ID em vez de apontar para um arquivo.

name: Testes de API

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Configurar Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Instalar Apidog CLI
        run: npm install -g apidog-cli

      - name: Executar cenário de teste de API
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r html,junit \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - name: Upload do relatório
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: relatorio-apidog
          path: ./apidog-reports

Note a simetria. Mesmo checkout, mesma configuração de Node, mesmo formato de instalação e execução, mesmo upload sempre ativo. As únicas diferenças reais são o token configurado como um segredo e o cenário selecionado por ID em vez de pelo caminho do arquivo. Como o cenário é buscado ao vivo, não há arquivo JSON para manter atualizado. Para o mesmo padrão em outros sistemas, como automatizar testes de API no GitHub Actions transporta a estrutura para GitLab CI e Jenkins.

Como escolher

A decisão raramente se resume a qual executor é objetivamente melhor. Ela se resume a onde seus testes já residem e como sua equipe deseja mantê-los.

Escolha o Newman quando seus testes já forem coleções Postman. Se sua suite reside no Postman, sua equipe escreve scripts de teste no editor, e você quer um executor gratuito e de código aberto que se integre a qualquer pipeline sem uma nova conta, o Newman é a escolha direta. É a opção natural para equipes que usam Postman e se sentem confortáveis em exportar uma coleção e fazer commit do JSON, e que não se importam em gerenciar os scripts de teste manualmente. Você pode ler mais sobre as diferenças dentro do ecossistema Postman em qual a diferença entre Newman e Postman.

Escolha o Apidog CLI quando a velocidade de autoria e uma única fonte da verdade importam mais do que permanecer dentro do Postman. Se você prefere construir um cenário de teste visualmente, encadear requisições, extrair variáveis e executar esse mesmo cenário em diferentes ambientes sem escrever e re-exportar código de teste, o Apidog remove esse atrito. Projete, depure, simule e teste ao vivo em um único espaço de trabalho, e o CLI executa exatamente o cenário que você construiu. Para equipes que estão saindo do Postman, a migração é algo que o Apidog aborda como uma alternativa ao Postman para testes de API, e a importação é feita com um clique.

Há também uma resposta para ambas as ferramentas. Algumas equipes mantêm uma etapa Newman existente executando suas coleções legadas enquanto movem cenários novos e mais complexos para o Apidog. Os dois CLIs coexistem bem em um pipeline; são etapas separadas com códigos de saída separados, e você pode desativar a etapa Newman no seu próprio tempo.

Para configurar seu primeiro cenário automatizado e executá-lo no terminal na mesma tarde, baixe o Apidog, construa um cenário de teste e copie o comando gerado da sua aba CI/CD.