DEV Community

Cover image for Apidog CLI vs Postman CLI: O Melhor Executor de Testes para CI
Lucas
Lucas

Posted on • Originally published at apidog.com

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

Seus testes de API não estão “automatizados” só porque passam quando você clica em Executar no laptop. O teste que importa é o que roda em cada pull request, merge e build noturno sem intervenção humana. Para isso, você precisa de um executor de linha de comando: ele roda os testes em modo headless, retorna um código de saída que a CI entende e gera relatórios que aparecem no dashboard da build.

Experimente o Apidog hoje

Dois executores aparecem com frequência nesse cenário: o CLI do Postman e o CLI do Apidog. Os dois executam testes de API em pipelines como GitHub Actions, GitLab CI e Jenkins. A diferença principal não está apenas no comando run, mas em como os testes são criados, onde vivem e como os resultados são publicados.

💡 Esta comparação é focada no uso em CI/CD. O CLI do Postman funciona bem quando sua equipe já mantém coleções no Postman. O CLI do Apidog funciona bem quando você quer criar cenários visuais, encadear requisições e executar esses mesmos cenários no pipeline.

TL;DR

  • CLI do Postman (postman) executa coleções do Postman. Ele é baseado no Newman, é oficialmente suportado pelo Postman e autentica via chave de API.
  • CLI do Apidog (apidog) executa cenários de teste criados visualmente no Apidog. Você informa o ID do cenário, o ambiente e um token de acesso.
  • Ambos geram relatórios cli, json, junit e html.
  • Ambos retornam código diferente de zero quando um teste falha, permitindo bloquear merges.
  • Use o CLI do Postman se seus testes já estão em coleções do Postman e você quer histórico na nuvem do Postman.
  • Use o CLI do Apidog se você quer criar cenários visuais, encadear requisições, usar ambientes e controlar se os relatórios ficam locais ou são enviados para a nuvem.

O problema: testes que existem, mas não rodam na CI

Um teste manual tende a ficar desatualizado. Alguém cria, executa uma vez e depois a API muda sem que o teste seja rodado novamente. O resultado é um falso senso de segurança.

Para que um teste de API seja útil em CI/CD, o executor precisa fazer três coisas:

  1. Rodar sem interface gráfica.
  2. Retornar erro quando uma asserção falhar.
  3. Gerar relatório legível pela CI, como JUnit XML.

Tanto o CLI do Postman quanto o CLI do Apidog atendem a esses requisitos. A escolha depende de onde seus testes são mantidos.

Se você está montando uma estratégia do zero, vale complementar com este guia sobre automação de testes de API em CI/CD.

O que o CLI do Postman faz bem

O CLI do Postman não é exatamente o Newman. Newman é o executor open source mais antigo, baseado em npm. O CLI do Postman é uma ferramenta mais nova, baseada na fundação do Newman, mas assinada e suportada oficialmente pelo Postman.

Se você está comparando os dois, veja também Postman CLI vs Newman.

A principal vantagem do CLI do Postman é executar o que sua equipe já tem no workspace do Postman: coleções, ambientes e variáveis.

Instalação

No macOS e Linux:

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

Também é possível instalar via npm:

npm install -g postman-cli
Enter fullscreen mode Exit fullscreen mode

O binário é:

postman
Enter fullscreen mode Exit fullscreen mode

Autenticação na CI

Use uma chave de API do Postman armazenada como segredo:

postman login --with-api-key $POSTMAN_API_KEY
Enter fullscreen mode Exit fullscreen mode

Executando uma coleção 

postman collection run $POSTMAN_COLLECTION_ID -e $POSTMAN_ENV_ID
Enter fullscreen mode Exit fullscreen mode

Na prática, um job de CI costuma adicionar repórteres e comportamento de falha rápida:

postman collection run $POSTMAN_COLLECTION_ID \
  -e $POSTMAN_ENV_ID \
  --reporters cli,junit \
  --bail
Enter fullscreen mode Exit fullscreen mode

