Como Rodar Testes de API Com Apidog CLI?

Seus testes de API passam no seu laptop. Então alguém mescla uma alteração às 2h da manhã, o endpoint de staging começa a retornar um payload malformado, e ninguém percebe até que um cliente abra um ticket na manhã seguinte. Os testes existiam. Eles simplesmente nunca rodaram onde importava: dentro do pipeline, a cada push, sem nenhum humano clicando em um botão.

Essa lacuna entre “testes que existem” e “testes que rodam automaticamente” é exatamente o que um executor de linha de comando preenche. A CLI do Apidog pega os cenários de teste que você já construiu no aplicativo de desktop ou web do Apidog e os executa sem interface gráfica a partir de um terminal. Sem GUI, sem cliques manuais. Você o instala com um único comando npm, o aponta para um cenário de teste, e ele sai com um código de status limpo e um relatório que você pode publicar em qualquer sistema de CI. Isso o torna a ponte entre o construtor de testes visual e sua plataforma de CI/CD.

TL;DR

• A CLI do Apidog é um pacote npm chamado apidog-cli. Instale-o globalmente com npm install -g apidog-cli, e então execute cenários com o comando apidog run.
• Ele executa os cenários de teste que você projeta no Apidog. Você não reescreve os testes como código; a CLI executa o mesmo cenário por ID, usando um token de acesso para autenticação.
• Execução principal: apidog run --access-token $APIDOG_ACCESS_TOKEN -t <scenarioId> -e <environmentId> -n 1 -r html,cli.
• Os relatórios cobrem cli, html, json e junit. O JUnit XML é o que se conecta diretamente aos dashboards de teste do CI.
• Um código de saída diferente de zero na falha do teste é o que torna a CLI um verdadeiro portão de qualidade. Testes falhos interrompem a construção por padrão.
• Funciona em qualquer executor de CI que tenha Node.js: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines e outros.

O que a CLI do Apidog realmente é

Apidog é uma plataforma de API tudo-em-um: você projeta o esquema, depura requisições, constrói cenários de teste automatizados, simula endpoints e publica documentação em um único espaço de trabalho. A maior parte desse trabalho acontece em uma interface visual. Você encadeia requisições em um cenário de teste, adiciona asserções, extrai valores de uma resposta para a próxima e itera sobre um arquivo de dados.

A CLI é o executor sem interface gráfica para esses cenários. Não possui seu próprio formato de teste. Ela acessa seu projeto Apidog, encontra o cenário que você nomeia por ID e o executa exatamente como o aplicativo faria, então reporta os resultados. Pense nisso como a relação entre uma ferramenta de build e seu código-fonte: a fonte da verdade vive no projeto, e a CLI é o que o executa sem a presença de uma pessoa.

Isso importa porque elimina a razão mais comum pela qual os testes de API se deterioram. Quando os testes vivem apenas como etapas clicáveis em um aplicativo de desktop, eles são executados quando alguém se lembra. Quando eles são executados a partir de um comando de uma linha, você pode conectá-los a um pipeline e eles serão executados a cada commit, a cada merge, a cada agendamento noturno. O construtor visual oferece autoria rápida; a CLI oferece automação. Você obtém ambos sem precisar escolher.

Se você vem do mundo Postman, o modelo mental se alinha perfeitamente. A CLI do Apidog desempenha o papel que a CLI do Postman ou Newman desempenham para as coleções do Postman, exceto que ela executa cenários de teste do Apidog e é distribuída como um único pacote. Cobrimos essa comparação em profundidade em CLI do Postman vs Newman, e a questão mais ampla de executar coleções em CI sem Newman se você estiver migrando.

Pré-requisitos

Antes de executar qualquer comando, você precisa de três coisas:

1. Node.js v16 ou superior. A CLI é distribuída como um pacote npm, então um runtime Node é a única dependência do sistema. Verifique o seu com node -v. Qualquer imagem de CI com Node 16+ já é qualificada.
2. Um cenário de teste do Apidog. A CLI executa cenários, não requisições avulsas. Crie um no aplicativo Apidog primeiro: encadeie suas requisições, adicione asserções, configure qualquer iteração orientada a dados que você precise. Se você é novo na criação de asserções, Asserções de API: um guia prático explica a validação de respostas.
3. Um token de acesso. Isso autentica a CLI na sua conta Apidog para que ela possa buscar e executar o cenário. Você o gera na aba CI/CD do cenário de teste; mais sobre isso abaixo.

É isso. Nenhuma instalação separada do Apidog na máquina de CI, nenhuma GUI, nenhum arquivo de licença. O pacote e um token são suficientes.

Instalando a CLI do Apidog

Instale-o globalmente com npm:

