Apidog CLI vs Postman CLI: O Melhor Executor de Testes para CI

Seus testes de API passam quando você clica em 'Executar' no seu laptop. Isso não prova nada. O teste que realmente importa é aquele que dispara em cada pull request, em cada merge e em cada build noturno, sem a presença humana para clicar em nada. A tarefa de inserir seus testes nesse ciclo 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 aparece no dashboard da build.

Dois executores surgem repetidamente quando as equipes configuram isso: o CLI do Postman e o CLI do Apidog. Eles visam o mesmo objetivo a partir de pontos de partida diferentes. O CLI do Postman executa as coleções que você cria no Postman. O CLI do Apidog executa os cenários de teste visuais que você cria no Apidog. Ambos são instalados em uma única etapa, ambos se integram ao GitHub Actions, GitLab CI e Jenkins, e ambos fazem a build falhar quando um teste falha. As verdadeiras diferenças estão a montante do comando de execução: como você escreve os testes, como você se autentica na CI e onde a definição do teste realmente reside.

TL;DR

• CLI do Postman (binário postman) executa as coleções armazenadas no seu workspace do Postman. É baseado no Newman, assinado e suportado pelo Postman, e autentica com uma chave de API do Postman. Quando você está logado, ele envia os resultados da execução de volta para a nuvem do Postman automaticamente.
• CLI do Apidog (apidog-cli, binário apidog) executa os cenários de teste que você projeta visualmente no Apidog. Você o aponta para um cenário por ID com um token de acesso, e ele executa esse cenário sem interface gráfica (headless) e sem GUI.
• Ambos emitem relatórios JUnit, JSON, HTML e de terminal. Ambos falham a build em caso de teste com falha. O XML JUnit é o que se conecta a um dashboard de CI em ambos os casos.
• Escolha o CLI do Postman quando seus testes já residem em coleções do Postman e sua equipe está comprometida com a nuvem do Postman para relatórios e histórico.
• Escolha o CLI do Apidog quando você deseja autoria visual de cenários, encadeamento de requisições, gerenciamento de ambiente e execuções orientadas por dados a partir de uma única fonte de verdade, com controle total sobre se os relatórios permanecem locais ou vão para a nuvem.

O problema real: testes que existem, mas nunca são executados

Um teste que você executa manualmente é um teste que apodrece. Alguém o escreveu, ele passou uma vez e depois ficou intocado enquanto a API mudava. Três meses depois, o teste está incorreto e ninguém percebeu, porque ninguém o executou. A solução não é escrever mais testes. É fazer com que os testes que você tem sejam executados automaticamente a cada alteração, com um sinal de sucesso ou falha sobre o qual o pipeline possa agir.

Um executor de CLI é a ferramenta que preenche essa lacuna. Para ganhar um lugar na CI, ele precisa fazer três coisas. Ele precisa ser executado sem GUI, porque seu executor de CI não tem tela. Ele precisa sair com um código diferente de zero quando algo falha, para que a build fique vermelha e um merge problemático seja bloqueado. E ele precisa escrever um relatório legível por máquina, para que o revisor veja o que quebrou sem precisar executar nada localmente. O CLI do Postman e o CLI do Apidog superam esse desafio de forma limpa. Onde eles se diferenciam é em tudo o que acontece antes de run: como o teste foi escrito e onde ele reside quando a CI o procura.

Se você está configurando testes automatizados do zero, os padrões mais amplos em automação de testes de API em CI/CD valem a leitura junto com este artigo. Aqui, o foco permanece nos dois executores.

O que o CLI do Postman faz bem

Primeiro, um ponto de clareza que confunde muitas pessoas: o CLI do Postman não é o Newman. Newman é o executor mais antigo, de código aberto, baseado em npm, que a comunidade tem usado por anos. O CLI do Postman é uma ferramenta mais nova, construída sobre a fundação do Newman, mas assinada e oficialmente suportada pela empresa Postman. Se você tem usado o Newman, os dois não são intercambiáveis, e a diferença importa na CI. Nós detalhamos essa distinção exata em Postman CLI vs Newman se você estiver decidindo entre as duas opções do lado do Postman.

A maior força do CLI do Postman é que ele permanece dentro do mundo que sua equipe já conhece. Se suas coleções, ambientes e variáveis compartilhadas já residem em um workspace do Postman, o CLI os executa com quase nenhuma tradução. Você não reconstrói nada. Você se autentica, nomeia a coleção, e ele executa as requisições e testes exatamente como o aplicativo faria.

A instalação é um único comando. No macOS e Linux, você executa o script de instalação oficial:

curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh

No Windows, você usa o instalador PowerShell assinado, e também existe um pacote npm se você preferir fixá-lo como uma dependência de desenvolvimento:

npm install -g postman-cli

O binário é postman. Na CI, você se autentica com uma chave de API do Postman, que é o método que o Postman recomenda para pipelines:

postman login --with-api-key $POSTMAN_API_KEY

Então você executa uma coleção pelo seu ID, ou por um caminho de arquivo local se você a exportou:

