Lucas

Posted on Jun 15 • Originally published at apidog.com

Como Configurar Testes de API Automatizados Diários no GitHub Actions, GitLab e Jenkins

Seus testes de API passam em cada pull request, a build fica verde e você faz deploy. Horas depois, alguém em outro fuso horário relata um erro 500 no checkout — sem nenhuma alteração recente no código desse fluxo. O problema pode ter vindo de um sandbox de pagamento, uma migração noturna, um token expirado ou uma mudança de contrato em um serviço externo. Testes por commit não detectam isso porque nada mudou no seu repositório.

Experimente o Apidog hoje

Uma build noturna fecha essa lacuna: ela executa uma regressão completa, em horário agendado, contra ambientes reais ou próximos da produção. Para APIs, isso ajuda a detectar desvio de dados, integrações instáveis, credenciais expiradas, regressões de performance e quebras de contrato antes que usuários encontrem o problema.

Neste guia, você vai configurar uma regressão noturna de API com Apidog, Apidog CLI e pipelines agendados no GitHub Actions, GitLab CI/CD e Jenkins.

Por que testes por commit não são suficientes

Testes por commit respondem:

“Essa mudança de código quebrou algo?”

Uma build noturna responde:

“O sistema continua saudável agora, mesmo sem mudança de código?”

Essa diferença importa porque APIs dependem de várias partes móveis fora do commit atual:

Dependências externas: gateways de pagamento, APIs de terceiros e sandboxes podem mudar comportamento.
Dados alterados fora do deploy: ETLs, migrações e cargas de conteúdo podem quebrar fluxos.
Credenciais expiradas: tokens OAuth, certificados TLS e chaves de API têm ciclo de vida próprio.
Performance degradada: um endpoint que sai de 200 ms para 1.2 s pode continuar funcional, mas já está regredindo.
Suites completas são lentas: a regressão com centenas de casos não deve bloquear todo pull request.

O padrão recomendado é usar dois níveis:

Smoke tests rápidos em cada commit.
Regressão completa noturna com fluxos críticos, contratos, erros e limites de performance.

O que colocar em uma regressão noturna de API

Antes de criar o job agendado, defina o que a suite deve validar.

Inclua:

Jornadas críticas ponta a ponta

Exemplo: cadastro → login → criação de recurso → leitura → atualização → exclusão.
Autenticação e autorização

Teste login válido, token expirado, ausência de credenciais e permissões por papel.
Validação de contrato

Compare respostas com o schema OpenAPI para detectar campos removidos, tipos alterados ou payloads incompatíveis. Para entender esse problema, veja por que a documentação e as coleções do Swagger continuam divergindo.
Casos de erro

Valide 400, 401, 404, 429 e outros caminhos não felizes.
Consistência de dados entre requisições

Crie um recurso e confirme que ele aparece em chamadas posteriores.
Orçamentos de performance

Defina limites de tempo de resposta para endpoints críticos.

Se você precisa estruturar melhor seus casos, veja o modelo e exemplo de caso de teste de API e o guia de asserções de API.

Passo 1: construa a suite de regressão no Apidog

No Apidog, você pode montar cenários de teste como fluxos ordenados de requisições. Cada etapa executa uma chamada de API, aplica asserções e pode passar dados para as etapas seguintes.

Um cenário de regressão de checkout pode seguir esta estrutura:

POST /auth/login
- Enviar credenciais.
- Validar status 200.
- Extrair accessToken para uma variável.
POST /carts
- Criar carrinho usando o token.
- Validar status 201.
- Extrair cartId.
POST /carts/{cartId}/items
- Adicionar produto.
- Validar status 200.
- Validar que total corresponde ao preço esperado.
POST /checkout
- Enviar carrinho para checkout.
- Validar status 200.
- Validar order.status == "confirmed".
GET /orders/{orderId}
- Buscar pedido criado.
- Validar persistência e itens do pedido.

No Apidog, cada etapa pode ter asserções visuais como:

Status da resposta é 200
JSONPath $.order.status é igual a confirmed
Tempo de resposta é menor que 1000 ms

Para respostas documentadas em OpenAPI, o Apidog também pode validar o payload contra o schema salvo do endpoint.

Boas práticas para a suite

Use ambientes, não URLs fixas

Configure staging, preprod ou outro ambiente com base URL, credenciais e variáveis.
Use variáveis para dados sensíveis e dinâmicos

Não coloque tokens, senhas ou IDs específicos diretamente no cenário.
Agrupe cenários em uma suite

A suite será a unidade executada pelo job noturno.
Mantenha dados de teste previsíveis

Se o teste cria dados, tenha cleanup ou use operações idempotentes.

Para aprofundar o encadeamento de cenários, veja o guia de orquestração de testes de API. Se você está começando, siga o guia de como testar uma API com Apidog. Você também pode baixar o Apidog e montar um cenário antes de configurar o CI.