npm install -g apidog-cli

Em seguida, confirme se tudo foi resolvido corretamente:

node -v && apidog -v && which node && which npm && which apidog

Se isso imprimir números de versão e caminhos, você terminou. O binário é apidog, então todo comando começa com apidog run.

Em uma máquina de desenvolvedor, uma instalação global é adequada. Em CI, você tem dois padrões razoáveis. O primeiro é instalá-lo do zero em cada execução de pipeline, o que garante que você esteja na versão mais recente:

npm install -g apidog-cli
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

O segundo é executá-lo sem uma instalação global persistente via npx, o que evita a mutação dos pacotes globais do executor:

npx apidog-cli run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -r cli

Ambos funcionam. A abordagem npx é mais limpa para executores de CI efêmeros; a instalação global é marginalmente mais rápida quando você a armazena em cache entre as execuções.

Obtendo seu token de acesso e ID de cenário

A CLI precisa saber duas coisas: qual cenário executar e que ela tem permissão para executá-lo. O Apidog gera ambos para você, para que você não precise procurar na interface do usuário.

Abra o cenário de teste que você deseja automatizar. Mude para a aba CI/CD. Escolha a opção de linha de comando, então clique em Adicionar token de acesso e Gerar token. O Apidog constrói o comando apidog run completo para você, com o token de acesso, o ID do cenário e o ID do ambiente já preenchidos. Clique no comando para copiá-lo.

Esse comando gerado é o ponto de partida canônico. Ele se parece com isto:

apidog run --access-token YOUR_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,cli

Os números são IDs reais do seu projeto. 605067 é o ID do cenário de teste. 1629989 é o ID do ambiente. Você quase nunca digitará estes manualmente; você os copia da aba CI/CD uma vez e depois parametrizar o token.

Uma regra que vale a pena mencionar desde o início: trate o token de acesso como uma senha. Não o cole em um arquivo de configuração commitado ou em uma definição de pipeline pública. Armazene-o como um segredo em seu sistema de CI e referencie-o como uma variável de ambiente. Todos os exemplos abaixo usam $APIDOG_ACCESS_TOKEN exatamente por essa razão.

O comando apidog run, flag por flag

A CLI inteira gira em torno de um comando. Aqui está a superfície completa de opções, agrupada pelo que cada grupo controla.

Selecionando o que executar

Você escolhe um entre -t, -f ou --test-suite dependendo do escopo. Um único cenário para um teste de fumaça focado, uma pasta para uma área de recurso, um conjunto de testes quando você deseja um conjunto selecionado de cenários executados juntos como um único trabalho lógico.

Autenticação

Este é o único sinalizador que todo comando de CI precisa. Passe-o a partir de um segredo, nunca diretamente no comando.

Ambiente e iteração

O sinalizador de ambiente é como você aponta o mesmo cenário para o ambiente de staging em uma verificação de pull-request e para produção em um teste de fumaça pós-implantação, sem duplicar o cenário. Dados de iteração são como você executa um cenário em cinquenta linhas de entrada e trata cada linha como uma passagem separada. Cobrimos o padrão orientado a dados mais completamente no guia sobre escalar testes de API automatizados com conjuntos de testes.

Relatórios

É aqui que a CLI ganha seu lugar em um pipeline. Passe vários formatos de uma vez, separados por vírgulas:

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

cli oferece saída de terminal legível para humanos que leem o log de build. html produz um relatório autocontido que você pode arquivar como um artefato de build e abrir em um navegador. junit emite XML no formato JUnit padrão, que quase todos os dashboards de CI sabem como analisar em uma árvore de aprovação/reprovação. json fornece o resultado estruturado bruto se você quiser pós-processá-lo.

Tratamento de erros e comportamento de saída

--on-error controla o que acontece no meio do cenário. end interrompe a execução na primeira falha, que é o que você geralmente deseja para um teste de fumaça de falha rápida. continue executa cada etapa para que você veja todas as falhas em um relatório. ignore é para o caso raro em que uma etapa é conhecida por ser instável e você não quer que ela prejudique a execução.

TLS e certificados

Use estes quando testar endpoints por trás de TLS mútuo ou com cadeias de CA internas. Use -k apenas contra hosts internos confiáveis onde o certificado é autoassinado; nunca contra nada público.

Saída e diagnósticos

--verbose é sua primeira ação quando um teste passa localmente, mas falha em CI; ele mostra a requisição exata que o executor enviou e a resposta exata que ele recebeu. --silent é para trabalhos noturnos ruidosos onde você só se importa com o código de saída e o relatório salvo.

Códigos de saída: a parte que faz o CI funcionar

