Como Agendar Testes Automatizados de API no Apidog (Cloud, Runner e CLI)

Um conjunto de testes aprovado só é útil se continuar aprovado. Seu fluxo de checkout pode funcionar hoje, mas uma dependência pode introduzir uma mudança às 2h da manhã, um certificado pode expirar no fim de semana ou um desvio de configuração pode derrubar o endpoint de pagamentos. Em vez de descobrir isso por um cliente irritado, execute testes de API em um cronograma e receba alertas assim que algo falhar.

Experimente o Apidog hoje

O Apidog possui o recurso integrado de Tarefas Agendadas (Scheduled Tasks) para esse fluxo. Você seleciona cenários de teste existentes, define a frequência, escolhe a máquina de execução e configura alertas. Para contexto adicional, consulte o artigo sobre monitoramento de API e a documentação oficial de Tarefas Agendadas.

Nota: o recurso Tarefas Agendadas está em Beta. A quantidade de execuções disponíveis depende do plano da sua conta.

O que as Tarefas Agendadas fazem

Uma tarefa agendada executa um ou mais Cenários de Teste salvos em uma cadência recorrente. Casos de uso comuns:

• Regressão noturna da API principal.
• Teste de fumaça de staging a cada poucas horas.
• Verificação de saúde durante fins de semana.
• Monitoramento contínuo de endpoints críticos.

A tarefa armazena:

• Cenários a executar.
• Ambiente de destino.
• Frequência de execução.
• Runner responsável pela execução.
• Configuração de notificações.

Isso não é um recurso de raspagem web. As Tarefas Agendadas ficam no módulo Testes e executam seus cenários de API, incluindo asserções, requisições encadeadas e variáveis extraídas. O resultado é um relatório de aprovação ou falha do contrato da API.

Antes de começar: configure um Runner auto-hospedado

Para executar Tarefas Agendadas, você precisa configurar um Runner auto-hospedado.

O Runner é a máquina que efetivamente dispara as requisições. Quando a tarefa é acionada, o Apidog envia o trabalho para o Runner selecionado; as requisições não são executadas no seu cliente desktop.

Use uma máquina que permaneça disponível no horário agendado, por exemplo:

• Um servidor de CI.
• Uma VM dedicada.
• Um servidor pequeno sempre ativo.

No momento, o destino do Runner apresenta duas opções:

• Apidog Cloud — marcado como “em breve”.
• Runner auto-hospedado — opção funcional atual.

Como as requisições partem da máquina do Runner, a rede dela afeta os resultados. Um Runner dentro de uma VPN, VPC, região ou sub-rede específica pode receber respostas diferentes das que você vê no laptop. Para monitoramento, isso normalmente é desejável: o Runner deve enxergar a API de forma próxima ao tráfego real.

Passo a passo: crie uma Tarefa Agendada

O exemplo abaixo usa uma regressão noturna de uma API de e-commerce com cadastro, catálogo, carrinho e checkout com Stripe.

1. Abra Tarefas Agendadas no módulo Testes

No cliente Apidog:

1. Abra o módulo Testes.
2. Na árvore de pastas, clique em Tarefas Agendadas.
3. Visualize e gerencie as tarefas do projeto.

Essa seção centraliza o que está sendo executado e quando cada tarefa será disparada.

2. Crie a tarefa

Clique em + Novo para criar uma tarefa agendada.

Você também pode criar pastas para agrupar tarefas relacionadas, por exemplo:

• Produção
• Staging
• Serviço de pagamentos
• Serviço de catálogo

Defina campos claros:

• Nome da Tarefa: Regressão noturna — Produção
• Descrição: Valida cadastro, catálogo, carrinho e checkout.

Cada tarefa possui um botão para ativar ou desativar a execução sem precisar excluí-la.

3. Selecione os cenários de teste

Em Cenário de Teste, selecione um ou mais cenários existentes.

Para um fluxo de e-commerce, você pode incluir:

