DEV Community

Cover image for Como Rodar Testes de API Apidog CLI no GitHub Actions (Workflow Completo)
Lucas
Lucas

Posted on • Originally published at apidog.com

Como Rodar Testes de API Apidog CLI no GitHub Actions (Workflow Completo)

Seus testes de API passam na sua máquina. Então alguém mescla uma alteração que quebra o endpoint de login, e o problema só aparece quando um cliente abre um ticket. Os testes existiam; eles apenas não rodaram no momento certo: na pull request, antes da mesclagem.

Experimente o Apidog hoje

A integração contínua fecha essa lacuna. Em vez de depender de execuções locais, você move os testes para um pipeline que roda automaticamente a cada push ou pull request. Para testes de API, o fluxo ideal é simples: um executor de linha de comando executa os cenários já criados, retorna sucesso ou falha e deixa o CI bloquear a build quando algo quebra.

Em resumo

  • O Apidog CLI é o pacote npm apidog-cli.
  • Instale com npm install -g apidog-cli ou execute via npx.
  • Rode cenários com apidog run.
  • O CLI executa os cenários criados no aplicativo Apidog por ID.
  • Você não precisa reescrever testes em código.
  • Um workflow mínimo do GitHub Actions precisa de:
    • checkout do repositório;
    • Node.js;
    • instalação do CLI;
    • execução de apidog run.
  • Quando uma asserção falha, o CLI retorna código de saída diferente de zero.
  • O GitHub Actions interpreta esse código como falha e bloqueia a PR.
  • O token de acesso deve ser salvo como segredo do GitHub Actions.
  • Use -r junit, -r html e if: always() para salvar relatórios mesmo quando os testes falharem.

Por que executar testes de API em CI?

Um teste que só roda quando alguém lembra de executá-lo não é uma barreira confiável. Execuções locais são úteis durante a criação do cenário, mas falham como processo de equipe: ambientes variam, dependências mudam e quase ninguém roda o pacote completo antes de cada push.

Com CI, cada pull request executa o mesmo trabalho em um runner limpo, contra o mesmo ambiente. Se um endpoint começa a retornar 500, se um contrato muda ou se uma asserção quebra, a PR mostra a falha antes da mesclagem.

Testes de API funcionam bem como porta de qualidade porque são rápidos e objetivos. Um cenário envia requisições reais, valida status codes, headers e corpos de resposta, e termina com sucesso ou falha. Não há navegador, renderização ou estado visual instável.

Se você quiser revisar os conceitos gerais, veja o guia sobre o que é CI/CD e como funciona.

O que o Apidog CLI faz

O ponto principal: você não escreve código de teste para o CLI.

Você cria os cenários no aplicativo Apidog, com requisições, asserções, variáveis de ambiente e dados de teste. O CLI atua como executor. Com um ID de cenário e um token de acesso, ele busca o cenário no projeto Apidog e o executa passo a passo.

O resultado é:

  • saída no terminal;
  • relatórios opcionais;
  • código de saída de sucesso ou falha.

Isso simplifica o CI. Em vez de manter uma versão dos testes no aplicativo e outra em código, o pipeline roda o mesmo cenário que a equipe já mantém no Apidog. Se você atualiza uma asserção no editor visual, a próxima execução do CI já usa essa versão.

O binário é apidog, distribuído pelo pacote npm apidog-cli. O comando base é:

apidog run
Enter fullscreen mode Exit fullscreen mode

Para um fluxo de automação mais amplo, veja também o guia sobre integrar o Apidog CLI com Claude Skills para automação de testes de API.

Pré-requisitos

Antes de criar o workflow, você precisa de três informações:

  1. Um cenário de teste

    • Crie no aplicativo Apidog.
    • Pode ser algo simples, como login e busca de perfil.

  2. ID do cenário e ID do ambiente

    • O ID do cenário define o que será executado.
    • O ID do ambiente define onde será executado: desenvolvimento, staging ou produção.

  3. Token de acesso

    • Autentica o CLI para buscar e executar o cenário.

A forma mais prática de obter tudo é pela guia CI/CD do cenário no Apidog. Abra o cenário, acesse a guia CI/CD, escolha a opção de linha de comando e gere um token de acesso. O Apidog monta um comando apidog run com:

  • --access-token;
  • -t, para o ID do cenário;
  • -e, para o ID do ambiente.

Copie esse comando. Ele será a base do seu workflow.

Trate o token como senha. Nunca comite o token no repositório.

Passo 1: salve o token como segredo do GitHub

No GitHub, abra o repositório e vá para:

Settings > Secrets and variables > Actions > New repository secret
Enter fullscreen mode Exit fullscreen mode

Crie o segredo:

Name: APIDOG_ACCESS_TOKEN
Secret: cole o token gerado pelo Apidog
Enter fullscreen mode Exit fullscreen mode

No workflow, você vai referenciar esse segredo assim:

${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

E passá-lo para o CLI via env::

env:
  APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

O ID do cenário e o ID do ambiente não precisam ser tratados como segredo. Apenas o token precisa de proteção.

Se vários repositórios usarem o mesmo projeto Apidog, considere criar o segredo no nível da organização e liberar acesso apenas aos repositórios necessários.

Passo 2: crie o workflow mínimo

Crie o arquivo:

.github/workflows/api-tests.yml
Enter fullscreen mode Exit fullscreen mode

Use este workflow como base:

name: Testes de API

on:
  pull_request:
    branches: [main]

jobs:
  api-tests:
    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 Apidog CLI
        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 \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Substitua:

  • 605067 pelo ID do seu cenário;
  • 1629989 pelo ID do seu ambiente.

Agora comite o arquivo e abra uma pull request. O GitHub Actions vai:

  1. iniciar um runner Ubuntu;
  2. instalar Node.js 20;
  3. instalar o Apidog CLI;
  4. executar o cenário;
  5. marcar a verificação como verde ou vermelha.

Se qualquer asserção falhar, apidog run retorna código diferente de zero. O GitHub Actions interpreta isso como falha da etapa e mostra um X vermelho na PR.

Alternativa com npx

Se você não quiser instalar o CLI globalmente no runner, use npx:

- name: Executar cenário de teste de API
  run: npx apidog-cli run --access-token "$APIDOG_ACCESS_TOKEN" -t 605067 -e 1629989 -r cli
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

As duas abordagens executam o mesmo cenário.

Passo 3: publique relatórios úteis

Uma verificação vermelha informa que algo falhou. O relatório informa por quê.

O parâmetro -r ou --reporters define os formatos de saída. Ele aceita:

  • cli;
  • html;
  • json;
  • junit.

Para CI, os formatos mais úteis são:

  • junit: XML compatível com ferramentas de relatório de teste;
  • html: relatório navegável para baixar e abrir no navegador;
  • cli: saída legível no log do job.

Atualize a etapa de execução para gerar relatórios:

- 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,cli \
      --out-dir ./apidog-reports
  env:
    APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

- name: Carregar relatório de teste
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: apidog-report
    path: ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

Pontos importantes:

  • --out-dir ./apidog-reports define onde os relatórios serão gravados.
  • actions/upload-artifact@v4 salva esse diretório como artefato.
  • if: always() garante upload mesmo quando os testes falham.

Sem if: always(), o GitHub pode pular a etapa de upload após uma falha, justamente quando você mais precisa do relatório.

A flag -n 1 define o número de iterações. Aumente esse valor se quiser executar o cenário várias vezes.

Passo 4: use o ambiente certo para cada evento

Uma pull request normalmente deve testar contra staging. Um push para main, depois do deploy, pode executar um smoke test contra produção.

Você pode usar o mesmo cenário e alterar apenas o ID do ambiente com -e.

Exemplo com dois jobs:

name: Testes de API

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  verificacao-pr:
    if: github.event_name == 'pull_request'
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g apidog-cli

      - name: Testar staging
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1629989 \
            -r junit,cli \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: staging-report
          path: ./apidog-reports

  smoke-test-producao:
    if: github.event_name == 'push'
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g apidog-cli

      - name: Smoke test de produção
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e 1730055 \
            -r cli \
            --on-error end
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Neste exemplo:

  • 1629989 é o ambiente de staging;
  • 1730055 é o ambiente de produção;
  • a PR executa uma validação mais completa;
  • o push em main executa um smoke test mais enxuto.

A flag --on-error controla o comportamento após uma falha:

  • end: para na primeira falha;
  • continue: executa as etapas restantes e mostra todas as falhas;
  • ignore: ignora falhas em etapas específicas.

Mesmo com comportamentos diferentes, a execução retorna código diferente de zero se houver falha relevante.

Indo além: matriz, pastas e dados de teste

Depois que o workflow básico estiver funcionando, você pode expandir a cobertura com poucas alterações.

Executar uma pasta inteira

Em vez de executar um único cenário com -t, execute todos os cenários de uma pasta:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" -f <folderId> -e <environmentId>
Enter fullscreen mode Exit fullscreen mode

Ou execute uma suíte de testes:

apidog run --access-token "$APIDOG_ACCESS_TOKEN" --test-suite <testSuiteId> -e <environmentId>
Enter fullscreen mode Exit fullscreen mode

Suítes são úteis quando você quer uma sequência específica de cenários em um único job lógico. Veja o guia sobre escalar testes automatizados de API com suites de teste.

Testar vários ambientes em paralelo

Use uma matriz do GitHub Actions:

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

    strategy:
      matrix:
        env-id: [1629989, 1730055]

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'

      - run: npm install -g apidog-cli

      - name: Executar cenário contra ${{ matrix.env-id }}
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t 605067 \
            -e ${{ matrix.env-id }} \
            -r cli
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

O GitHub cria um runner para cada valor da matriz. Assim, staging e produção podem ser testados em paralelo.

Executar testes orientados a dados

Use -d para passar um arquivo CSV ou JSON:

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

Isso permite validar o mesmo cenário com várias entradas sem criar dezenas de cenários duplicados.

Executar contra um branch do Apidog

Se sua equipe usa branches no Apidog, use:

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

Assim, uma PR pode testar os cenários definidos em um branch específico.

Solução de problemas comuns

O job está verde, mas deveria falhar

Verifique se o código de saída do apidog run está chegando ao GitHub Actions.

Evite padrões como:

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

Isso mascara a falha e faz o job passar. O comando apidog run deve ser o último comando relevante da etapa ou rodar sozinho.

A autenticação falha

Confirme se o nome do segredo está consistente:

env:
  APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
Enter fullscreen mode Exit fullscreen mode

Verifique também se:

  • o segredo existe em Settings > Secrets and variables > Actions;
  • o token não foi regenerado no Apidog;
  • o valor não foi colado com espaços extras.

Passa localmente, falha no CI

Adicione --verbose temporariamente:

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

Isso ajuda a comparar requisições e respostas entre sua máquina e o runner do CI. Diferenças comuns incluem:

  • variável de ambiente ausente;
  • base URL diferente;
  • dados de staging desatualizados;
  • serviço inacessível a partir do runner.

Os relatórios não aparecem como artefatos

Confira se o diretório é o mesmo nos dois pontos:

--out-dir ./apidog-reports
Enter fullscreen mode Exit fullscreen mode 
path: ./apidog-reports
Enter fullscreen mode Exit fullscreen mode

E confirme que o upload usa:

if: always()
Enter fullscreen mode Exit fullscreen mode

O runner não consegue acessar a API

Se staging ou produção estiverem atrás de firewall, VPN ou rede privada, runners públicos do GitHub não conseguirão acessar a API.

Opções comuns:

  • usar um runner auto-hospedado dentro da rede;
  • liberar os IPs do GitHub Actions;
  • expor um ambiente de staging acessível apenas para CI.

Comparação com alternativas

Você pode escrever testes de API como código usando um framework e chamá-los no GitHub Actions. Isso funciona, mas cria outra camada para manter: os testes em código precisam continuar sincronizados com a API e com os cenários que a equipe documenta ou valida em outra ferramenta.

Também é possível usar curl em scripts shell. Para uma verificação simples de saúde, funciona. Para múltiplos endpoints, ambientes, asserções e relatórios, a manutenção cresce rápido.

Com o Apidog CLI, o cenário mantido no aplicativo é o mesmo que roda no CI. O pipeline só precisa executar o comando e respeitar o código de saída.

O GitHub Actions também não é obrigatório. O mesmo comando apidog run pode ser usado em GitLab CI, Jenkins, CircleCI ou qualquer executor que rode shell e leia códigos de saída.

Para fluxos multiplataforma, veja o guia para automatizar testes de API em CI/CD. Se você usa Jenkins, veja o passo a passo para integrar testes automatizados do Apidog com Jenkins.

Para criar os cenários que serão executados, baixe o Apidog, configure seus testes no aplicativo e copie o comando CLI pela guia CI/CD do cenário.

Conclusão

A configuração é pequena:

  1. crie um cenário no Apidog;
  2. gere um token de acesso;
  3. salve o token como segredo do GitHub;
  4. adicione um workflow com apidog run;
  5. publique relatórios como artefatos.

Depois disso, cada pull request executa os testes automaticamente. Se um endpoint quebrar, a verificação falha antes da mesclagem. Se você precisar investigar, o relatório fica disponível nos artefatos da execução.

A divisão de responsabilidades é o que mantém o fluxo simples: o Apidog mantém os cenários, o CLI executa os testes e o GitHub Actions aplica o bloqueio pela saída do comando. Não há duplicação de testes nem sincronização manual entre ferramenta visual e código de pipeline.

Top comments (0)