Um executor de testes só é útil em um pipeline se ele informar ao pipeline se os testes foram aprovados. A CLI do Apidog faz isso da mesma forma que toda ferramenta de linha de comando bem-comportada: ela sai com o código 0 quando todas as asserções passam e com um código diferente de zero quando algo falha.

Esse comportamento único é o que transforma apidog run em um portão de qualidade. Os sistemas de CI leem o código de saída de cada etapa. Uma saída diferente de zero marca a etapa como falha, o que falha o trabalho, o que bloqueia a mesclagem ou a implantação. Você não configura nada extra. Enquanto a etapa apidog run estiver no seu pipeline, um teste falho interrompe a linha.

Você pode moldar isso com --on-error. O comportamento padrão falha na primeira asserção quebrada, o que mantém o feedback rápido. Mude para --on-error continue quando preferir ver todas as falhas em um relatório antes que a build fique vermelha. De qualquer forma, a execução ainda termina com uma saída diferente de zero se algo falhar, então o portão se mantém.

Executando no GitHub Actions

Aqui está um workflow completo que executa um cenário Apidog em cada pull request e publica o relatório como um artefato.

name: Testes de API

on:
  pull_request:
    branches: [main]

jobs:
  testes-api:
    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 CLI Apidog
        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 \
            -n 1 \
            -r html,junit \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

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

O token reside nos segredos do repositório e chega à etapa como uma variável de ambiente. O if: always() na etapa de upload significa que você ainda obtém o relatório mesmo quando os testes falham, que é exatamente quando você deseja lê-lo. Se um teste falha, a etapa apidog run sai com um código diferente de zero, o trabalho fica vermelho e o PR mostra uma verificação falha.

Executando no GitLab CI

O mesmo padrão em .gitlab-ci.yml:

stages:
  - teste

