Como Configurar o Runner Auto-Hospedado Apidog para Testes de API Agendados

Seu pacote de testes de API só é útil se executado em um agendamento confiável. Uma coleção que você aciona manualmente detecta bugs quando você se lembra de clicar. Uma execução noturna em uma máquina que você controla os detecta às 2 da manhã, antes que seus usuários o façam. Esse é o trabalho do runner do Apidog: um serviço auto-implantado, instalado com Docker em seu próprio servidor, que executa os cenários de teste agendados que você constrói no Apidog e envia os relatórios de volta para o seu projeto.

Abordamos as três formas de agendar testes no Apidog em nosso guia para agendar testes de API automatizados. Esse post compara a execução em nuvem, o runner e o CLI em alto nível. Este é o aprofundamento no caminho do runner: quando você precisa dele, como implantá-lo, como apontar uma tarefa agendada para ele e como ele se compara às alternativas.

Quando você precisa de um runner de testes auto-hospedado

A execução em nuvem é conveniente, mas três situações empurram as equipes para um runner de testes auto-hospedado.

Suas APIs vivem em uma rede privada. Um ambiente de staging em https://orders.staging.internal:8443 não é resolvido pela internet pública. Nenhum serviço em nuvem pode alcançá-lo. Um runner implantado dentro da sua VPC ou rede de escritório pode, porque ele faz requisições de onde está. Este é o mesmo raciocínio por trás da execução de um servidor de mock auto-hospedado em sua intranet: a carga de trabalho precisa viver onde o acesso à rede está.

A conformidade mantém o tráfego interno. Se sua equipe de segurança proíbe payloads de teste com dados reais de clientes de sair da sua infraestrutura, a execução em nuvem está fora de questão. Com o runner, as requisições se originam do seu servidor e atingem suas APIs diretamente. Apenas os relatórios de teste retornam para o Apidog.

Você quer agendamentos estáveis independentes de qualquer laptop. Os testes agendados dentro do aplicativo de desktop param quando o aplicativo é fechado. Os testes conectados à CI são executados quando alguém faz push de código. Nenhum deles oferece "a cada 6 horas, para sempre, não importa o quê". Um runner em um servidor sempre ativo faz exatamente isso.

Se nenhuma dessas situações se aplicar, você provavelmente não precisa de um runner. Execuções manuais no aplicativo ou o CLI na CI serão suficientes.

O que é o runner do Apidog

O runner auto-hospedado é um serviço de automação que você implanta em um servidor independente. Uma vez conectado à sua equipe, ele pode:

• Executar tarefas de teste automatizadas agendadas construídas a partir de seus cenários de teste do Apidog
• Importar documentação de API em um agendamento recorrente
• Servir respostas de mock auto-hospedadas

Ele vem em dois escopos. Um runner geral de nível de equipe pertence a uma equipe. Um runner de nível de organização pode ser compartilhado entre todos os projetos nas equipes da sua organização. A implantação funciona da mesma forma para ambos.

O principal modelo mental: o runner é um worker, não uma cópia do seu projeto. Seus cenários de teste, ambientes e asserções permanecem no Apidog. O runner recebe tarefas, as executa contra qualquer rede que possa alcançar e carrega os resultados. Os membros da equipe nunca acessam via SSH para ver o que aconteceu; eles abrem o histórico de execução no aplicativo.

Pré-requisitos

Verifique-os antes de implantar. Eles vêm diretamente da documentação do ambiente de implantação do runner.

Hardware. Mínimo de 2 núcleos de CPU e 4 GB de RAM; 4+ núcleos e 8 GB são recomendados se você for executar tarefas concorrentes ou tiver uma equipe maior. Reserve pelo menos 30 GB de disco para logs e artefatos de teste, 50 GB para maior conforto.

Docker. O host precisa do Docker versão 20.10.0 ou posterior, com 20.10.13 recomendado. Se o servidor for novo, siga o guia oficial de instalação do Docker Engine para sua distribuição primeiro.

Rede. O runner se comunica com o servidor Apidog via HTTPS na porta 443 e mantém uma conexão WebSocket (WSS) aberta para despacho de tarefas em tempo real. Ele também precisa de acesso de saída para os domínios da AWS usados para uploads de relatórios, além, obviamente, de alcance de rede para todas as APIs que seus testes visam. Observe a direção aqui: o runner faz chamadas de saída. Você não precisa abrir portas de entrada para que o Apidog o alcance, o que torna as conversas sobre firewall com sua equipe de operações curtas.