1. Cadastro e login
2. Navegar e adicionar ao carrinho
3. Finalizar compra com cartão de teste Stripe

Cada cenário pode ter configurações próprias de execução, como:

• Ambiente.
• Dados de teste.
• Iterações.
• Atraso entre requisições.
• Salvamento de requisições e respostas.

Se todos os cenários usarem os mesmos parâmetros, ative Usar mesma configuração de execução. Isso aplica uma única configuração a todos os cenários selecionados.

Para manter o monitoramento simples, prefira uma tarefa por ambiente:

Tarefa	Ambiente
Regressão noturna — Produção	Produção
Smoke test — Staging	Staging
Pré-lançamento — QA	QA

Embora seja possível misturar ambientes na mesma tarefa, isso torna os resultados mais difíceis de interpretar.

4. Defina o ciclo de execução

Configure a frequência no campo de agendamento. Dependendo da tela, ele pode aparecer como Ciclo de Execução ou Modo de Execução.

Exemplos de cadência:

• Todo domingo às 23h.
• A cada 6 horas.
• A cada 8 horas.
• Uma vez por dia durante a madrugada.

Sugestões práticas:

• Regressão completa: execute diariamente fora do horário comercial.
• Smoke test de staging: execute a cada 6 horas.
• Verificação de endpoint crítico: use uma cadência compatível com os limites do plano.

5. Escolha onde a tarefa será executada

No campo do Runner, selecione seu Runner auto-hospedado.

O rótulo pode variar entre telas, por exemplo:

• Executa em
• Executar em
• Executa em

Todos indicam a máquina que executará o conjunto de testes.

Escolha um Runner que represente a rede esperada para o tráfego da aplicação. Por exemplo, se sua API só é acessível dentro de uma VPC, use um Runner na mesma VPC.

6. Ative as notificações

Ative Notificação para receber alertas sobre os resultados da tarefa.

Os canais disponíveis incluem:

• Slack
• Teams
• Webhook
• Jenkins
• E-mail

Para e-mail, os membros do projeto podem ser preenchidos automaticamente, e você pode adicionar endereços externos, como uma caixa de entrada de plantão.

Defina quando notificar:

• Após cada execução: útil durante lançamentos ou investigações.
• Apenas em caso de falha: recomendado para regressões noturnas estáveis.

Para a maioria dos times, a configuração ideal é:

Canal: Slack
Condição: Apenas falhas
Destino: #api-alertas

7. Salve e ative

Ative a tarefa usando o botão de status. Ela começará a rodar na cadência configurada.

Você pode desativá-la temporariamente sem excluí-la, o que é útil durante:

• Janelas de manutenção.
• Migrações.
• Incidentes conhecidos.
• Mudanças planejadas que geram falhas esperadas.

8. Consulte o Histórico de Execução

Depois de cada execução, o Runner envia os resultados de volta ao servidor.

Abra Tarefas Agendadas - Histórico de Execução para verificar:

• Execuções aprovadas e falhas.
• Horário de cada execução.
• Cenário que falhou.
• Asserção quebrada.
• Detalhes das requisições e respostas.

Quando um alerta chegar pelo Slack ou e-mail, use esse histórico para investigar a causa.

Configurações avançadas

Escolha o escopo correto para variáveis

O Apidog oferece três níveis de compartilhamento de variáveis:

1. Compartilhar apenas no cenário de teste atual
   
   Mantém a variável isolada naquele cenário.

2. Compartilhar entre todos os cenários de teste na tarefa agendada atual
   
   Permite que cenários da mesma tarefa reutilizem valores.

3. Compartilhar entre todas as tarefas agendadas na pasta de tarefas agendadas atual
   
   Compartilha valores entre tarefas relacionadas na mesma pasta.

Use sempre o menor escopo possível. Isso reduz o risco de um token ou valor temporário vazar para cenários não relacionados.

Mantenha valores entre execuções quando necessário

Por padrão, uma execução pode começar sem os valores capturados pela execução anterior.