Passo 2: execute a suite pela linha de comando

Uma build noturna precisa rodar sem interface gráfica. Para isso, use o Apidog CLI, um pacote npm que executa cenários salvos a partir do terminal.

Requisito: Node.js v16 ou superior.

Instale o CLI:

npm install -g apidog-cli

Para executar um cenário ou suite online, você precisa de:

um token de acesso do Apidog;
o ID do cenário, suite ou pasta;
o ID do ambiente.

Gere o token em Configurações de CI/CD no Apidog. Trate esse token como segredo.

Exemplo de execução:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 123456 \
  -e 789 \
  -r cli,html \
  --out-dir ./apidog-reports

Principais flags:

Flag	Uso
`--access-token <token>`	Autentica a execução. Use variável de ambiente.
`-t, --test-scenario <id>`	Executa um cenário específico.
`--test-suite <id>`	Executa uma suite completa.
`-f, --test-scenario-folder <id>`	Executa uma pasta de cenários.
`-e, --environment <id>`	Seleciona o ambiente.
`-r, --reporters [reporters]`	Define saída, como `cli` e `html`.
`--out-dir <dir>`	Salva relatórios no diretório informado.

Outras flags úteis:

# Repetir execução para detectar instabilidade
-n 3

# Usar massa de dados CSV ou JSON
-d ./data/regression-data.csv

# Injetar variável de ambiente em runtime
--env-var "baseUrl=https://staging.example.com"

# Injetar variável global
--global-var "region=br"

Antes de agendar, execute localmente:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --test-suite $APIDOG_SUITE_ID \
  -e $APIDOG_ENV_ID \
  -r cli,html \
  --out-dir ./apidog-reports

Se passar localmente, leve o mesmo comando para o pipeline.

Passo 3: agende a execução no CI

A lógica é a mesma em qualquer CI:

Definir um cron diário.
Instalar Node.js e Apidog CLI.
Ler o token a partir de segredo.
Executar apidog run.
Arquivar o relatório HTML como artefato.

GitHub Actions

Este workflow executa todos os dias às 02:00 UTC e também permite execução manual com workflow_dispatch.

name: Nightly API Regression

on:
  schedule:
    - cron: '0 2 * * *'   # 02:00 UTC daily
  workflow_dispatch:

jobs:
  regression:
    runs-on: ubuntu-latest

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

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

      - name: Run nightly regression suite
        run: |
          apidog run \
            --access-token $APIDOG_ACCESS_TOKEN \
            --test-suite ${{ vars.APIDOG_SUITE_ID }} \
            -e ${{ vars.APIDOG_ENV_ID }} \
            -r cli,html \
            --out-dir ./apidog-reports
        env:
          APIDOG_ACCESS_TOKEN: ${{ secrets.APIDOG_ACCESS_TOKEN }}

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

Use if: always() no upload para preservar o relatório mesmo quando o teste falhar.

GitLab CI/CD

No GitLab, o agendamento é criado pela interface em CI/CD > Schedules. No YAML, restrinja o job para rodar apenas quando a origem do pipeline for schedule.

nightly-regression:
  image: node:20

  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

  before_script:
    - npm install -g apidog-cli

  script:
    - apidog run
        --access-token "$APIDOG_ACCESS_TOKEN"
        --test-suite "$APIDOG_SUITE_ID"
        -e "$APIDOG_ENV_ID"
        -r cli,html
        --out-dir ./apidog-reports

  artifacts:
    when: always
    paths:
      - apidog-reports/
    expire_in: 30 days

Configure no GitLab:

APIDOG_ACCESS_TOKEN como variável mascarada e protegida;
APIDOG_SUITE_ID como variável;
APIDOG_ENV_ID como variável;
cron, por exemplo: 0 2 * * *.

Jenkins

No Jenkins, use um pipeline com gatilho cron. Armazene o token como credencial e injete com withCredentials.

pipeline {
    agent any

    triggers {
        cron('H 2 * * *')   // por volta de 02:00; H distribui a carga
    }

    stages {
        stage('Install CLI') {
            steps {
                sh 'npm install -g apidog-cli'
            }
        }

        stage('Nightly regression') {
            steps {
                withCredentials([string(credentialsId: 'apidog-token',
                                        variable: 'APIDOG_ACCESS_TOKEN')]) {
                    sh '''
                        apidog run \
                          --access-token $APIDOG_ACCESS_TOKEN \
                          --test-suite $APIDOG_SUITE_ID \
                          -e $APIDOG_ENV_ID \
                          -r cli,html \
                          --out-dir ./apidog-reports
                    '''
                }
            }
        }
    }

    post {
        always {
            archiveArtifacts artifacts: 'apidog-reports/**', allowEmptyArchive: true
        }
    }
}

O H em H 2 * * * é específico do Jenkins e distribui os jobs ao longo da hora, evitando que todos rodem exatamente às 02:00.

