Um conjunto de testes aprovado só ajuda se continuar sendo aprovado. Seu fluxo de checkout funciona hoje, mas uma dependência pode lançar uma mudança quebra-galho às 2 da manhã, um certificado pode expirar durante o fim de semana, ou um desvio de configuração pode derrubar o endpoint de pagamentos em um domingo. Você descobre através de um cliente irritado, em vez de uma execução de teste. A solução é simples e confiável: execute seus testes de API em um cronograma, sem a necessidade de um clique humano, e seja avisado no momento em que algo falhar.
O Apidog possui um recurso integrado de Tarefas Agendadas (Scheduled Tasks) exatamente para isso. Você o aponta para cenários de teste que já construiu, define uma cadência, escolhe uma máquina para executar e configura alertas. Este guia aborda tudo isso honestamente, incluindo as limitações atuais. Se você é novo em executar verificações não assistidas contra endpoints ativos, nosso artigo sobre monitoramento de API estabelece o contexto mais amplo, e a documentação das Tarefas Agendadas do Apidog é a fonte oficial para a interface do usuário.
Uma nota rápida antes de começar. O recurso Tarefas Agendadas está rotulado como Beta no momento, e o número exato de execuções agendadas que sua conta obtém depende do seu plano. Mantenha ambos em mente enquanto lê.
O que as tarefas agendadas fazem (e como elas diferem dos raspadores agendados)
Uma tarefa agendada no Apidog executa um ou mais Cenários de Teste salvos em um ciclo recorrente. Pense em uma regressão noturna em sua API principal, uma verificação de fumaça a cada poucas horas contra o ambiente de staging, ou uma varredura de saúde no fim de semana. A tarefa lembra quais cenários executar, qual ambiente atingir, com que frequência disparar, qual máquina executa o trabalho e quem notificar quando falhar.
Se você já viu a frase “tarefas agendadas” associada à raspagem da web ou coleta de dados, isso é algo diferente. Este recurso não se trata de rastrear páginas por tempo. Ele reside dentro do módulo Testes e impulsiona seus cenários de teste de API: asserções, requisições encadeadas, variáveis extraídas, tudo. O resultado é um relatório de aprovação ou falha sobre seu contrato de API, não um conjunto de dados raspados.
Essa distinção importa porque muda o que você configura. Você não está escrevendo seletores ou regras de rastreamento. Você está escolhendo cenários de teste existentes e dizendo ao Apidog quando e onde executá-los.
Antes de começar: configure um Runner auto-hospedado
Aqui está o pré-requisito que confunde as pessoas. Para executar tarefas agendadas, você precisa primeiro configurar um Runner auto-hospedado. A documentação é explícita sobre isso.
Um Runner é uma máquina que executa o conjunto de testes. Quando uma tarefa agendada é acionada, o Apidog não executa as requisições em seu cliente de desktop; ele entrega a tarefa ao Runner que você selecionou, e cada requisição no conjunto é enviada a partir dessa máquina. Uma caixa de CI, um pequeno servidor sempre ligado ou uma VM dedicada funcionam bem. O que quer que você escolha permanece ativo e acessível no cronograma desejado.
O campo de destino do runner oferece duas opções: Apidog Cloud, marcado como “em breve”, ou um Runner auto-hospedado. Como o Apidog Cloud ainda não está disponível, um Runner auto-hospedado é a única opção funcional hoje. Não planeje a execução em nuvem até que seja lançado.
Como as requisições se originam da máquina do Runner, seu ambiente de rede molda seus resultados. Um Runner atrás de uma VPN corporativa, em uma região diferente ou em uma sub-rede com firewall pode ver respostas diferentes das que seu laptop vê. Isso geralmente é o que você deseja para um monitoramento realista, mas vale a pena saber quando uma execução agendada discorda de uma execução local.
Passo a passo: crie uma tarefa agendada
Com um Runner registrado, o restante acontece no cliente. O exemplo em execução abaixo é um conjunto de regressão noturna para uma API de e-commerce que abrange cadastro de usuário, listagem de produtos, carrinho e um checkout suportado por Stripe.
1. Abra as Tarefas Agendadas no módulo de Testes
Abra o módulo Testes no cliente Apidog. Na árvore de pastas de Testes, clique em Tarefas Agendadas para visualizar e gerenciar cada tarefa agendada no projeto. Todas as tarefas do projeto aparecem aqui na seção Tarefas Agendadas, então este é o seu único lugar para ver o que está sendo executado e quando.
2. Crie a tarefa
Clique em + Novo para criar uma nova tarefa agendada. Você também pode criar uma pasta aqui para agrupar tarefas relacionadas, o que é útil quando você tem conjuntos de testes separados para staging e produção ou para diferentes serviços.
Dê à tarefa um Nome da Tarefa e uma Descrição claros. Estes existem para distinguir as tarefas e explicar seu propósito, para que seu eu futuro saiba o que “Regressão noturna, prod” realmente cobre sem ter que abri-la. Cada tarefa também possui um botão de ativar/desativar, e as tarefas na árvore podem ser ativadas ou desativadas a qualquer momento.
3. Selecione os cenários de teste para executar
Em Cenário de Teste, escolha um ou mais cenários para incluir. Para o exemplo de e-commerce, você pode selecionar “Cadastro e login”, “Navegar e adicionar ao carrinho” e “Finalizar compra com cartão de teste Stripe” para que uma única tarefa cubra todo o caminho crítico.
Cada cenário pode ter suas próprias configurações de execução: Ambiente, dados de teste, iterações, atraso e se deve salvar requisições e respostas. Se você preferir não ajustar cada um, ative Usar mesma configuração de execução para aplicar uma única configuração de tempo de execução a cada cenário selecionado de uma vez. Isso mantém um grande conjunto de testes consistente e rápido de configurar.
A seleção de ambiente é a configuração com a qual as pessoas mais se preocupam. Aponte um monitor de produção noturno para seu ambiente de produção, e um teste de fumaça de pré-lançamento para o ambiente de staging. Como cada cenário pode especificar seu próprio ambiente, uma tarefa pode até misturar alvos se você precisar, embora manter uma tarefa para um único ambiente seja mais fácil de entender.
4. Defina o ciclo de execução
Defina o campo de agendamento de execução para a cadência desejada. Dependendo da tela em que você está, este campo pode ser chamado de Ciclo de Execução ou Modo de Execução; é a mesma configuração, e a terminologia do rótulo varia na interface do usuário. A documentação fornece exemplos concretos que você pode replicar: todo domingo às 23h, a cada 6 horas ou a cada 8 horas.
Para regressão noturna, uma execução diária tarde da noite mantém o ruído baixo e detecta problemas antes do dia de trabalho. Para um teste de fumaça de staging, a cada 6 horas oferece feedback mais rápido sem sobrecarregar o ambiente.
5. Escolha onde será executado
Defina o campo do runner para o seu Runner auto-hospedado. Assim como o campo de agendamento, este é rotulado inconsistente em diferentes telas como 'Executa em', 'Executar em' ou 'Executa em'; todos significam a mesma coisa, a máquina que executa o conjunto. O Apidog Cloud também aparece aqui, mas está “em breve”, então escolha seu Runner auto-hospedado. Se você registrou vários Runners de uso geral, escolha o específico que deseja, por exemplo, um Runner que esteja dentro da mesma VPC da sua API.
Lembre-se que todas as requisições iniciadas no conjunto de testes são enviadas da máquina especificada aqui, então escolha um Runner cuja rede veja sua API da mesma forma que o tráfego real.
6. Ative as notificações
Ative a Notificação para que a tarefa o avise quando algo falhar. A documentação recomenda isso para tarefas agendadas, e este é o objetivo principal das execuções não assistidas: o silêncio deve significar sucesso, e uma falha deve chegar até você rapidamente.
O Apidog suporta estes canais por nome: Slack, Teams, Webhook, Jenkins e E-mail. Para E-mail, os endereços dos membros do projeto são preenchidos automaticamente, e você pode digitar endereços de não-membros manualmente para um plantão ou uma caixa de entrada compartilhada. O Slack envia falhas diretamente para o seu canal da equipe; a opção Webhook permite que você distribua para qualquer outra coisa que você execute, de PagerDuty a um endpoint personalizado.
Você também escolhe quando os alertas são disparados: após cada execução, ou apenas em caso de falhas. Para um conjunto de testes noturno saudável, a opção 'apenas falhas' mantém o canal silencioso até que seja realmente necessário. Durante um lançamento instável, a opção 'a cada execução' fornece um batimento cardíaco que confirma que o trabalho está sendo executado.
7. Salve e ative
Acione o botão da tarefa para ativá-la, e ela começará a ser executada na cadência que você definiu. Você pode desativá-la mais tarde sem excluí-la, o que é útil durante uma interrupção planejada ou uma janela de migração barulhenta.
8. Leia o histórico de execuções
Após cada execução, os resultados são automaticamente enviados do Runner de volta para o servidor. Abra a seção 'Tarefas Agendadas - Histórico de Execução' no cliente para vê-los. Este é o seu rastro de auditoria: qual execução passou, qual falhou, qual asserção quebrou e quando. Quando um alerta chega no Slack, o Histórico de Execução é onde você vai para ver os detalhes por trás dele.
Configurações avançadas e variações
Uma vez que a tarefa básica esteja em execução, algumas opções a tornam mais robusta.
Escopo da variável. Quando seus cenários passam dados entre execuções, o Apidog oferece três níveis de compartilhamento, do menor para o maior: Compartilhar apenas no cenário de teste atual, que mantém uma variável em um arquivo dedicado para aquele cenário; Compartilhar entre todos os cenários de teste na tarefa agendada atual, que permite que os cenários na mesma tarefa leiam os valores uns dos outros; e Compartilhar entre todas as tarefas agendadas na pasta de tarefas agendadas atual, o escopo mais amplo. Escolha o menor escopo que ainda permita que seus dados fluam, para que um token de autenticação de um cenário não vaze para outro não relacionado.
Persistência de variáveis. Os valores só são transferidos de uma execução para a próxima se a opção 'Manter valores de variáveis' estiver ativada na página de design do cenário de teste. Se sua execução noturna precisar do ID de pedido capturado de ontem ou de um token atualizado, ative esta opção. Sem ela, cada execução começa limpa e qualquer suposição entre execuções falha silenciosamente.
Agrupamento com pastas. À medida que seu conjunto de testes cresce, crie pastas em Tarefas Agendadas para separar, por exemplo, monitores de produção de verificações de pré-lançamento. O escopo de variável em nível de pasta permite que um grupo de tarefas relacionadas compartilhe a configuração de forma limpa.
Limites do plano. O número de execuções agendadas que você obtém depende da sua assinatura. A documentação aponta para a página de preços do Apidog para os números exatos, então verifique seu plano antes de definir uma cadência agressiva de hora em hora. Se você precisar de uma cobertura mais aprofundada de agrupamento e padrões de agendamento mais pesados, nosso guia sobre tarefas agendadas avançadas vai além, e o guia irmão sobre lógica condicional em cenários de teste de API ajuda você a construir cenários que valem a pena agendar em primeiro lugar. Para equipes que estão configurando suas primeiras verificações não assistidas, o artigo sobre execuções noturnas de testes de API em CI complementa bem este.
Automatize o fluxo de trabalho com a CLI do Apidog
A interface de usuário de Tarefas Agendadas é um caminho. A CLI do Apidog é o terceiro, e é um caminho real: você executa um cenário salvo sem interface gráfica, e então deixa o cron ou seu provedor de CI lidar com a cadência. Para ser claro, a CLI não possui um comando de agendamento nativo; o agendamento vive fora do Apidog, na ferramenta que você já confia para o cron.
Instale e autentique, então execute um cenário por ID contra um ambiente escolhido. O guia de instalação da CLI do Apidog cobre a configuração de token em detalhes:
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
Aqui `-t` é o ID do cenário de teste, `-e` é o ID do ambiente, e `-r` é o repórter (`cli`, `html`, ou `junit`, separados por vírgula para vários). Para executá-lo todas as noites com cron, adicione uma linha:
0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1
Ou acione-o a partir de um job agendado do GitHub Actions. De qualquer forma, o relatório JUnit é inserido nos seus painéis de pipeline existentes. Veja A CLI do Apidog no seu pipeline de CI/CD para a configuração completa, incluindo cron e gatilhos de agendamento do GitHub Actions.
FAQ
Posso executar testes agendados no Apidog Cloud hoje? Ainda não. O destino do runner lista o Apidog Cloud como “em breve”, então um Runner auto-hospedado é a única máquina de execução funcionando por enquanto. Registre um Runner primeiro e, em seguida, selecione-o na tarefa.
Com que frequência as tarefas agendadas podem ser executadas? Tão frequentemente quanto seu plano permitir. A cadência em si é flexível, com exemplos documentados como a cada 6 horas ou todo domingo às 23h, mas o número de execuções agendadas é limitado pela sua assinatura. Verifique a página de preços do Apidog para o limite exato do seu nível, em vez de assumir um número.
Como recebo notificações apenas quando um teste falha? Nas configurações de Notificação da tarefa, escolha a opção 'apenas falhas' em vez de 'cada execução', e então adicione um canal: Slack, Teams, Webhook, Jenkins ou E-mail. Isso mantém seu canal silencioso em noites sem problemas e barulhento quando algo falha. Combine-o com uma verificação de saúde de API leve para um sinal rápido de atividade ao lado do conjunto de regressão mais aprofundado.
Por que meus resultados agendados diferem das minhas execuções de teste locais? Porque as requisições vêm da máquina do Runner, não do seu laptop. Sua rede, região e qualquer VPN ou firewall moldam as respostas. Isso é esperado e geralmente é a visão mais realista do que seus usuários enfrentam.
Minhas variáveis resetam a cada execução. O que eu perdi? A opção 'Manter valores de variáveis' na página de design do cenário de teste. Ative-a para que os valores capturados persistam de uma execução para a próxima. Sem ela, cada execução agendada começa do zero e qualquer dependência entre execuções falha.
Conclusão
Testes agendados transformam “achamos que a API funciona” em “sabemos, e já teríamos sido avisados se não funcionasse”. Construa seus cenários uma vez, registre um Runner auto-hospedado, defina um Ciclo de Execução, configure o Slack ou e-mail em caso de falha, e deixe-o rodar enquanto você dorme. Quando você quiser as mesmas verificações dentro de um pipeline, a CLI mais o cron oferecem o terceiro caminho com zero ferramentas extras. Baixe o Apidog para configurar seu primeiro conjunto de regressão agendado. É gratuito para começar, sem necessidade de cartão de crédito.