Se o seu fluxo depende de valores persistentes, ative Manter valores de variáveis na página de design do cenário de teste.

Esse ajuste é relevante quando você precisa reutilizar dados como:

• Token de autenticação atualizado.
• ID de pedido capturado anteriormente.
• IDs criados em uma execução anterior.

Sem essa opção, cada execução começa do zero.

Organize tarefas em pastas

Use pastas para separar responsabilidades:

Tarefas Agendadas/
├── Produção/
│   ├── Smoke test — API pública
│   └── Regressão noturna — Checkout
├── Staging/
│   ├── Smoke test — Catálogo
│   └── Validação pré-lançamento
└── Integrações/
    ├── Stripe
    └── Webhooks

Além de facilitar a navegação, o escopo de variáveis no nível da pasta ajuda tarefas relacionadas a compartilhar configuração de forma controlada.

Verifique os limites do plano

O número de execuções agendadas depende da sua assinatura. Antes de criar tarefas com alta frequência, confirme os limites do seu plano.

Para fluxos mais avançados, consulte:

• Tarefas agendadas avançadas
• Lógica condicional em cenários de teste de API
• Execuções noturnas de testes de API em CI

Automatize com a CLI do Apidog

As Tarefas Agendadas são uma opção de interface. Outra alternativa é usar a CLI do Apidog com cron ou um provedor de CI.

A CLI executa cenários salvos sem interface gráfica. Ela não possui um comando de agendamento nativo: a cadência fica sob responsabilidade do cron, GitHub Actions ou outra ferramenta de automação.

Instale a CLI, autentique-se e execute um cenário:

npm install -g apidog-cli
apidog login --with-token <YOUR_TOKEN>
apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli,junit

Parâmetros principais:

Parâmetro	Descrição
-t	ID do cenário de teste
-e	ID do ambiente
-r	Repórter: cli, html ou junit

Para executar todas as noites às 2h com cron:

0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1

O relatório JUnit pode ser integrado aos painéis e pipelines existentes.

Consulte:

• Guia de instalação da CLI do Apidog
• A CLI do Apidog no seu pipeline de CI/CD
• Gatilhos agendados do GitHub Actions

FAQ

Posso executar testes agendados no Apidog Cloud hoje?

Ainda não. O Apidog Cloud aparece como “em breve”. Por enquanto, use um Runner auto-hospedado.

Com que frequência as Tarefas Agendadas podem ser executadas?

A frequência é flexível, com exemplos como a cada 6 horas ou todo domingo às 23h. No entanto, o número de execuções disponíveis depende do seu plano.

Como recebo alertas apenas quando um teste falha?

Nas configurações de Notificação, selecione apenas falhas e adicione um canal, como Slack, Teams, Webhook, Jenkins ou E-mail.

Combine essa estratégia com uma verificação de saúde de API leve para obter um sinal rápido de disponibilidade ao lado de uma regressão mais completa.

Por que os resultados agendados diferem das execuções locais?

As requisições agendadas saem da máquina do Runner, não do seu laptop. Rede, região, VPN e firewall podem alterar as respostas recebidas.

Minhas variáveis são resetadas a cada execução. O que faltou?

Ative Manter valores de variáveis no design do cenário de teste. Sem essa opção, cada execução agendada começa sem os valores capturados na execução anterior.

Conclusão

Testes agendados transformam “achamos que a API funciona” em “sabemos que funciona — e seremos avisados quando não funcionar”.

O fluxo de implementação é direto:

1. Crie cenários de teste confiáveis.
2. Registre um Runner auto-hospedado.
3. Crie uma Tarefa Agendada.
4. Defina ambiente e frequência.
5. Configure alertas apenas para falhas.
6. Acompanhe o Histórico de Execução.

Quando precisar levar as mesmas verificações para um pipeline, use a CLI com cron ou CI. Baixe o Apidog para configurar seu primeiro conjunto de regressão agendado. É gratuito para começar e não exige cartão de crédito.