Quando autenticado, o CLI do Postman também envia os resultados para a nuvem do Postman. Isso é útil para equipes que já usam o workspace do Postman como fonte de histórico e colaboração.

O que o CLI do Apidog faz bem

O Apidog usa outro modelo: você cria cenários visualmente dentro do aplicativo. Um cenário pode conter várias requisições encadeadas, asserções, extração de valores de respostas e dados de iteração.

O CLI executa esses cenários em modo headless. Ou seja, o teste que você desenha no editor visual é o mesmo que roda na CI.

Isso evita manter duas versões do mesmo teste: uma visual e outra em script.

Para fluxos como login, criação de recurso, consulta e exclusão, esse modelo reduz bastante o código “cola”. A criação desses fluxos é explicada no guia sobre cenários de teste para automação de testes de API.

Instalação 

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

O binário é:

apidog
Enter fullscreen mode Exit fullscreen mode

Executando um cenário

Um comando típico informa:

  • token de acesso;
  • ID do cenário;
  • ID do ambiente;
  • número de iterações;
  • formatos de relatório. 
apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -n 1 \
  -r html,junit
Enter fullscreen mode Exit fullscreen mode

Você não precisa descobrir esses IDs manualmente. No Apidog:

  1. Abra o cenário de teste.
  2. Vá para a aba CI/CD.
  3. Gere um token de acesso.
  4. Copie o comando apidog run gerado.
  5. Mova o token para um segredo da CI.

Exemplo usando variável de ambiente:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -r cli,junit \
  --out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Por padrão, os relatórios ficam locais. Para enviar uma visão geral para a nuvem do Apidog, use:

--upload-report
Enter fullscreen mode Exit fullscreen mode

Comparação lado a lado

Dimensão CLI do Postman (postman) CLI do Apidog (apidog)
Instalação Script oficial, instalador assinado ou npm i -g postman-cli npm i -g apidog-cli
Comando de execução postman collection run <id|arquivo> apidog run -t <scenarioId>
Fonte do teste Coleções no workspace do Postman ou arquivo exportado Cenários no projeto Apidog, buscados por ID
Autoria Editor de coleções do Postman Construtor visual de cenários do Apidog
Autenticação na CI Chave de API via postman login --with-api-key Token via --access-token
Selecionar o que executar ID da coleção ou caminho do arquivo Cenário -t, pasta -f ou --test-suite
Ambiente -e, --environment -e, --environment <environmentId>
Dados de iteração -d, --iteration-data com JSON ou CSV -d, --iteration-data com JSON ou CSV
Iterações -n, --iteration-count -n, --iteration-count
Repórteres cli, json, junit, html cli, html, json, junit
Falha rápida --bail --on-error end, padrão que para na primeira falha
Relatório na nuvem Envia resultados automaticamente quando autenticado Envia somente com --upload-report
Base Newman Motor próprio do Apidog

A parte comum é simples: ambos executam testes em CI, geram JUnit XML e fazem a build falhar quando algo quebra.

A diferença operacional é esta:

  • Postman executa coleções do workspace do Postman.
  • Apidog executa cenários visuais do projeto Apidog.

Repórteres e códigos de saída

Na CI, o que importa é:

  • relatório;
  • código de saída.

Postman CLI com JUnit 

postman collection run $POSTMAN_COLLECTION_ID \
  -e $POSTMAN_ENV_ID \
  --reporters cli,junit \
  --bail
Enter fullscreen mode Exit fullscreen mode

O repórter junit gera XML para dashboards de CI. A flag --bail interrompe no primeiro erro, útil para smoke tests.

Sem --bail, o executor continua e reporta todas as falhas no final.

Apidog CLI com JUnit 

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

Para controlar o comportamento em caso de erro:

apidog run --access-token $APIDOG_ACCESS_TOKEN \
  -t 605067 \
  -r cli,junit \
  --on-error continue
Enter fullscreen mode Exit fullscreen mode

Opções úteis:

  • --on-error end: para na primeira falha. É o padrão.
  • --on-error continue: continua executando para coletar mais falhas.
  • --on-error ignore: ignora uma falha conhecida e continua.