Permissões e plano. A implantação de um runner é uma ação de recurso de equipe, então você precisará da função de equipe apropriada. O número de execuções de tarefas agendadas que você obtém depende do seu nível de assinatura; verifique a página de preços do Apidog para os limites atuais por plano.

Passo 1: obtenha o comando de implantação no Apidog

O Apidog gera o comando de implantação do Docker para você, com um token de autenticação incorporado. Não copie um de um post de blog, incluindo este; o token é o que vincula o contêiner à sua equipe.

1. Abra Apidog e vá para a página inicial do Apidog. Se você ainda não tem uma conta, baixe o Apidog gratuitamente para acompanhar.
2. Selecione a equipe à qual o runner deve pertencer.
3. Clique em Recursos no lado direito.
4. Clique em Implantar Runner Geral.

Um pop-up mostra o comando de implantação completo. Copie-o imediatamente: ele contém um token sensível e é exibido apenas uma vez. Trate-o como um segredo de CI, não como um trecho para sua wiki de equipe.

Antes de copiar, a caixa de diálogo permite personalizar o comando:

• Sistema Operacional do Servidor: Linux, macOS ou Windows.
• Variante da imagem: Geral vem com Node.js 18, Java 21, Python 3 e PHP 8, então scripts de pré/pós-processamento nessas linguagens funcionam sem configuração extra. Slim inclui apenas Node.js 18 e carrega mais rápido. Personalizado permite que você forneça seu próprio Dockerfile quando os testes dependem de certificados de CA internos ou bibliotecas incomuns.
• Porta exposta: mapeie uma com -p (por exemplo -p 80:4524) se você também for usar o runner para mocks auto-hospedados.
• Diretório de dados montado: adicione uma montagem de volume -v se seus cenários de teste leem arquivos de dados locais, como conjuntos de dados CSV para execuções orientadas por dados.

A documentação do runner geral cobre cada opção em detalhes.

Passo 2: execute o contêiner e confirme que está conectado

Acesse o servidor de destino via SSH, cole o comando e deixe o Docker puxar a imagem e iniciar o contêiner. Duas notas operacionais que valem a pena configurar no primeiro dia:

• Passe TZ como uma variável de ambiente (por exemplo TZ=America/Sao_Paulo) para que "todos os dias às 02:00" signifique suas 02:00, não o padrão do contêiner.
• A partir da versão 2.2.5 do runner, a imagem inclui um usuário não-root runner (UID/GID 10001). Se sua plataforma impõe runAsNonRoot, defina o contexto de segurança de acordo e pré-configure as permissões de volume, já que o entrypoint não pode alterar o proprietário de diretórios no modo não-root.

De volta ao Apidog, o runner aparece em Recursos da sua equipe assim que o handshake do WebSocket é concluído, e os membros da equipe podem selecioná-lo ao criar tarefas. Se ele não aparecer em um minuto, verifique os logs do contêiner com docker logs e confirme se o host pode alcançar o servidor Apidog na porta 443; uma conexão WSS bloqueada é a causa mais comum em redes corporativas com restrições.

Você pode implantar vários runners em uma equipe. As equipes geralmente mantêm um dentro da VPC de staging e outro com acesso de leitura à produção, e então escolhem por tarefa.

Passo 3: crie uma tarefa agendada que vise o runner

Com o runner online, o agendamento é um formulário, não um script.

1. Em seu projeto, abra o módulo Testes e clique em Tarefas Agendadas. As tarefas vivem em uma estrutura de pastas, então agrupe-as por serviço ou ambiente à medida que a lista cresce.
2. Crie uma tarefa e dê a ela um nome que um colega de equipe entenderá em seis meses: "Smoke test do serviço de Pedidos, staging, a cada 6h" é melhor que "teste1".
3. Selecione um ou mais cenários de teste. Por cenário, você pode definir o ambiente, dados de teste, contagem de iterações, atraso entre as requisições e se deve salvar os corpos de requisição/resposta.
4. Defina o ambiente e o escopo da variável. Aplicar variáveis a todos os cenários dentro da tarefa é o meio-termo recomendado; o escopo de pasta é poderoso, mas fácil de se atrapalhar.
5. Defina o Ciclo de Execução: todo domingo às 23h, a cada 6 horas, o que quer que corresponda à rapidez com que você precisa saber se algo quebrou.
6. Em Executa em, escolha seu runner auto-hospedado pelo nome.
7. Configure as notificações. Você pode alertar após cada execução ou apenas em caso de falha. Apenas em caso de falha é o padrão sensato; um canal cheio de marcadores verdes treina a todos para ignorá-lo.

