Blog

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

Configure uma compilação noturna para suas APIs: agende testes de regressão automatizados no CI com o Apidog CLI. Copie e cole as configurações cron do GitHub Actions, GitLab e Jenkins para identificar falhas até de manhã.

Ashley Innocent

Ashley Innocent

15 junho 2026

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

Apidog para empresas

Implantação local

SSO & RBAC

Conforme SOC 2

Explorar Apidog Enterprise

Seus testes de API são aprovados em cada pull request. A compilação está verde. Você implanta. Então, às 9 da manhã, alguém em outro fuso horário relata que o checkout retorna um erro 500, e ninguém alterou o código do checkout. O que mudou foi um sandbox de pagamento de terceiros, uma migração de banco de dados que rodou durante a noite, ou um token que expirou silenciosamente. Seus testes por commit nunca detectaram isso porque nada no seu repositório se moveu.

Esta é a lacuna que uma compilação noturna fecha. Uma compilação noturna é uma execução de teste completa e agendada que dispara uma vez por dia, geralmente nas primeiras horas da manhã, contra seus serviços e ambientes reais, em vez de apenas em alterações de código. Ela detecta as falhas que existem entre os commits: desvio de dados, integrações instáveis, credenciais expiradas, vazamentos lentos de desempenho e quebras de contrato introduzidas por serviços que você não controla. Para APIs especificamente, uma execução de regressão noturna é o sistema de alerta antecipado mais barato que você pode configurar.

Este guia descreve a construção desse sistema de ponta a ponta com Apidog. Você projetará um conjunto de regressão, gerará uma execução de linha de comando com o Apidog CLI, o conectará a um trabalho de CI agendado no GitHub Actions, GitLab e Jenkins, e terá um relatório esperando por você antes da reunião de standup. Se você já depurou uma interrupção que uma execução noturna teria sinalizado horas antes, este é o fluxo de trabalho que recupera essas horas.

botão

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

A integração contínua nos ensinou a testar a cada push. Isso é bom, e você deve continuar fazendo isso. Mas os testes por commit respondem a uma pergunta restrita: "essa mudança quebrou algo?" Eles são rápidos, executados frequentemente e têm um escopo para manter os desenvolvedores desbloqueados. Esse escopo é exatamente o motivo pelo qual eles perdem uma classe inteira de problemas.

Uma compilação noturna responde a uma pergunta mais ampla: "o sistema ainda está saudável agora, independentemente de alguém ter mexido nele?" A diferença importa porque a produção tem partes móveis que seus commits nunca veem.

Então, o padrão é de dois níveis, não "ou/ou". Testes de fumaça rápidos guardam cada commit. Um conjunto de regressão mais profundo é executado em um cronograma. O nível noturno é onde você coloca tudo o que é muito lento, muito amplo ou muito dependente do mundo real para pertencer ao ciclo interno.

O que entra em um conjunto de regressão de API noturno

Antes de agendar qualquer coisa, decida o que a execução noturna realmente verifica. Um conjunto noturno é mais amplo do que seus testes de fumaça de commit-gate e mais completo do que um rápido ping de saúde. Busque uma cobertura que o envergonharia se falhasse silenciosamente.

Um sólido conjunto de API noturno cobre:

Se você nunca escreveu casos estruturados como estes, o modelo e exemplo de caso de teste de API é um bom ponto de partida, e asserções de API cobre como validar o corpo da resposta, status, cabeçalhos e tempo com precisão.

Passo 1: Construa o conjunto de regressão no Apidog

O Apidog trata os testes como uma parte de primeira classe do ciclo de vida da API, não como um complemento. Você projeta endpoints e, em seguida, os encadeia em cenários de teste que espelham fluxos de trabalho reais. Um cenário é uma lista ordenada de etapas onde cada etapa é uma solicitação de API com asserções, e onde os dados fluem de uma etapa para a próxima.

Aqui está a forma de um cenário de regressão de checkout:

  1. POST /auth/login: envie credenciais, afirme 200, extraia o accessToken da resposta para uma variável.
  2. POST /carts: crie um carrinho usando o token, afirme 201, extraia o cartId.
  3. POST /carts/{cartId}/items: adicione um produto, afirme 200, afirme que o total do corpo da resposta é igual ao preço esperado.
  4. POST /checkout: envie o carrinho, afirme 200, afirme que order.status é "confirmed".
  5. GET /orders/{orderId}: leia o pedido de volta, afirme que ele persistiu com os itens de linha corretos.

No Apidog, você constrói isso visualmente. Cada etapa recebe asserções sem escrever código repetitivo: uma asserção visual como "o status da resposta é 200" ou "JSONPath $.order.status é igual a confirmado." Para conformidade de esquema, o Apidog pode validar a resposta em relação à definição OpenAPI salva do endpoint automaticamente, para que você não precise escrever manualmente uma verificação para cada campo.

Algumas regras de design mantêm um conjunto noturno sustentável:

Se você vem de outra ferramenta, isso se alinha perfeitamente com conceitos que você já conhece. A visão mais ampla de como encadear cenários está no guia de orquestração de testes de API, e se você nunca executou um teste estruturado no Apidog antes, como testar uma API com Apidog é o ponto de partida passo a passo. Baixe o Apidog e construa um cenário antes de continuar lendo; o restante deste guia assume que você tem um conjunto para executar.

Passo 2: Execute o conjunto a partir da linha de comando

Uma compilação noturna é executada sem supervisão, então precisa de um executor headless. Esse é o Apidog CLI, um pacote npm que executa seus cenários de teste salvos a partir de qualquer terminal, sem necessidade de GUI. Ele foi construído exatamente para isso: execuções automatizadas dentro de um pipeline de CI/CD.

Instale-o globalmente. O CLI precisa do Node.js v16 ou superior.

npm install -g apidog-cli

Para executar um cenário online (um que vive no seu projeto Apidog), você precisa de duas coisas: um token de acesso e o ID do cenário ou conjunto. Gere o token no Apidog em Configurações de CI/CD, onde há um botão "Adicionar token de acesso". Trate esse token como uma senha; ele deve ir em um segredo, nunca no seu repositório.

O comando para executar um único cenário de teste se parece com isto:

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

Flag por flag, usando as opções reais do Apidog CLI:

Outras flags ganham seu lugar em uma execução noturna. -n, --iteration-count <n> repete a execução para identificar instabilidade. -d, --iteration-data <path> alimenta um arquivo CSV ou JSON para que um cenário seja executado em muitas linhas de dados; perfeito para testes de limite. --env-var "key=value" e --global-var "key=value" injetam valores em tempo de execução, que é como você mantém as credenciais fora do cenário salvo.

Você não precisa memorizar isso. O Apidog gera o comando exato para você: abra o painel de CI/CD no cliente, escolha seu cenário ou conjunto e copie a linha apidog run pronta diretamente para a configuração do seu pipeline. Execute-o uma vez localmente primeiro para confirmar que está verde antes de agendá-lo.

Passo 3: Agende-o como uma compilação noturna

Uma compilação noturna é este comando em um temporizador. Cada plataforma de CI suporta trabalhos agendados através da sintaxe cron. O padrão é idêntico em todas elas: um gatilho diário, o token de acesso de um segredo, a execução do CLI e o relatório arquivado como um artefato.

GitHub Actions

O GitHub Actions suporta um gatilho schedule com cron padrão. Este fluxo de trabalho é executado às 02:00 UTC todos os dias e também expõe um botão manual via workflow_dispatch.

name: Nightly API Regression

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

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

O if: always() na etapa de upload é importante: você quer que o relatório seja arquivado mesmo quando a execução falha, porque uma falha é exatamente quando você precisa lê-lo. Observe que os trabalhos agendados do GitHub são executados em UTC e podem ser atrasados durante o pico de carga, então não agende nada que precise ser disparado em um segundo exato.

GitLab CI/CD

O GitLab agenda pipelines através da UI (CI/CD > Agendamentos) em vez de no YAML, então seu trabalho é acionado por uma condição de regras para que ele seja executado apenas no agendamento, e não em cada push.

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

Defina APIDOG_ACCESS_TOKEN como uma variável de CI/CD mascarada e protegida, e então crie um agendamento de pipeline com uma expressão cron como 0 2 * * *. O bloco rules impede que este trabalho seja executado em commits comuns.

Jenkins

No Jenkins, um pipeline com um gatilho cron faz o mesmo trabalho. Armazene o token como uma credencial e puxe-o com withCredentials.

