DEV Community

Cover image for Como Rodar Testes de API Com Apidog CLI?
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Rodar Testes de API Com Apidog CLI?

Seus testes de API passam no laptop. Então alguém faz merge às 2h da manhã, o endpoint de staging começa a retornar um payload malformado, e ninguém percebe até um cliente abrir um ticket. Os testes existiam, mas não rodavam onde importava: no pipeline, a cada push, sem alguém clicar em um botão.

Experimente o Apidog hoje

A CLI do Apidog resolve essa lacuna. Ela executa, via terminal, os cenários de teste que você já criou no Apidog desktop ou web. Você instala com npm, aponta para um cenário, passa um token de acesso e deixa o CI decidir: se as asserções falharem, o comando sai com código diferente de zero e a build quebra.

TL;DR

  • A CLI do Apidog é o pacote npm apidog-cli.
  • Instalação global: 
npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode
  • Execução básica: 
apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t <scenarioId> \
  -e <environmentId> \
  -n 1 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode
  • Você não reescreve testes como código. A CLI executa cenários já criados no Apidog.
  • Relatórios disponíveis: cli, html, json e junit.
  • Use junit para integrar com dashboards de CI.
  • Se qualquer asserção falhar, o comando retorna código diferente de zero e bloqueia o pipeline.
  • Funciona em qualquer CI com Node.js: GitHub Actions, GitLab CI, Jenkins, CircleCI, Azure Pipelines etc.

O que a CLI do Apidog faz

O Apidog é uma plataforma para projetar APIs, depurar requisições, criar testes automatizados, simular endpoints e publicar documentação. Na interface visual, você monta cenários de teste encadeando requisições, adicionando asserções, extraindo valores de uma resposta para usar na próxima etapa e, se necessário, iterando com dados externos.

A CLI é o executor headless desses cenários. Ela não cria um formato novo de teste. Em vez disso, acessa seu projeto Apidog, localiza o cenário pelo ID e executa esse cenário como o aplicativo faria.

O fluxo fica assim:

  1. Você cria e valida o cenário no Apidog.
  2. Gera o comando na aba CI/CD do cenário.
  3. Salva o token como segredo no CI.
  4. Executa apidog run no pipeline.
  5. Publica relatórios e usa o código de saída como quality gate.

Se você vem do Postman, o modelo é parecido com Postman CLI ou Newman, mas aplicado aos cenários do Apidog. Para contexto, veja CLI do Postman vs Newman e como executar coleções em CI sem Newman.

Pré-requisitos

Antes de rodar a CLI, prepare:

  1. Node.js v16 ou superior

Verifique a versão:

node -v
Enter fullscreen mode Exit fullscreen mode

Qualquer imagem moderna de CI com Node 16+ atende ao requisito.

  1. Um cenário de teste no Apidog

A CLI executa cenários, não requisições avulsas. Crie um cenário no Apidog com suas requisições, variáveis, scripts e asserções. Se precisar revisar validações, veja Asserções de API: um guia prático.

  1. Um token de acesso

O token autentica a CLI para buscar e executar o cenário. Gere-o na aba CI/CD do cenário.

Instalando a CLI do Apidog

Instale globalmente:

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

Valide a instalação:

node -v && apidog -v && which node && which npm && which apidog
Enter fullscreen mode Exit fullscreen mode

Se o comando imprimir versões e caminhos, a CLI está pronta. O binário é apidog, e o comando principal é apidog run.

Captura de tela mostrando a saída da instalação e verificação da CLI do Apidog

Em uma máquina local, a instalação global é simples. Em CI, você pode escolher entre instalar a cada execução:

npm install -g apidog-cli

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e 1629989 \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Ou usar npx sem instalação global persistente:

npx apidog-cli run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e 1629989 \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Use npx para runners efêmeros. Use instalação global se você consegue cachear dependências entre execuções.

Obtendo token de acesso, ID do cenário e ID do ambiente

A CLI precisa de duas informações principais:

  • qual cenário executar;
  • permissão para executá-lo.

No Apidog:

  1. Abra o cenário de teste.
  2. Acesse a aba CI/CD.
  3. Escolha a opção de linha de comando.
  4. Clique em Adicionar token de acesso.
  5. Gere o token.
  6. Copie o comando apidog run gerado.

O comando gerado se parece com isto:

apidog run \
  --access-token YOUR_ACCESS_TOKEN \
  -t 605067 \
  -e 1629989 \
  -n 1 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Neste exemplo:

  • 605067 é o ID do cenário.
  • 1629989 é o ID do ambiente.
  • YOUR_ACCESS_TOKEN deve ser movido para um segredo do CI.

Nunca comite o token em arquivos de configuração. Use uma variável de ambiente, por exemplo:

APIDOG_ACCESS_TOKEN=<valor-do-segredo>
Enter fullscreen mode Exit fullscreen mode

E chame:

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

Comando apidog run: flags principais

Selecionando o que executar

Flag Argumento Uso
-t, --test-scenario <testScenarioId> Executa um cenário específico por ID.
-f, --test-scenario-folder <folderId> Executa todos os cenários dentro de uma pasta.
--test-suite <testSuiteId> Executa um conjunto de testes por ID.
--project <projectId> Especifica o projeto do cenário.
--branch <branchName> Executa contra uma branch específica. O padrão é main.

Use:

  • -t para smoke tests ou validações específicas;
  • -f para uma área funcional;
  • --test-suite para um conjunto de cenários curado.

Veja também conjuntos de testes no Apidog.

Autenticação

Flag Argumento Uso
--access-token <accessToken> Autentica a execução na conta Apidog.

Em CI, sempre passe o token via segredo:

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

Ambiente e iteração

Flag Argumento Uso
-e, --environment <environmentId> Define o ambiente alvo, como dev, staging ou prod.
-n, --iteration-count <n> Executa o cenário n vezes.
-d, --iteration-data <path> Usa um arquivo JSON ou CSV para iterações.
--variables <path> Carrega variáveis de um arquivo local.
--global-var <value> Define variável global inline no formato chave=valor.
--env-var <value> Sobrescreve variável de ambiente inline no formato chave=valor.

Exemplo usando o mesmo cenário contra staging:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e <stagingEnvId> \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Exemplo orientado a dados com CSV:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -d ./test-data.csv \
  -r junit
Enter fullscreen mode Exit fullscreen mode

Para escalar cenários, veja o guia sobre testes automatizados com conjuntos de testes.

Relatórios

Flag Argumento Uso
-r, --reporters [reporters] Define formatos: cli, html, json, junit. Padrão: cli.
--out-dir <outDir> Diretório de saída. Padrão: ./apidog-reports.
--out-file <outFile> Nome do arquivo de relatório. Suporta {FOLDER_NAME}, {SCENARIO_NAME}, {GENERATE_TIME}.
--out-json-failures-separated <value> Salva falhas em um JSON separado.
--upload-report [value] Envia uma visão geral do relatório para a nuvem Apidog.

Exemplo comum para CI:

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

Use:

  • cli para logs legíveis no terminal;
  • html para arquivar um relatório navegável como artefato;
  • junit para integração com dashboards de CI;
  • json para pós-processamento customizado.

Tratamento de erros

Flag Argumento Uso
--on-error <behavior> Define comportamento em falhas: ignore, continue ou end.
--ignore-redirects Não segue redirecionamentos HTTP automaticamente.
--delay-request [n] Aguarda n ms entre requisições.
--timeout-request [n] Timeout por requisição em ms.
--timeout-script [n] Timeout de execução de script em ms.

Escolha:

--on-error end
Enter fullscreen mode Exit fullscreen mode

Para falhar rápido em smoke tests.

--on-error continue
Enter fullscreen mode Exit fullscreen mode

Para executar todas as etapas e coletar todas as falhas no relatório.

Use ignore apenas quando uma etapa é conhecida como instável e não deve afetar o resultado da execução.

TLS e certificados