testes-api:
  stage: teste
  image: node:20
  script:
    - npm install -g apidog-cli
    - >
      apidog run
      --access-token "$APIDOG_ACCESS_TOKEN"
      -t 605067
      -e 1629989
      -r junit,cli
      --out-dir ./apidog-reports
  artifacts:
    when: always
    paths:
      - apidog-reports/
  reports:
    junit: apidog-reports/*.xml

Duas coisas a serem observadas. Armazene APIDOG_ACCESS_TOKEN como uma variável de CI/CD mascarada e protegida em Configurações, não no arquivo. E o bloco reports: junit: informa ao GitLab para analisar o XML JUnit e renderizar os resultados no widget de solicitação de merge, para que um revisor veja quais asserções falharam sem baixar nada.

Executando no Jenkins

Em um pipeline declarativo, armazene o token como uma credencial Jenkins ou uma variável de ambiente global, então chame a CLI em um estágio:

pipeline {
  agent any
  environment {
    APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
  }
  stages {
    stage('Testes de API') {
      steps {
        sh 'npm install -g apidog-cli'
        sh 'apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e 1629989 -n 1 -r html,junit --out-dir apidog-reports'
      }
    }
  }
  post {
    always {
      junit 'apidog-reports/*.xml'
      archiveArtifacts artifacts: 'apidog-reports/', allowEmptyArchive: true
    }
  }
}

Se seus agentes de build já têm a CLI instalada e em cache, remova a linha npm install e chame apidog run diretamente. A etapa junit no bloco post alimenta o XML nos gráficos de tendência de teste do Jenkins; archiveArtifacts mantém o relatório HTML anexado à build. Se você está comparando Jenkins com outros executores, a comparação em Configuração do CI do ReadyAPI Jenkins, e uma alternativa mais simples aborda as vantagens e desvantagens.

Padrões e receitas comuns

Teste de fumaça após implantação. Execute um cenário rápido contra a produção logo após um lançamento, visando o ambiente de produção:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -e <prodEnvId> -r cli --on-error end

Regressão completa noturna. Execute uma pasta inteira de cenários em um agendamento, com todas as falhas coletadas em um único relatório:

apidog run --access-token $APIDOG_ACCESS_TOKEN -f <folderId> -r html,junit --on-error continue --out-dir ./nightly-reports

Execução orientada a dados. Itere um cenário sobre um CSV de casos de teste:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 -d ./test-data.csv -r junit

Verificação específica de branch. Execute os cenários como eles existem em uma branch de recurso, não main:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t 605067 --branch feature-payments -e 1629989 -r cli

Depure uma falha apenas em CI. Quando um cenário passa localmente, mas falha no pipeline, adicione --verbose para ver a requisição e a resposta exatas em nível de rede que o executor produziu.

Resolução de problemas

• Erros de autenticação. Se a execução falhar com um erro de autenticação, o token está errado, expirado ou não está chegando ao comando. Faça um echo de uma verificação mascarada (nunca o token completo) e confirme se seu segredo de CI está realmente preenchido. Gere novamente o token na aba CI/CD do cenário, se necessário.
• “Cenário não encontrado.” O ID do cenário, ID do projeto ou branch não corresponde. Copie novamente o comando da aba CI/CD para garantir que os IDs estejam atualizados e confirme se --branch aponta para onde você espera.
• Testes passam localmente, mas falham em CI. Quase sempre uma diferença de ambiente. O executor de CI pode visar um ambiente -e diferente, acessar um host que não consegue alcançar ou faltar uma variável da qual seu cenário depende. Execute com --verbose e compare a requisição que o executor de CI enviou com o que você envia localmente.
• Falhas de rede ou TLS contra hosts internos. Se seu endpoint usa uma CA interna, passe --ssl-extra-ca-certs. Use -k apenas como último recurso em hosts internos confiáveis onde o certificado é autoassinado.
• A build permanece verde mesmo quando um teste deveria falhar. Confirme se o código de saída da etapa apidog run está realmente chegando ao CI. Se você o envolveu em um pipeline de shell ou adicionou || true, a saída diferente de zero é engolida e o portão para de funcionar. Remova qualquer coisa que mascare o código de saída.

Como a CLI do Apidog se encaixa em um fluxo de trabalho real

A CLI é uma peça de um loop. Você projeta e depura requisições no aplicativo Apidog. Você as encadeia em um cenário com asserções. Você commita seu trabalho e a CLI executa esse cenário em CI a cada alteração. Quando algo quebra, o relatório informa qual asserção falhou e o código de saída interrompe a implantação. Você corrige, envia novamente e o mesmo portão confirma a correção.

A vantagem de construir testes visualmente e executá-los sem interface gráfica é que ninguém precisa manter duas representações do mesmo teste. O cenário no projeto é o teste. A CLI apenas o executa onde um humano não pode estar. Esse é um modelo diferente dos executores baseados em script, onde o teste e sua execução são o mesmo arquivo frágil, e é uma grande parte do motivo pelo qual as equipes migram para Apidog como uma alternativa ao Postman para testes de API.

Se você ainda não construiu os testes, comece no aplicativo, faça um cenário passar, então configure o comando da CLI a partir de sua aba CI/CD. Baixe o Apidog para configurar seu primeiro cenário automatizado, e você o terá guardando seu pipeline na mesma tarde.

Perguntas frequentes

• A CLI do Apidog é gratuita? A CLI em si é um pacote npm gratuito. Você a instala com npm install -g apidog-cli. Ela executa os cenários de teste do seu projeto Apidog, então o que você pode executar depende do seu plano Apidog, mas o executor de linha de comando não é um produto pago separado.
• Preciso reescrever meus testes como código para usar a CLI? Não. Essa é a principal diferença dos executores baseados em script. Você constrói cenários visualmente no Apidog, e a CLI os executa por ID. O cenário é o teste; a CLI é apenas o executor.
• Qual a diferença entre a CLI do Apidog e o Newman? O Newman executa coleções Postman a partir da linha de comando. A CLI do Apidog executa cenários de teste do Apidog. Os papéis são paralelos, mas o executor do Apidog executa cenários que você criou no aplicativo Apidog e é distribuído como o único pacote apidog-cli. Veja CLI do Postman vs Newman para o lado Postman dessa comparação.
• Qual formato de relatório devo usar em CI? Use junit para o resultado legível por máquina que seu dashboard de CI analisa em uma árvore de aprovação/reprovação, e adicione html se quiser um relatório navegável salvo como um artefato de build. Uma escolha comum é -r html,junit. Mantenha cli também se quiser uma saída legível no log de build.
• Como a CLI faz uma build falhar? Através do seu código de saída. Quando qualquer asserção falha, apidog run sai com um código diferente de zero. Os sistemas de CI leem esse código de saída, marcam a etapa como falha e bloqueiam a mesclagem ou implantação. Você não configura nada extra para que isso funcione.
• Posso executar a CLI sem instalá-la globalmente? Sim. Use npx apidog-cli run ... para executá-la sem uma instalação global persistente, o que é conveniente em executores de CI efêmeros.
• Que versão do Node.js eu preciso? Node.js v16 ou superior. Qualquer imagem de CI moderna com Node 16+ já satisfaz o requisito.
• Onde consigo o token de acesso e o ID do cenário?** Ambos vêm da aba CI/CD do cenário de teste no Apidog. Escolha a opção de linha de comando, gere um token de acesso e copie o comando apidog run completo que o Apidog constrói para você com os IDs já preenchidos. Em seguida, mova o token para um segredo de CI.