postman collection run $POSTMAN_COLLECTION_ID -e $POSTMAN_ENV_ID

A parte que garante ao CLI do Postman muita lealdade é o que acontece após a execução. Quando você está logado, ele envia os resultados da execução diretamente para a nuvem do Postman, onde aparecem no seu workspace junto com a coleção. Histórico de testes, comparações de execução e o dashboard visível para a equipe estão todos lá sem nenhuma configuração extra. Para uma equipe que já vive no Postman, essa viagem de ida e volta é genuinamente útil, e é uma boa razão para permanecer.

O que o CLI do Apidog faz bem

O Apidog segue um caminho diferente para o mesmo pipeline. Você constrói testes visualmente dentro do aplicativo Apidog: encadeia várias requisições em um único cenário de teste, adiciona asserções em cada resposta, extrai um valor de uma resposta e o alimenta na próxima requisição, e repete todo o cenário sobre um arquivo de dados. O CLI é o executor sem interface gráfica (headless) para esses cenários. Ele não possui um formato de teste próprio. Ele acessa seu projeto Apidog, encontra o cenário que você nomeia por ID e o executa exatamente como o aplicativo faria, e então reporta os resultados.

A vantagem é que ninguém mantém duas cópias do mesmo teste. O cenário que você construiu no editor visual é o teste que é executado na CI. Não há uma etapa em que você re-expresse um teste funcionando como um script e depois depure o script. O ciclo rápido de autoria e o ciclo de automação compartilham uma única fonte de verdade. Para fluxos de várias etapas, como login, criação, leitura e exclusão, esse encadeamento visual economiza muito do código "cola" que você escreveria manualmente. A mecânica de construção desses fluxos é abordada no guia para cenários de teste para automação de testes de API.

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, seleciona um ambiente, define uma contagem de iterações e 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, mude para a guia CI/CD, clique para gerar um token de acesso, e o Apidog constrói o comando completo para você com o ID do cenário e o ID do ambiente já preenchidos. Você o copia uma vez, move o token para um segredo de CI e o referencia como $APIDOG_ACCESS_TOKEN no seu fluxo de trabalho.

O modelo de token e ID é a divisão mais clara em relação ao CLI do Postman. O Apidog executa testes armazenados em um projeto que o CLI busca pela rede, autenticado pelo token. Não há uma opção de adesão separada à nuvem para relatórios: você escolhe --out-dir para artefatos locais e adiciona --upload-report apenas quando deseja que uma visão geral seja enviada para a nuvem do Apidog. Os relatórios permanecem onde você os coloca.

Lado a lado

Duas coisas se destacam nessa tabela. Primeiro, ambos os executores cobrem os itens essenciais de CI de forma quase idêntica: seleção de ambiente, iteração orientada a dados, os quatro formatos de relatório importantes e uma saída diferente de zero em caso de falha. Se tudo o que você precisa é um executor que sinalize falha em um merge problemático, qualquer um deles faz o trabalho. Segundo, a verdadeira divisão está em onde o teste reside e como você o escreveu. O CLI do Postman executa uma coleção que está no seu workspace do Postman. O CLI do Apidog executa um cenário visual que está no seu projeto Apidog.

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

Um executor prova seu valor em um pipeline por meio de dois comportamentos: o relatório que ele escreve e o código de saída que ele retorna. Acertando esses dois, todo o resto são as conexões.

O CLI do Postman aceita uma lista de repórteres separada por vírgulas e, quando você está logado, também envia os resultados para a nuvem do Postman:

postman collection run $POSTMAN_COLLECTION_ID \
  -e $POSTMAN_ENV_ID \
  --reporters cli,junit \
  --bail

O repórter junit é o que seu dashboard de CI analisa em uma árvore de sucesso ou falha. A flag --bail interrompe a execução na primeira requisição, teste ou asserção que falhar, o que mantém o feedback rápido em um teste de fumaça. Remova --bail e ele executa tudo, então reporta todas as falhas juntas. O CLI sai com um código diferente de zero em qualquer falha, então a build fica vermelha por si só.

O CLI do Apidog usa a mesma ideia de repórter -r e escreve tudo em um 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 molda 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 avança um passo que se sabe ser instável sem desviar a execução. De qualquer forma, o processo termina com um código diferente de zero se algo falhar, e o XML JUnit é salvo em ./apidog-reports pronto para seu dashboard.

O resultado prático: ambos escrevem XML JUnit, ambos falham a build corretamente e ambos arquivam um relatório HTML que você pode abrir mais tarde. A diferença na geração de relatórios é a viagem de ida e volta à nuvem. O Postman envia os resultados para sua nuvem por padrão quando você está autenticado. O Apidog mantém os relatórios locais, a menos que você peça para fazer o upload. Nenhum é melhor em abstrato; um serve a equipes que querem um histórico hospedado sem precisar pensar muito, o outro serve a equipes que querem decidir exatamente o que sai do executor.

Conectando cada um ao GitHub Actions