Em ambos os CLIs, qualquer falha retorna código diferente de zero.

Exemplo no GitHub Actions

A estrutura do workflow é a mesma:

  1. Fazer checkout do repositório.
  2. Instalar o CLI.
  3. Autenticar usando segredo.
  4. Rodar os testes.
  5. Publicar ou arquivar relatórios.

Nunca coloque tokens diretamente no YAML.

Postman CLI no GitHub Actions 

- 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
Enter fullscreen mode Exit fullscreen mode

Apidog CLI no GitHub Actions 

- 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
Enter fullscreen mode Exit fullscreen mode

Para salvar relatórios como artefatos:

- 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 html,junit \
      --out-dir ./apidog-reports

- name: Upload test reports
  uses: actions/upload-artifact@v4
  with:
    name: apidog-reports
    path: ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Se você quer um passo a passo mais completo, veja automação de testes de API com GitHub Actions. Para Jenkins, veja integrando testes automatizados do Apidog com Jenkins.

Qual escolher?

Não existe vencedor universal. A escolha depende do seu fluxo atual.

Use o CLI do Postman se:

  • suas coleções já estão no Postman;
  • seus ambientes e variáveis já estão no workspace;
  • sua equipe quer histórico de execução na nuvem do Postman;
  • você quer o menor atrito possível para continuar no ecossistema Postman.

Use o CLI do Apidog se:

  • você quer criar cenários visualmente;
  • precisa encadear requisições sem manter scripts duplicados;
  • quer executar na CI o mesmo cenário usado no editor visual;
  • prefere controlar se os relatórios ficam locais ou são enviados;
  • quer manter design, mocking, documentação e testes no mesmo workspace.

Equipes avaliando as plataformas como um todo podem consultar a comparação Apidog vs Postman.

Um fluxo prático com Apidog fica assim:

  1. Crie o cenário no editor visual.
  2. Adicione asserções nas respostas.
  3. Encadeie valores entre requisições quando necessário.
  4. Abra a aba CI/CD.
  5. Gere o comando apidog run.
  6. Salve o token como segredo da CI.
  7. Cole o comando no pipeline.
  8. Publique o relatório JUnit ou HTML como artefato.

FAQ

O CLI do Postman é o mesmo que o Newman?

Não. Newman é o executor npm open source mais antigo. O CLI do Postman é uma ferramenta mais nova, baseada na fundação do Newman, assinada e suportada pelo Postman. Veja a comparação em Postman CLI vs Newman.

Preciso de token ou conta para usar na CI?

Sim. O Postman CLI usa uma chave de API:

postman login --with-api-key $POSTMAN_API_KEY
Enter fullscreen mode Exit fullscreen mode

O Apidog CLI usa um token de acesso:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067
Enter fullscreen mode Exit fullscreen mode

Em ambos os casos, armazene o valor como segredo da CI.

Os dois fazem a build falhar quando um teste falha?

Sim. Ambos retornam código diferente de zero quando há falha em teste ou asserção.

Posso manter relatórios locais?

Sim.

No Apidog CLI, os relatórios ficam locais por padrão:

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

Você só envia para a nuvem com:

--upload-report
Enter fullscreen mode Exit fullscreen mode

No Postman CLI, relatórios locais também podem ser gerados, mas quando você está autenticado, os resultados também são enviados para a nuvem do Postman.

Como obtenho o comando exato do Apidog?

No Apidog:

  1. Abra o cenário.
  2. Vá para CI/CD.
  3. Gere o token.
  4. Copie o comando apidog run gerado.
  5. Coloque o token em um segredo da CI.

Para ver todas as flags:

apidog run --help
Enter fullscreen mode Exit fullscreen mode

Qual é melhor para uma equipe migrando do Postman?

Se a equipe quer sair de um modelo centrado na nuvem ou prefere criar cenários visuais e controlar relatórios, o CLI do Apidog tende a se encaixar melhor. Para comparar além do executor, veja Apidog vs Postman.

Top comments (0)