Lucas

Posted on Jun 15 • Originally published at apidog.com

12 Melhores Práticas de CI/CD para Testes de API Automatizados

Um pipeline verde que entrega uma API quebrada é pior do que pipeline nenhum. Ele informa à equipe que está tudo bem até um cliente abrir um chamado. O problema geralmente não é falta de testes, mas testes que deixam de ser confiáveis: poucos endpoints cobertos, falhas intermitentes, continue-on-error permanente e uma suíte que roda sem bloquear nada.

Experimente o Apidog hoje

A solução é tratar testes de API em CI como parte do contrato da API: versionáveis, executáveis por comando e capazes de falhar o pipeline quando o contrato quebra. Este guia mostra 12 práticas para configurar isso em GitHub Actions, GitLab CI, Jenkins ou qualquer executor.

O fluxo usado nos exemplos é com Apidog: você projeta a especificação, cria asserções visualmente e executa a suíte em modo headless com o Apidog CLI.

Se CI/CD ainda é novo para você, a versão curta é: CI executa testes a cada commit ou pull request; CD promove builds aprovadas para deploy. Há uma explicação mais completa em O que é CI/CD e como funciona.

1. Coloque os testes de API no pipeline

Um teste executado manualmente antes do release é checklist, não rede de segurança. Para bloquear regressões cedo, rode a suíte automaticamente em pull requests.

Exemplo mínimo com GitHub Actions:

name: API Tests

on:
  pull_request:
    branches: [main]

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

    steps:
      - uses: actions/checkout@v4

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

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

      - name: Run API test suite
        run: |
          apidog run \
            --access-token "$APIDOG_ACCESS_TOKEN" \
            -t "$SCENARIO_ID" \
            -e "$APIDOG_ENV_ID" \
            -r cli,junit \
            --out-dir ./test-results
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}
          SCENARIO_ID: ${{ vars.SCENARIO_ID }}
          APIDOG_ENV_ID: ${{ vars.APIDOG_ENV_ID }}

O CLI retorna 0 quando todas as asserções passam e código diferente de zero quando alguma falha. Isso já faz o job ficar vermelho.

Veja também: Como Automatizar Testes de API no GitHub Actions.

2. Mantenha o comando portátil entre provedores de CI

Evite acoplar a suíte de API a plugins específicos de um provedor. O ideal é que qualquer executor consiga rodar os testes com o mesmo comando shell:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID" \
  -r cli,junit

No GitLab CI, por exemplo:

api-tests:
  image: node:20
  script:
    - npm install -g apidog-cli
    - apidog run --access-token "$APIDOG_ACCESS_TOKEN" -t "$SCENARIO_ID" -e "$ENV_ID" -r cli,junit
  artifacts:
    when: always
    reports:
      junit: ./test-results/*.xml

Ao migrar de GitHub Actions para GitLab, Jenkins ou outro executor, você muda o invólucro do pipeline, não a suíte.

Para Jenkins, veja: Como Integrar Testes Automatizados Apidog com Jenkins para CI/CD.

3. Faça asserções sobre comportamento, não só status code

Um teste que verifica apenas 200 OK pode passar mesmo quando a API retorna:

array vazio;
moeda errada;
campo null onde deveria haver objeto;
payload incompatível com o contrato.

Prefira asserções sobre estrutura e conteúdo. Em uma busca de pedido, por exemplo, valide:

status 200;
order.total é número;
currency corresponde ao valor esperado;
items não está vazio;
campos obrigatórios existem.

Boas regras:

valide contrato, não dados voláteis;
use uma preocupação por asserção;
teste caminhos negativos, como 400, 401 e 403.

Mais detalhes: asserções de API.

4. Gerencie ambientes e segredos como configuração

URLs base, tokens, tenants e credenciais mudam entre local, staging e produção. Não coloque esses valores hardcoded em cenários ou arquivos versionados.

Use variáveis e ambientes:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$STAGING_ENV_ID" \
  -r cli,junit

Boas práticas:

armazene APIDOG_ACCESS_TOKEN em GitHub Secrets, GitLab CI/CD Variables ou gerenciador de credenciais;
use IDs de ambiente diferentes para staging e produção;
mantenha o mesmo cenário e altere apenas -e;
nunca versionar tokens.

5. Torne os testes determinísticos

Teste instável destrói a confiança no pipeline. Se a suíte “às vezes falha”, desenvolvedores começam a reexecutar até ficar verde.

Principais causas de instabilidade:

Estado compartilhado: dois testes usam o mesmo e-mail, usuário ou tenant.
Dependência de ordem: um teste só passa se outro rodou antes.
Tempo fixo: sleep 10 em vez de consultar até a condição estar pronta.
Serviços externos instáveis: sandbox de pagamento, API de terceiros ou upstream fora do controle da equipe.

Como corrigir:

gere dados únicos por execução;
limpe os dados ao final do teste;
use polling para operações assíncronas;
simule dependências externas quando possível;
garanta que os testes passem em qualquer ordem.

6. Mantenha a etapa de API rápida

Uma suíte de 20 minutos em cada pull request será ignorada ou desativada. Para PRs, tente manter a etapa abaixo de cinco minutos.

Estratégias práticas:

rode smoke tests em PRs;
rode regressão completa no merge ou à noite;
paralelize cenários independentes;
faça cache da instalação do CLI;
em PRs, falhe rápido;
em execuções noturnas, continue após falhas para coletar mais sinais.

Exemplo com smoke tests em PR e regressão completa agendada:

on:
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 2 * * *'

jobs:
  api-tests:
    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: Run suite
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            apidog run \
              --access-token "$APIDOG_ACCESS_TOKEN" \
              -t "$SMOKE_ID" \
              -e "$ENV_ID" \
              -r cli,junit \
              --out-dir ./test-results
          else
            apidog run \
              --access-token "$APIDOG_ACCESS_TOKEN" \
              -t "$FULL_ID" \
              -e "$ENV_ID" \
              -r cli,junit \
              --on-error continue \
              --out-dir ./test-results
          fi
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

7. Publique resultados legíveis por máquina

Logs de console não bastam. Quando uma build falha, o time precisa saber:

qual cenário falhou;
qual request falhou;
qual asserção quebrou;
qual entrada causou o problema.

Use JUnit XML, formato suportado pela maioria dos servidores CI:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID" \
  -r cli,html,junit \
  --out-dir ./test-results

Esse comando gera:

cli: saída no console;
html: relatório navegável;
junit: resultado estruturado para o CI.

Publique os artefatos mesmo em falhas:

- name: Publish test report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: api-test-results
    path: ./test-results

O if: always() é importante: quando o teste falha, o relatório é ainda mais necessário.

8. Bloqueie merges com proteção de branch

Um teste que falha mas não bloqueia merge é apenas uma notificação.

Configure duas coisas:

o job precisa falhar com código diferente de zero;
a verificação precisa ser obrigatória na branch principal.

No GitHub, marque o job de testes de API como required status check em main. No GitLab e Bitbucket, use a configuração equivalente de merge request.

Resultado esperado:

push → testes → falha → merge bloqueado → correção → testes verdes → merge liberado

Isso transforma a suíte em uma regra aplicada pela plataforma, não em uma sugestão.

9. Gere cobertura a partir da especificação da API

Manter testes sincronizados manualmente com a API é caro. Cada endpoint novo exige cenário novo; cada campo alterado exige asserção atualizada.

Se você usa OpenAPI, gere o esqueleto da coleção a partir da especificação. Assim, a suíte já parte dos endpoints documentados e valida se a implementação continua compatível com o contrato.

No Apidog, especificação e testes ficam no mesmo workspace, permitindo criar cenários a partir dos endpoints documentados.

Guia relacionado: Como Gerar Coleções de Teste de API a Partir de Especificações OpenAPI.

Você ainda deve escrever asserções de negócio manualmente, mas não precisa reescrever o básico: endpoint existe, aceita os parâmetros esperados e retorna a estrutura documentada.

10. Use testes orientados a dados

Um mesmo endpoint pode precisar cobrir várias entradas:

pedido válido;
pedido acima do limite;
SKU inexistente;
moeda não suportada;
payload incompleto.

Em vez de duplicar cenários, execute o mesmo fluxo contra uma tabela de dados:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID" \
  -d ./test-data/orders.csv \
  -r cli,junit \
  --out-dir ./test-results

Cada linha de orders.csv vira uma iteração. O relatório mostra quais entradas falharam.

Esse padrão é útil para:

validação de payload;
regras de preço;
limites de negócio;
permissões;
combinações de parâmetros.

Veja: testes de API orientados a dados com CSV ou JSON.

11. Execute smoke tests pós-deploy

Testes em staging validam a build. Eles não garantem que o deploy funcionou.

Problemas que só aparecem após deploy:

variável de ambiente ausente;
rota mal configurada;
certificado expirado;
balanceador apontando para versão errada;
configuração diferente da esperada.

Adicione um job pós-deploy contra o ambiente real:

smoke-after-deploy:
  needs: deploy
  runs-on: ubuntu-latest

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

    - run: npm install -g apidog-cli

    - name: Smoke test production
      run: |
        apidog run \
          --access-token "$APIDOG_ACCESS_TOKEN" \
          -t "$SMOKE_SCENARIO_ID" \
          -e "$PROD_ENV_ID" \
          -r cli,junit \
          --out-dir ./smoke-results
      env:
        APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

Em deploy blue-green ou canary, rode o smoke test contra a nova versão antes de direcionar tráfego real.

12. Trate a suíte como código

Uma suíte de testes de API não é algo que você configura uma vez e esquece. Ela precisa evoluir junto com a API.

Hábitos úteis:

adicione testes no mesmo PR da funcionalidade;
trate teste instável como bug;
não deixe continue-on-error permanente;
revise endpoints sem cobertura;
mantenha YAML, dados de teste e configuração em controle de versão;
remova cenários obsoletos.

Como as definições de teste ficam no Apidog e o pipeline chama apenas apidog run, a configuração de CI permanece pequena. O esforço principal deve estar em melhorar cobertura e asserções.

Veja também: Conjuntos de Testes Apidog: Uma Maneira Mais Inteligente de Automatizar Testes de API.

Juntando tudo

As práticas se reforçam:

comando portátil facilita rodar testes em qualquer CI;
ambientes configuráveis permitem smoke tests pós-deploy;
testes determinísticos viabilizam paralelismo;
relatórios JUnit tornam falhas acionáveis;
proteção de branch impede merges quebrados;
especificação e dados reduzem manutenção manual.

O fluxo base é simples:

apidog run \
  --access-token "$APIDOG_ACCESS_TOKEN" \
  -t "$SCENARIO_ID" \
  -e "$ENV_ID" \
  -r cli,junit \
  --out-dir ./test-results

Comece pequeno:

escolha um fluxo crítico;
crie asserções reais;
rode no pull request;
publique relatório;
torne o status check obrigatório;
expanda para smoke tests, regressão completa e dados externos.

Um pipeline confiável fica vermelho quando algo realmente quebrou e verde quando é seguro seguir. Baixe o Apidog e crie o primeiro cenário.

FAQ

Qual a diferença entre testes de API em CI e CI/CD?

CI executa testes automaticamente em commits ou pull requests para capturar regressões cedo. CD promove uma build aprovada para deploy. Testes de API entram nos dois pontos: antes do merge e após o deploy com smoke tests.

O mesmo Apidog CLI pode ser usado nas duas etapas.

Preciso escrever código para executar testes de API no pipeline?

Não necessariamente. Você cria requisições e asserções visualmente no Apidog e executa tudo com:

apidog run

O pipeline precisa apenas instalar o CLI e chamar o comando. Veja: Como Automatizar Testes de API em CI/CD.

Como evito testes de API instáveis em CI?

Priorize:

dados isolados por teste;
limpeza de estado;
polling em vez de sleeps fixos;
mocks para dependências externas instáveis;
cenários independentes de ordem.

A meta é que a suíte passe em qualquer execução e em qualquer ordem.

Como faço um teste de API com falha bloquear merge?

Você precisa de duas configurações:

o executor deve retornar código diferente de zero em falhas;
o job deve ser obrigatório nas regras de proteção da branch.

O Apidog CLI já retorna erro quando uma asserção falha. Depois, basta marcar o job como required status check no host Git.

Posso rodar os mesmos testes no GitHub Actions, GitLab e Jenkins?

Sim. A lógica dos testes fica no Apidog, e o CI apenas chama apidog run. O comando é o mesmo; muda apenas o YAML ou script do executor.

Para GitHub Actions, veja: Como Automatizar Testes de API no GitHub Actions.

Quão rápida deve ser minha etapa de teste de API?

Para pull requests, tente manter abaixo de cinco minutos. Use smoke tests em PRs, regressão completa em execução agendada, paralelismo e cache da instalação do CLI.

DEV Community