A estrutura de um trabalho do GitHub Actions é a mesma para ambos: fazer checkout do repositório, configurar o Node, instalar o CLI, executar os testes, e o código de saída de falha bloqueia o merge. Armazene o segredo nas configurações do seu repositório, nunca no arquivo de workflow.

- name: Run API tests (Postman CLI)
  run: |
    curl -o- "https://dl-cli.pstmn.io/install/unix.sh" | sh
    postman login --with-api-key ${{ secrets.POSTMAN_API_KEY }}
    postman collection run $POSTMAN_COLLECTION_ID -e $POSTMAN_ENV_ID --reporters cli,junit --bail

E a versão do CLI do Apidog:

- name: Run API tests (Apidog CLI)
  run: |
    npm install -g apidog-cli
    apidog run --access-token ${{ secrets.APIDOG_ACCESS_TOKEN }} -t 605067 -e 1629989 -r cli,junit

Ambos são curtos, ambos são legíveis e ambos se comportam da mesma forma no nível que seu pipeline se importa: uma execução bem-sucedida sai com zero e o merge prossegue, uma execução com falha sai com um código diferente de zero e o merge é bloqueado. Se você deseja um guia mais aprofundado sobre a execução de testes de API em um workflow do GitHub, automação de testes de API com GitHub Actions descreve passo a passo. Para usuários do Jenkins, a mesma ideia é apresentada em integrando testes automatizados do Apidog com Jenkins.

Então, qual deles vence na CI?

Não há um único vencedor, porque a resposta certa depende de onde seus testes já residem e de como sua equipe deseja criá-los e armazená-los.

O CLI do Apidog vence quando você valoriza a autoria visual e uma única fonte de verdade mais do que um histórico de nuvem hospedado. Você constrói um cenário uma vez no editor visual, com encadeamento de requisições e asserções tratadas para você, e o mesmo cenário é executado na CI por referência. Você decide se os relatórios permanecem locais ou são enviados. E porque o Apidog cobre design, mocking e documentação no mesmo workspace, o cenário de teste fica ao lado do contrato de API que ele verifica, o que impede que testes e especificações se desvinculem. Equipes avaliando as plataformas de forma mais ampla podem ler a comparação completa Apidog vs Postman.

O CLI do Postman vence quando sua equipe já está dentro do Postman. Suas coleções estão lá, seus ambientes estão lá, e você quer o histórico de execução na nuvem do Postman sem precisar configurar nada. A viagem de ida e volta à nuvem em cada execução é uma verdadeira conveniência para essa configuração, e a ferramenta é oficialmente assinada e suportada. Se isso descreve sua equipe, mudar de executor não lhe trará muitos benefícios.

Se você já se sente preso pelo modelo de nuvem do Postman, ou apenas deseja criar testes uma vez e executá-los em todos os lugares, a mudança é clara. Baixe o Apidog, construa um cenário, abra sua guia CI/CD e copie o comando apidog run gerado para o seu pipeline. Essa é toda a configuração.

FAQ

• O CLI do Postman é o mesmo que o Newman? Não. Newman é o executor npm de código aberto mais antigo. O CLI do Postman é uma ferramenta mais nova construída sobre a base do Newman, assinada e suportada pelo Postman, com relatórios integrados para a nuvem do Postman. Se você está escolhendo entre os dois do lado do Postman, Postman CLI vs Newman detalha as diferenças.
• Preciso de uma conta ou token para qualquer CLI na CI? Sim, para ambos, mas o formato difere. O CLI do Postman autentica com uma chave de API do Postman via postman login --with-api-key. O CLI do Apidog autentica com um token de acesso passado como --access-token. Armazene qualquer um deles como um segredo de CI, nunca no arquivo de workflow.
• Ambos os executores falham a build quando um teste falha? Sim. Ambos saem com um código de status diferente de zero em qualquer teste ou asserção falha, o que informa ao seu sistema de CI para marcar a build como vermelha e bloquear o merge. O CLI do Postman usa --bail para parar na primeira falha; o CLI do Apidog usa --on-error end, que é seu padrão.
• Posso manter meus relatórios locais em vez de enviá-los para uma nuvem? O CLI do Apidog mantém os relatórios locais por padrão e os escreve em --out-dir; você só faz upload com --upload-report. O CLI do Postman também escreve relatórios locais, mas quando você está logado, ele também envia os resultados da execução para a nuvem do Postman automaticamente.
• Como obtenho o comando de execução exato do Apidog para meu cenário? Abra o cenário de teste no Apidog, mude para a aba CI/CD, gere um token de acesso, e o Apidog construirá o comando completo apidog run com o ID do cenário e o ID do ambiente já preenchidos. Copie-o, mova o token para um segredo de CI, e pronto. Para cada flag disponível, execute apidog run --help.
• Qual deles uma equipe migrando da nuvem Postman deve escolher? Se o motivo da sua saída é o modelo centrado na nuvem ou os preços, o CLI do Apidog se encaixa, porque ele executa um único cenário visual do seu projeto e permite que você decida o que sai do executor. Comece com a comparação Apidog vs Postman para ver como as plataformas se alinham além do executor.