DEV Community

Cover image for Apidog CLI para CI/CD: Pipeline Copia e Cola para Automação de Testes de API
Lucas
Lucas

Posted on • Originally published at apidog.com

Apidog CLI para CI/CD: Pipeline Copia e Cola para Automação de Testes de API

Você escreveu testes de API, eles passam localmente, mas só protegem o produto quando alguém lembra de executá-los. O próximo passo é colocar esses testes no CI: a cada push ou pull request, o pipeline roda os cenários, publica relatórios e falha automaticamente quando uma asserção quebra.

Experimente o Apidog hoje

A forma prática de fazer isso é executar os cenários do Apidog via CLI. Você continua criando e mantendo os cenários visualmente no Apidog, mas executa tudo em modo headless com um comando que qualquer runner com Node.js consegue rodar.

Este guia mostra arquivos prontos para GitHub Actions, GitLab CI, Jenkins, CircleCI e Azure Pipelines. Troque os IDs, salve o token como segredo e publique os relatórios no formato certo. Para uma visão mais ampla da estratégia, veja como automatizar testes de API em CI/CD.

O que você vai configurar

O CLI do Apidog é o pacote npm apidog-cli. Ele executa cenários de teste criados no Apidog, incluindo:

  • requisições encadeadas;
  • asserções;
  • extração de valores de uma resposta para a próxima requisição;
  • iterações com dados externos;
  • execução por cenário, pasta ou suíte.

O ponto principal para CI/CD é o código de saída:

  • 0: todos os testes passaram;
  • diferente de 0: alguma etapa ou asserção falhou.

Ou seja: o próprio comando apidog run vira o gate do pipeline. Se ele falhar, a etapa falha, o PR fica vermelho e o merge ou deploy é bloqueado.

Você precisa de três informações:

  1. Token de acesso

    Deve ser salvo como segredo do CI. Nunca commite esse valor.

  2. ID do cenário, pasta ou suíte

    Define o que será executado.

  3. ID do ambiente

    Define contra qual ambiente os testes vão rodar: desenvolvimento, staging ou produção.

No Apidog, abra o cenário de teste, vá até a aba CI/CD, escolha a opção de linha de comando e gere o comando apidog run. O Apidog já inclui os IDs necessários. Depois, mova o token para um segredo do seu CI.

Se você ainda não criou um cenário, comece por como escrever cenários de teste com o Apidog.

Comando base

Todos os exemplos abaixo usam esta estrutura:

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

Onde:

  • --access-token $APIDOG_ACCESS_TOKEN: usa o token salvo como variável de ambiente.
  • -t 605067: executa o cenário com esse ID.
  • -f <folderId>: alternativa para executar uma pasta inteira.
  • --test-suite <id>: alternativa para executar uma suíte.
  • -e 1629989: seleciona o ambiente.
  • -n 1: executa uma vez.
  • -d <file>: permite iterar usando CSV ou JSON.
  • -r html,junit: gera relatórios HTML e JUnit.
  • --out-dir ./apidog-reports: define o diretório de saída.

Use junit para integração com dashboards de CI. Use html para salvar um relatório navegável como artefato da build. Adicione cli se quiser saída legível no log.

GitHub Actions

Crie o arquivo .github/workflows/api-tests.yml:

name: API tests

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

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

      - name: Run API test scenario
        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: Upload report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: apidog-report
          path: ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Configuração necessária:

  1. Vá em Settings → Secrets and variables → Actions.
  2. Crie o segredo APIDOG_ACCESS_TOKEN.
  3. Substitua 605067 e 1629989 pelos IDs gerados no Apidog.

O if: always() garante que o relatório seja enviado mesmo quando os testes falharem. Para um guia específico da plataforma, veja como automatizar testes de API no GitHub Actions.

GitLab CI

Crie ou atualize .gitlab-ci.yml:

stages:
  - test

api-tests:
  stage: test
  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

Configuração necessária:

  1. Vá em Settings → CI/CD → Variables.
  2. Crie APIDOG_ACCESS_TOKEN.
  3. Marque como variável mascarada e, se aplicável, protegida.