Exemplos de cron

0 2 * * *      # todos os dias às 02:00
0 2,14 * * *   # duas vezes ao dia: 02:00 e 14:00
0 2 * * 1-5    # dias úteis às 02:00

Escolha um horário em que o ambiente esteja estável e serviços externos estejam disponíveis.

Passo 4: torne falhas visíveis

Uma regressão noturna só funciona se alguém vê a falha.

O apidog run retorna código diferente de zero quando há falha. Isso faz o job do CI falhar automaticamente.

A partir disso:

Ative notificações do CI

GitHub Actions, GitLab e Jenkins podem notificar por e-mail ou integração.
Envie alerta para Slack, Teams ou webhook

Inclua link para o job e para o relatório HTML arquivado.
Preserve histórico de relatórios

Isso ajuda a identificar padrões: um endpoint que falha três noites seguidas é sinal mais forte do que uma falha isolada.
Trate teste instável como problema real

Se a suite fica vermelha de forma intermitente, corrija o teste, os dados ou o ambiente. Não normalize o vermelho.

Para investigar instabilidade, repita o cenário:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  --test-suite $APIDOG_SUITE_ID \
  -e $APIDOG_ENV_ID \
  -n 3 \
  -r cli,html \
  --out-dir ./apidog-reports

Por que o Apidog se encaixa nesse fluxo

Você pode montar uma regressão noturna combinando ferramentas separadas: uma para design da API, outra para testes, outra para execução headless e outra para validação de schema. Funciona, mas aumenta o risco de divergência.

Com o Apidog, o endpoint projetado, o cenário testado, o schema validado e o comando executado no CI usam a mesma fonte de verdade. Isso reduz o risco de coleções desatualizadas ou contratos duplicados.

Se você já sofreu com coleções do Postman que não são uma fonte única de verdade, esse modelo ajuda a manter documentação, testes e execução sincronizados.

O mesmo cenário que você depura visualmente no Apidog pode ser executado pelo CLI no CI. Isso simplifica o ciclo:

Criar ou ajustar cenário visualmente.
Validar localmente.
Copiar comando gerado.
Executar em pipeline agendado.
Arquivar relatório.

Perguntas frequentes

Qual é a diferença entre build noturna e integração contínua?

Integração contínua executa testes em cada mudança de código. Build noturna executa em horário fixo, mesmo sem commit novo.

Use ambas:

CI para detectar regressões introduzidas por commits.
Build noturna para detectar problemas causados por ambiente, dados, integrações, credenciais e performance.

Que horas a build noturna deve rodar?

Escolha um período em que:

o ambiente de teste esteja ocioso;
sandboxes externos estejam disponíveis;
jobs de migração ou ETL não estejam alterando dados críticos;
a equipe consiga ver o alerta pela manhã.

Para muitas equipes, algo entre 01:00 e 04:00 funciona bem.

Posso executar contra produção?

Sim, mas com cautela.

Recomendação:

produção: smoke tests somente leitura;
staging/preprod: regressão completa com leitura e escrita;
operações de escrita: usar dados de teste, cleanup ou chamadas idempotentes.

Isso substitui monitoramento?

Não.

Monitoramento responde:

“A API está de pé?”

Regressão noturna responde:

“A API continua correta?”

Monitoramento tende a ser contínuo e superficial. Regressão noturna é periódica e profunda.

Preciso escrever código para agendar os testes?

Não para os cenários em si. Você monta os fluxos visualmente no Apidog e usa o comando apidog run no CI.

O “código” necessário é a configuração do pipeline, como os YAMLs acima.

Se quiser comparar alternativas de execução em linha de comando, veja Postman CLI vs Newman e executando coleções no CI sem Newman.

Checklist para configurar sua primeira regressão noturna

Comece pequeno:

[ ] Escolha um fluxo crítico, como login ou checkout.
[ ] Crie um cenário no Apidog.
[ ] Adicione asserções de status, corpo, headers e tempo de resposta.
[ ] Extraia tokens e IDs para variáveis.
[ ] Agrupe o cenário em uma suite.
[ ] Gere ou copie o comando apidog run.
[ ] Execute localmente.
[ ] Configure o job agendado no CI.
[ ] Arquive o relatório HTML.
[ ] Envie falhas para o canal da equipe.

Depois, expanda:

[ ] Adicione mais jornadas críticas.
[ ] Cubra autenticação e autorização.
[ ] Valide schemas OpenAPI.
[ ] Inclua casos de erro.
[ ] Defina limites de performance.
[ ] Use massa de dados com CSV ou JSON quando necessário.

Uma boa regressão noturna não precisa começar grande. Um único fluxo crítico rodando toda noite já captura problemas que testes por commit não enxergam. A partir daí, você aumenta a cobertura até ter uma rede de segurança real para suas APIs.

DEV Community