Flag Argumento Uso
-k, --insecure Desabilita verificação de certificado SSL.
--ssl-client-cert <path> Certificado de cliente em PEM.
--ssl-client-key <path> Chave privada do certificado de cliente.
--ssl-client-passphrase <passphrase> Senha do certificado de cliente.
--ssl-client-cert-list <path> Arquivo que mapeia certificados para hosts.
--ssl-extra-ca-certs <path> CAs adicionais confiáveis.

Para endpoints internos com CA própria:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  --ssl-extra-ca-certs ./internal-ca.pem
Enter fullscreen mode Exit fullscreen mode

Use -k apenas em hosts internos confiáveis com certificado autoassinado. Evite em endpoints públicos.

Diagnóstico

Flag Argumento Uso
--verbose Imprime detalhes completos de requisição e resposta.
--silent Suprime saída do console.
--color <value> Força saída colorida ligada ou desligada.
--external-program-path <path> Aponta para arquivo de programas externos.
--database-connection <path> Arquivo de configuração de banco de dados.
--preferred-http-version <version> Define versão preferencial do HTTP.
-b, --bigint Habilita suporte a BigInt.
--lang <language> Idioma da CLI.
-h, --help Exibe ajuda.

Quando o teste passa localmente, mas falha no CI, rode com:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e 1629989 \
  --verbose
Enter fullscreen mode Exit fullscreen mode

Isso mostra a requisição enviada pelo runner e a resposta recebida.

Códigos de saída: o que faz o CI bloquear a build

A CLI usa o comportamento padrão de ferramentas de linha de comando:

  • código 0: todas as asserções passaram;
  • código diferente de 0: houve falha.

Isso torna apidog run um quality gate.

Em um pipeline, se a etapa abaixo falhar:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e 1629989
Enter fullscreen mode Exit fullscreen mode

O CI marca o job como falho e bloqueia merge ou deploy, conforme sua configuração.

Evite mascarar esse código de saída. Não use:

apidog run ... || true
Enter fullscreen mode Exit fullscreen mode

Isso faria a build continuar mesmo com testes quebrados.

GitHub Actions

Exemplo completo executando testes de API em pull requests e publicando relatórios como 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
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • salve APIDOG_ACCESS_TOKEN em Settings → Secrets and variables → Actions;
  • if: always() garante upload do relatório mesmo quando os testes falham;
  • junit permite integração com ferramentas que leem XML de testes;
  • a build falha automaticamente se apidog run retornar código diferente de zero.

GitLab CI

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

No GitLab:

  1. Vá em Settings → CI/CD → Variables.
  2. Crie APIDOG_ACCESS_TOKEN.
  3. Marque como mascarada e protegida, se fizer sentido para seu fluxo.
  4. Use reports: junit para exibir os resultados na merge request.

Jenkins

Pipeline declarativo:

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

Se seus agentes Jenkins já têm a CLI instalada, remova:

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

A etapa junit alimenta os gráficos e relatórios do Jenkins. archiveArtifacts mantém o HTML disponível na build.

Se você está comparando Jenkins com outros fluxos, veja Configuração do CI do ReadyAPI Jenkins, e uma alternativa mais simples.

Receitas práticas

Smoke test após deploy

Execute um cenário curto contra produção logo após a implantação:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e <prodEnvId> \
  -r cli \
  --on-error end
Enter fullscreen mode Exit fullscreen mode

Regressão completa noturna

Execute uma pasta inteira e colete todas as falhas:

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

Teste orientado a dados

Execute o mesmo cenário para cada linha de um CSV:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -d ./test-data.csv \
  -r junit
Enter fullscreen mode Exit fullscreen mode

Execução por branch

Execute os cenários como estão em uma branch específica:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  --branch feature-payments \
  -e 1629989 \
  -r cli
Enter fullscreen mode Exit fullscreen mode

Debug de falha apenas no CI

Adicione --verbose:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e 1629989 \
  --verbose
Enter fullscreen mode Exit fullscreen mode