O bloco abaixo é essencial:

reports:
  junit: apidog-reports/*.xml
Enter fullscreen mode Exit fullscreen mode

Ele permite que o GitLab leia o XML JUnit e mostre as falhas diretamente no merge request.

Jenkins

Exemplo com pipeline declarativo:

pipeline {
  agent any

  environment {
    APIDOG_ACCESS_TOKEN = credentials('apidog-access-token')
  }

  stages {
    stage('API tests') {
      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

Configuração necessária:

  1. Salve o token como credencial Jenkins com o ID apidog-access-token.
  2. Garanta que o agente tenha Node.js disponível.
  3. Substitua os IDs do cenário e ambiente.

Se seus agentes já tiverem o CLI instalado ou cacheado, remova:

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

O Apidog também tem um guia dedicado para integrar testes automatizados do Apidog com Jenkins para CI/CD.

CircleCI

Crie .circleci/config.yml:

version: 2.1

jobs:
  api-tests:
    docker:
      - image: cimg/node:20.11

    steps:
      - checkout

      - run:
          name: Install Apidog CLI
          command: npm install -g apidog-cli

      - run:
          name: Run API test scenario
          command: |
            apidog run \
              --access-token "$APIDOG_ACCESS_TOKEN" \
              -t 605067 \
              -e 1629989 \
              -r junit,cli \
              --out-dir ./apidog-reports

      - store_test_results:
          path: ./apidog-reports

      - store_artifacts:
          path: ./apidog-reports
          destination: apidog-reports

workflows:
  test:
    jobs:
      - api-tests
Enter fullscreen mode Exit fullscreen mode

Configuração necessária:

  1. Vá em Project Settings → Environment Variables.
  2. Crie APIDOG_ACCESS_TOKEN.
  3. Ajuste os IDs de cenário e ambiente.

Use:

store_test_results:
  path: ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

para que o CircleCI interprete os relatórios JUnit. Use store_artifacts para manter o HTML disponível na página da build.

Azure Pipelines

Crie azure-pipelines.yml:

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - task: NodeTool@0
    inputs:
      versionSpec: '20.x'
    displayName: 'Install Node.js'

  - script: npm install -g apidog-cli
    displayName: 'Install Apidog CLI'

  - script: |
      apidog run \
        --access-token "$APIDOG_ACCESS_TOKEN" \
        -t 605067 \
        -e 1629989 \
        -r junit,html \
        --out-dir ./apidog-reports
    displayName: 'Run API test scenario'
    env:
      APIDOG_ACCESS_TOKEN: $(APIDOG_ACCESS_TOKEN)

  - task: PublishTestResults@2
    condition: always()
    inputs:
      testResultsFormat: 'JUnit'
      testResultsFiles: 'apidog-reports/*.xml'
      testRunTitle: 'Apidog API tests'
Enter fullscreen mode Exit fullscreen mode

Configuração necessária:

  1. Crie APIDOG_ACCESS_TOKEN como variável secreta do pipeline.
  2. Opcionalmente, use um grupo de variáveis conectado ao Azure Key Vault.
  3. Mapeie o valor via env, como no exemplo.

A tarefa PublishTestResults@2 com condition: always() publica os resultados mesmo quando apidog run falha.

Padrões úteis para CI/CD

1. Teste de fumaça 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

Use --on-error end quando quiser falhar rápido.

2. Regressão completa durante a noite

Execute uma pasta inteira em uma job agendada:

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

Use --on-error continue para coletar todas as falhas em um único relatório.

3. Execução com dados externos

Use CSV ou JSON para rodar o mesmo cenário com várias entradas:

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

4. Teste em um branch específico

Execute o cenário como ele existe em um branch:

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

5. Debug de falha apenas no CI

Quando passa localmente, mas falha no runner:

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

O --verbose ajuda a comparar a requisição enviada pelo CI com a requisição enviada localmente.

Problemas comuns

A build continua verde quando deveria falhar

Verifique se você não está mascarando o código de saída:

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

ou usando um pipeline de shell que ignora falhas.

O CI precisa ler diretamente o exit code de apidog run.

Erro de autenticação

Possíveis causas:

  • token expirado;
  • token copiado incorretamente;
  • variável de ambiente não configurada;
  • segredo indisponível para branches ou forks.

Para diagnosticar, valide se a variável existe sem imprimir o valor:

echo ${#APIDOG_ACCESS_TOKEN}
Enter fullscreen mode Exit fullscreen mode

“Cenário não encontrado”

Verifique:

  • ID do cenário;
  • ID da pasta ou suíte;
  • projeto correto;
  • branch correto;
  • comando copiado da aba CI/CD mais recente.

Passa localmente, falha no CI

Normalmente é diferença de ambiente:

  • -e aponta para outro ambiente;
  • o runner não acessa o host por firewall/VPN;
  • variáveis necessárias não existem no CI;
  • certificados ou DNS internos não estão disponíveis.

Rode com --verbose e compare requisição, URL, headers e resposta.

Falhas TLS em hosts internos

Se o endpoint usa uma CA interna, prefira configurar o certificado CA adicional. Use -k para ignorar verificação SSL apenas como último recurso em hosts internos confiáveis com certificado autoassinado. Não use isso contra endpoints públicos.

Por que criar visualmente e executar em modo headless

Com executores baseados em script, o teste e a execução costumam estar no mesmo arquivo. Isso funciona, mas também pode criar duplicação e manutenção extra.

No Apidog, o cenário criado no projeto é o teste. O CLI apenas executa esse cenário no CI. Assim, você mantém uma única fonte da verdade: o mesmo fluxo que foi depurado visualmente é executado automaticamente no pipeline.

Esse modelo é um dos motivos pelos quais times consideram o Apidog uma alternativa ao Postman para testes de API quando precisam integrar testes ao CI. Independentemente da ferramenta, o que realmente sustenta o gate são boas asserções de API.

O fluxo final fica assim:

  1. Projete e depure as requisições no Apidog.
  2. Encadeie as requisições em um cenário.
  3. Adicione asserções.
  4. Copie o comando apidog run da aba CI/CD.
  5. Salve o token como segredo do CI.
  6. Publique relatórios JUnit e HTML.
  7. Bloqueie merges ou deploys quando uma asserção falhar.

Se seus testes ainda dependem de alguém abrir uma ferramenta manualmente, mova-os para o pipeline. Crie um cenário, faça-o passar, copie o comando apidog run e use o bloco correspondente à sua plataforma.

Perguntas frequentes

O CLI do Apidog é gratuito para usar em CI?

O CLI é um pacote npm gratuito:

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

Ele 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 cenários visualmente no Apidog e o CLI os executa por ID. O cenário é o teste; o CLI é o executor.

Como um teste que falha quebra minha build?

Pelo código de saída. Quando uma asserção falha, apidog run sai com código diferente de zero. O CI interpreta isso como falha da etapa.

Qual formato de relatório devo usar?

Use junit para integração com o CI e html para análise manual.

Exemplo comum:

-r junit,html
Enter fullscreen mode Exit fullscreen mode

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

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

Preciso instalar o aplicativo Apidog no servidor de CI?

Não. O runner precisa apenas de Node.js e do pacote apidog-cli. Não há GUI, aplicativo desktop ou licença local na máquina de CI.

Posso executar sem instalação global?

Sim:

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

Isso é útil em runners efêmeros.

Qual a diferença entre isso e o Newman?

O Newman executa coleções Postman pela linha de comando. O CLI do Apidog executa cenários de teste do Apidog. As funções são parecidas, mas cada executor roda artefatos da sua própria ferramenta. Veja Postman CLI vs Newman para o lado Postman dessa comparação.

Onde consigo o token e os IDs?

Na aba CI/CD do cenário de teste no Apidog. Gere o token, copie o comando apidog run e depois mova o token para um segredo de CI, referenciando-o como:


bash
$APIDOG_ACCESS_TOKEN
Enter fullscreen mode Exit fullscreen mode

Top comments (0)