Salve. A partir deste ponto, o agendamento é executado em seu servidor, independentemente de alguém ter o aplicativo Apidog aberto.

Passo 4: leia os relatórios de execução no Apidog

Após cada execução, o runner carrega os resultados para o servidor Apidog automaticamente. Abra Tarefas Agendadas → Histórico de Execução no aplicativo para ver cada execução: status de aprovação/falha, resultados por cenário, falhas de asserção e tempo de execução.

Esta é a vantagem discreta do runner sobre uma configuração caseira de cron e scripts. A execução acontece em sua infraestrutura, mas os relatórios chegam no mesmo espaço de trabalho compartilhado onde os testes são definidos. Quando a execução das 02:00 de terça-feira falha, o engenheiro de QA que investiga vê qual asserção falhou em qual etapa, no contexto, sem precisar procurar em um servidor por arquivos de log.

Combine as notificações de falha com o histórico de execução e você terá um ciclo de monitoramento: o alerta dispara, abre o relatório, reproduz a etapa falha manualmente no aplicativo contra o mesmo ambiente, corrige e espera pela próxima execução bem-sucedida.

Runner vs. CLI vs. nuvem: escolhendo um caminho de execução

O Apidog oferece três formas de executar testes além de um clique manual no aplicativo, e elas resolvem problemas diferentes. Escrevemos um guia completo do caminho de CI em nosso guia do Apidog CLI para GitHub Actions, e a comparação abaixo mostra onde cada um se encaixa.

Os caminhos se complementam em vez de competir. Uma configuração comum: o CLI barra cada implantação no pipeline, enquanto o runner executa um conjunto de smoke tests por hora contra o ambiente de staging e uma regressão completa noturna, detectando as falhas causadas por desvio de infraestrutura e credenciais expiradas, em vez de mudanças de código.

Uma ressalva sobre o tempo: de acordo com a documentação de tarefas agendadas, as tarefas agendadas são projetadas para serem executadas em um runner auto-hospedado, com o Apidog Cloud selecionável à medida que a disponibilidade é lançada. Se você precisa de execução agendada hoje e não pode esperar pela disponibilidade em nuvem para seu plano, o runner é a rota confiável.

Perguntas Frequentes

Preciso do runner se já uso o CLI do Apidog na CI?

Eles respondem a perguntas diferentes. A CI diz "esta mudança quebrou a API?" no momento do push. O runner diz "a API está saudável agora?" em um ciclo fixo, detectando falhas causadas por tokens expirados, dependências mortas ou desvio de infraestrutura sem um commit anexado. Muitas equipes executam ambos; veja nosso guia de configuração de testes de API noturnos para a metade agendada via CI do padrão.

O runner pode alcançar APIs de intranet?

Sim, e esta é sua principal razão de existir. O runner faz requisições da máquina onde está implantado. Coloque-o dentro da sua VPC ou rede de escritório e ele poderá testar hosts *.internal que nenhum serviço em nuvem pode resolver. Ele só precisa de acesso HTTPS e WebSocket de saída para o servidor Apidog para receber tarefas e carregar relatórios.

Quais são as especificações mínimas do servidor?

Dois núcleos de CPU, 4 GB de RAM, 30 GB de disco e Docker 20.10.0 ou posterior. Para equipes que executam tarefas agendadas concorrentes, passe para 4+ núcleos e 8 GB. Uma pequena VM ou uma caixa sobressalente no rack do escritório funcionam; a restrição é o tempo de atividade, não a potência.

De qual plano preciso para tarefas agendadas em um runner auto-hospedado?

As cotas de execução de tarefas agendadas variam por nível de assinatura, então verifique os limites atuais na página de preços do Apidog antes de planejar um agendamento de alta frequência. Se você estiver avaliando opções de execução entre ferramentas, nossa comparação do Apidog CLI vs. Postman CLI analisa o que o lado do test-runner de cada plataforma inclui.