Compare a requisição enviada no CI com a execução local.

Resolução de problemas

Erro de autenticação

Possíveis causas:

  • token incorreto;
  • token expirado;
  • variável de ambiente não configurada;
  • segredo não disponível para aquele branch ou job.

Verifique se o segredo existe no CI e gere outro token na aba CI/CD do cenário, se necessário. Nunca imprima o token completo no log.

“Cenário não encontrado”

Verifique:

  • ID do cenário;
  • ID do projeto;
  • branch usada em --branch;
  • permissão do token.

A forma mais segura é copiar novamente o comando da aba CI/CD do cenário.

Passa localmente, falha no CI

Normalmente é diferença de ambiente:

  • -e aponta para outro ambiente;
  • variável ausente;
  • runner sem acesso de rede ao host;
  • certificado interno não confiável;
  • dados de teste diferentes.

Rode com:

--verbose
Enter fullscreen mode Exit fullscreen mode

E compare request/response.

Falha de TLS em hosts internos

Se o endpoint usa CA interna:

--ssl-extra-ca-certs ./internal-ca.pem
Enter fullscreen mode Exit fullscreen mode

Use -k apenas como último recurso em ambiente interno confiável.

A build continua verde mesmo com teste quebrado

Procure por comandos que escondem o erro:

apidog run ... || true
Enter fullscreen mode Exit fullscreen mode

Ou pipelines shell que descartam o exit code. O CI precisa receber diretamente o código de saída do apidog run.

Como encaixar a CLI no workflow da equipe

Um fluxo prático fica assim:

  1. Projete e depure endpoints no Apidog.
  2. Crie cenários com asserções.
  3. Gere o comando apidog run na aba CI/CD.
  4. Salve o token como segredo no CI.
  5. Execute os testes em pull requests, merges ou deploys.
  6. Publique relatórios html e junit.
  7. Deixe o código de saída bloquear o pipeline quando houver falha.

A vantagem é manter uma única fonte da verdade. O cenário visual no Apidog é o teste. A CLI apenas executa esse teste onde humanos não deveriam estar clicando: no pipeline.

Esse modelo evita manter uma versão visual e outra versão em script do mesmo teste. É uma das razões pelas quais equipes avaliam o Apidog como alternativa ao Postman para testes de API.

Se você ainda não tem cenários automatizados, comece criando um cenário simples, faça-o passar no Apidog e depois copie o comando da aba CI/CD. Você pode baixar o Apidog e configurar o primeiro teste no pipeline no mesmo dia.

Perguntas frequentes

A CLI do Apidog é gratuita?

A CLI é um pacote npm gratuito instalado com:

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

Ela executa cenários do seu projeto Apidog. 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?

Não. Você cria os cenários visualmente no Apidog e a CLI os executa por ID.

Qual é a diferença entre a CLI do Apidog e o Newman?

O Newman executa coleções Postman via linha de comando. A CLI do Apidog executa cenários de teste do Apidog. Os papéis são parecidos, mas cada ferramenta executa artefatos da sua própria plataforma. Veja CLI do Postman vs Newman.

Qual formato de relatório devo usar em CI?

Use junit para integração com dashboards de CI e html para relatório navegável como artefato:

-r html,junit
Enter fullscreen mode Exit fullscreen mode

Adicione cli se quiser saída legível no log:

-r cli,html,junit
Enter fullscreen mode Exit fullscreen mode

Como a CLI faz a build falhar?

Por código de saída. Se qualquer asserção falhar, apidog run retorna código diferente de zero. O CI marca a etapa como falha e bloqueia merge ou deploy.

Posso executar sem instalação global?

Sim:

npx apidog-cli run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t 605067 \
  -e 1629989
Enter fullscreen mode Exit fullscreen mode

Qual versão do Node.js é necessária?

Node.js v16 ou superior.

Onde encontro o token e o ID do cenário?

Na aba CI/CD do cenário de teste no Apidog. Gere o token, copie o comando completo e mova o token para um segredo do CI.

Top comments (0)