pipeline {
    agent any
    triggers {
        cron('H 2 * * *')   // around 02:00, H spreads load
    }
    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 * * * é uma conveniência do Jenkins: ele escolhe um minuto estável dentro da hora para que todos os seus trabalhos noturnos não se aglomerem exatamente às 02:00.

Esse campo cron é o mesmo em todas as três plataformas. 0 2 * * * significa minuto 0, hora 2, todos os dias. Quer duas vezes por noite para pegar problemas mais cedo? 0 2,14 * * *. Apenas dias de semana? 0 2 * * 1-5. Escolha um horário em que seu ambiente de staging esteja tranquilo e os sandboxes externos estejam ativos.

Passo 4: Torne as falhas impossíveis de ignorar

Uma execução noturna que falha em um log que ninguém lê é pior do que nenhuma execução noturna; ela constrói uma falsa confiança. O objetivo principal é o alerta. Conecte o resultado para onde sua equipe já olha.

O código de saída do CLI é seu gancho. apidog run sai com um valor diferente de zero quando um cenário falha, então o CI automaticamente marca o trabalho como falha. A partir daí:

Uma disciplina mantém as compilações noturnas confiáveis: trate uma falha como um bug real até que se prove o contrário. A maneira mais rápida de acabar com um conjunto noturno é deixar que testes instáveis ensinem a todos a ignorar o vermelho. Se um cenário falha intermitentemente, corrija o teste ou o ambiente; não ignore. Executar com -n para repetir um cenário, ou estabilizar os dados dos quais seu cenário depende, geralmente expõe a verdadeira instabilidade.

Por que o Apidog se encaixa no padrão noturno

Você pode montar um pipeline de API noturno a partir de partes separadas: uma ferramenta para projetar, outra para escrever testes, uma terceira para executá-los em modo headless e um validador de esquema adicionado. Muitas equipes vivem dessa forma, e funciona até que as peças se descoordenem. O atrito aparece às 2 da manhã, quando o teste executado pelo executor não corresponde mais à API que você realmente implantou.

O Apidog condensa isso em um único fluxo de trabalho. O endpoint que você projeta, o cenário que você testa, o esquema contra o qual você valida e o comando que você agenda, todos referenciam a mesma fonte da verdade. Quando você altera um endpoint, o cenário e a verificação de esquema se movem com ele. Não há etapa de exportação, nenhuma coleção que fica silenciosamente desatualizada, nenhuma segunda cópia do contrato para manter sincronizada. Se você já sentiu a dor de coleções do Postman que não são uma verdadeira fonte de verdade, esse design de fonte única faz a diferença.

O CLI é o mesmo motor da GUI, então um cenário que você depura visualmente em sua mesa é executado de forma idêntica no CI às 2 da manhã. Você constrói e corrige testes com total visibilidade e, em seguida, os executa em modo headless com um único comando. Essa simetria é o que torna uma compilação noturna algo em que você confia, em vez de algo que você precisa monitorar constantemente.

Perguntas frequentes

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

A integração contínua executa testes em cada mudança de código para detectar regressões em novos commits. Uma compilação noturna é executada em um cronograma fixo, geralmente durante a noite, independentemente de algo ter mudado. O CI detecta o que sua equipe quebra; a execução noturna detecta o que o mundo exterior quebra: tokens expirados, dependências desviadas, mudanças de dados e rastejamento lento de desempenho. Pipelines maduros executam ambos. Testes de fumaça rápidos protegem cada commit, e um conjunto de regressão mais amplo é executado noturnamente.

A que horas uma compilação noturna deve ser executada?

Escolha um período em que seu ambiente de teste esteja ocioso e os serviços externos dos quais você depende estejam acessíveis. Para muitas equipes, isso é da 1h às 4h da manhã, horário local. Se suas APIs chamam sandboxes de terceiros, confirme se estão ativas nesse horário; alguns provedores limitam ou pausam durante a noite. Evite agendar exatamente na hora cheia em CI compartilhado, onde milhares de trabalhos são acionados de uma vez; um atraso de alguns minutos (ou usando a sintaxe H do Jenkins) distribui a carga.

Posso executar um conjunto noturno contra a produção?

Execute verificações somente leitura contra a produção com segurança. Para qualquer coisa que escreva dados, direcione o conjunto noturno para um ambiente de staging ou pré-produção dedicado com dados realistas, ou use operações idempotentes e uma etapa de limpeza. Um padrão comum é uma execução de regressão completa de leitura e escrita contra o staging, mais uma pequena execução de fumaça somente leitura contra a produção para confirmar que o sistema em produção está acessível e respondendo corretamente.

Como isso difere do monitoramento?

O monitoramento de uptime responde "a API está funcionando?" Um conjunto de regressão noturna responde "a API está correta?" O monitoramento faz um ping em um endpoint e verifica um 200. Uma execução de regressão exercita fluxos de trabalho completos, valida corpos de resposta contra seu esquema, verifica limites de autenticação e afirma regras de negócios. Eles são complementares; o monitoramento é contínuo e superficial, o teste noturno é periódico e profundo.

Preciso escrever código para agendar testes de API?

Não. Você constrói cenários visualmente no Apidog sem script, então copia o comando apidog run gerado do painel de CI/CD. O único "código" são as poucas linhas de YAML ou configuração de pipeline que informam à sua plataforma de CI quando executar, e esses são os modelos acima. Se você preferir ver como os executores de linha de comando se comparam em geral, Postman CLI vs Newman e executando coleções no CI sem Newman cobrem as alternativas.

Configure sua primeira execução noturna

Comece pequeno. Escolha um fluxo de trabalho crítico, seu fluxo de login ou seu caminho de checkout, e construa-o como um único cenário Apidog com asserções reais. Execute-o localmente com o CLI até que esteja verde. Coloque o comando gerado em um trabalho agendado usando um dos modelos acima. Conecte a falha ao chat da sua equipe. Isso é uma compilação noturna funcionando em uma tarde.

A partir daí, expanda o conjunto. Adicione cenários para as jornadas mais importantes seguintes, ative a validação de esquema em todos os níveis e defina orçamentos de desempenho em seus endpoints mais utilizados. Em uma semana, você terá uma rede de regressão que detecta as falhas que seus testes por commit nunca foram projetados para ver, e você as ouvirá de uma mensagem de chat às 2 da manhã em vez de um cliente às 9.

botão

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar