Comment configurer le Runner Apidog auto-hébergé pour les tests API planifiés

Votre suite de tests API n'est utile que si elle s'exécute selon un calendrier fiable. Une collection que vous déclenchez manuellement détecte les bugs lorsque vous vous souvenez de cliquer. Une exécution nocturne sur une machine que vous contrôlez les détecte à 2 heures du matin, avant vos utilisateurs. C'est le rôle du runner Apidog : un service auto-déployé, installé avec Docker sur votre propre serveur, qui exécute les scénarios de tests planifiés que vous créez dans Apidog et renvoie les rapports dans votre projet.

Nous avons abordé les trois façons de planifier des tests dans Apidog dans notre guide sur la planification des tests API automatisés. Cet article compare l'exécution dans le cloud, le runner et la CLI à un niveau général. Celui-ci est une plongée en profondeur dans la voie du runner : quand en avez-vous besoin, comment le déployer, comment y diriger une tâche planifiée, et comment il se compare aux alternatives.

bouton

Quand vous avez besoin d'un runner de tests auto-hébergé

L'exécution dans le cloud est pratique, mais trois situations poussent les équipes vers un runner de tests auto-hébergé.

Vos API se trouvent sur un réseau privé. Un environnement de staging à https://orders.staging.internal:8443 n'est pas résolu depuis l'internet public. Aucun service cloud ne peut l'atteindre. Un runner déployé au sein de votre VPC ou de votre réseau de bureau le peut, car il effectue des requêtes depuis l'endroit où il se trouve. C'est la même logique qui sous-tend l'exécution d'un serveur de maquettes auto-hébergé sur votre intranet : la charge de travail doit se trouver là où l'accès au réseau est disponible.

La conformité maintient le trafic en interne. Si votre équipe de sécurité interdit que des charges utiles de test contenant des données client réalistes ne quittent votre infrastructure, l'exécution dans le cloud est exclue. Avec le runner, les requêtes proviennent de votre serveur et atteignent directement vos API. Seuls les rapports de test retournent à Apidog.

Vous voulez des plannings stables indépendants de tout ordinateur portable. Les tests planifiés dans l'application de bureau s'arrêtent lorsque l'application se ferme. Les tests intégrés à la CI s'exécutent lorsque quelqu'un pousse du code. Aucun des deux ne vous offre « toutes les 6 heures, pour toujours, quoi qu'il arrive ». Un runner sur un serveur toujours actif fait exactement cela.

Si aucune de ces situations ne s'applique, vous n'avez probablement pas besoin d'un runner. Les exécutions manuelles dans l'application ou la CLI en CI suffiront.

Qu'est-ce que le runner Apidog

Le runner auto-hébergé est un service d'automatisation que vous déployez sur un serveur indépendant. Une fois connecté à votre équipe, il peut :

• Exécuter des tâches de test automatisées planifiées, créées à partir de vos scénarios de test Apidog
• Importer la documentation API selon un calendrier récurrent
• Servir des réponses de maquettes auto-hébergées

Il existe en deux étendues. Un runner général au niveau de l'équipe appartient à une seule équipe. Un runner au niveau de l'organisation peut être partagé entre tous les projets des équipes de votre organisation. Le déploiement fonctionne de la même manière pour les deux.

Le modèle mental clé : le runner est un travailleur, pas une copie de votre projet. Vos scénarios de test, environnements et assertions restent dans Apidog. Le runner reçoit les tâches, les exécute sur n'importe quel réseau qu'il peut atteindre et télécharge les résultats. Les membres de l'équipe ne se connectent jamais en SSH pour voir ce qui s'est passé ; ils ouvrent l'historique d'exécution dans l'application.

Prérequis

Vérifiez ces éléments avant de déployer. Ils proviennent directement de la documentation de l'environnement de déploiement du runner.

Matériel. Minimum 2 cœurs de CPU et 4 Go de RAM ; 4+ cœurs et 8 Go sont recommandés si vous exécutez des tâches concurrentes ou si vous avez une équipe plus grande. Prévoyez au moins 30 Go de disque pour les journaux et les artefacts de test, 50 Go pour être à l'aise.

Docker. L'hôte nécessite Docker version 20.10.0 ou ultérieure, avec la version 20.10.13 recommandée. Si le serveur est neuf, suivez d'abord le guide d'installation officiel de Docker Engine pour votre distribution.

Réseau. Le runner communique avec le serveur Apidog via HTTPS sur le port 443 et maintient une connexion WebSocket (WSS) ouverte pour la répartition des tâches en temps réel. Il a également besoin d'un accès sortant aux domaines AWS utilisés pour le téléchargement des rapports, et, évidemment, d'un accès réseau à toutes les API ciblées par vos tests. Notez la direction ici : le runner initie les connexions sortantes. Vous n'avez pas besoin d'ouvrir des ports entrants pour qu'Apidog l'atteigne, ce qui raccourcit les discussions sur le pare-feu avec votre équipe d'opérations.

Permissions et abonnement. Le déploiement d'un runner est une action de ressource d'équipe, vous aurez donc besoin du rôle d'équipe approprié. Le nombre d'exécutions de tâches planifiées dont vous disposez dépend de votre niveau d'abonnement ; consultez la page de tarification Apidog pour connaître les limites actuelles par plan.

Étape 1 : Obtenez la commande de déploiement depuis Apidog

Apidog génère pour vous la commande de déploiement Docker, avec un jeton d'authentification intégré. Ne copiez pas une commande d'un article de blog, y compris celui-ci ; le jeton est ce qui lie le conteneur à votre équipe.

1. Ouvrez Apidog et accédez à la page d'accueil d'Apidog. Si vous n'avez pas encore de compte, téléchargez Apidog gratuitement pour suivre le guide.
2. Sélectionnez l'équipe à laquelle le runner doit appartenir.
3. Cliquez sur Ressources sur le côté droit.
4. Cliquez sur Déployer un runner général.

Une fenêtre contextuelle affiche la commande de déploiement complète. Copiez-la immédiatement : elle contient un jeton sensible et n'est affichée qu'une seule fois. Traitez-la comme un secret de CI, pas comme un extrait pour le wiki de votre équipe.

Avant de copier, la boîte de dialogue vous permet de personnaliser la commande :

• OS du serveur : Linux, macOS ou Windows.
• Variante d'image : Générale est livrée avec Node.js 18, Java 21, Python 3 et PHP 8, de sorte que les scripts de pré/post-traitement dans ces langages fonctionnent sans configuration supplémentaire. Slim n'inclut que Node.js 18 et se télécharge plus rapidement. Personnalisée vous permet de fournir votre propre Dockerfile lorsque les tests dépendent de certificats CA internes ou de bibliothèques inhabituelles.
• Port exposé : mappez-en un avec -p (par exemple -p 80:4524) si vous utilisez également le runner pour des maquettes auto-hébergées.
• Répertoire de données monté : ajoutez un montage de volume -v si vos scénarios de test lisent des fichiers de données locaux, tels que des jeux de données CSV pour des exécutions basées sur les données.

La documentation du runner général couvre chaque option en détail.

Étape 2 : Exécutez le conteneur et confirmez qu'il est connecté

Connectez-vous en SSH au serveur cible, collez la commande et laissez Docker extraire l'image et démarrer le conteneur. Deux notes opérationnelles à prendre en compte dès le premier jour :

• Passez TZ comme variable d'environnement (par exemple TZ=Asia/Singapore) afin que « tous les jours à 02:00 » signifie votre 02:00, et non la valeur par défaut du conteneur.
• À partir de la version 2.2.5 du runner, l'image inclut un utilisateur non-root runner (UID/GID 10001). Si votre plateforme impose runAsNonRoot, configurez le contexte de sécurité en conséquence et pré-configurez les permissions de volume, car le point d'entrée ne peut pas modifier la propriété des répertoires en mode non-root.

De retour dans Apidog, le runner apparaît sous les Ressources de votre équipe une fois la poignée de main WebSocket terminée, et les membres de l'équipe peuvent le sélectionner lors de la création de tâches. S'il n'apparaît pas dans la minute, vérifiez les journaux du conteneur avec docker logs et confirmez que l'hôte peut atteindre le serveur Apidog sur le port 443 ; une connexion WSS bloquée est le coupable habituel sur les réseaux d'entreprise restreints.

Vous pouvez déployer plusieurs runners au sein d'une même équipe. Les équipes en conservent souvent un à l'intérieur du VPC de staging et un autre avec un accès en lecture à la production, puis choisissent par tâche.

Étape 3 : Créez une tâche planifiée ciblant le runner

Avec le runner en ligne, la planification est un formulaire, pas un script.

1. Dans votre projet, ouvrez le module Tests et cliquez sur Tâches planifiées. Les tâches résident dans une structure de dossiers, regroupez-les donc par service ou par environnement à mesure que la liste s'allonge.
2. Créez une tâche et donnez-lui un nom qu'un coéquipier comprendra dans six mois : « Tests de fumée du service de commandes, staging, toutes les 6h » est préférable à « test1 ».
3. Sélectionnez un ou plusieurs scénarios de test. Par scénario, vous pouvez définir l'environnement, les données de test, le nombre d'itérations, le délai entre les requêtes et si les corps de requête/réponse doivent être sauvegardés.
4. Définissez l'environnement et la portée des variables. L'application des variables à tous les scénarios de la tâche est le juste milieu recommandé ; la portée à l'échelle du dossier est puissante mais facile à mal utiliser.
5. Définissez le Cycle d'exécution : chaque dimanche à 23h, toutes les 6 heures, tout ce qui correspond à la rapidité avec laquelle vous devez savoir que quelque chose a mal tourné.
6. Sous S'exécute sur, choisissez votre runner auto-hébergé par son nom.
7. Configurez les notifications. Vous pouvez alerter après chaque exécution ou uniquement en cas d'échec. L'alerte uniquement en cas d'échec est la valeur par défaut raisonnable ; un canal rempli de coches vertes habitue tout le monde à l'ignorer.

Enregistrez-la. À partir de ce moment, la planification s'exécute sur votre serveur, que quelqu'un ait ou non l'application Apidog ouverte.

Étape 4 : Lisez les rapports d'exécution dans Apidog

Après chaque exécution, le runner télécharge automatiquement les résultats sur le serveur Apidog. Ouvrez Tâches planifiées → Historique d'exécution dans l'application pour voir chaque exécution : statut succès/échec, résultats par scénario, échecs d'assertion et chronométrage.

C'est l'avantage discret du runner par rapport à une configuration maison de cron et de scripts. L'exécution a lieu sur votre infrastructure, mais les rapports arrivent dans le même espace de travail partagé où les tests sont définis. Lorsque l'exécution de mardi à 02:00 échoue, l'ingénieur QA qui enquête voit quelle assertion a échoué à quelle étape, dans son contexte, sans avoir à chercher des fichiers journaux sur un serveur.

Associez les notifications d'échec à l'historique d'exécution et vous obtenez une boucle de surveillance : l'alerte se déclenche, ouvrez le rapport, reproduisez manuellement l'étape défaillante dans l'application sur le même environnement, corrigez, et attendez la prochaine exécution réussie.

Runner vs CLI vs cloud : choisir un chemin d'exécution

Apidog vous offre trois façons d'exécuter des tests au-delà d'un simple clic manuel dans l'application, et elles résolvent des problèmes différents. Nous avons rédigé une présentation complète du chemin CI dans notre guide Apidog CLI GitHub Actions, et la comparaison ci-dessous montre où chacun s'intègre.

Les chemins se complètent plutôt que de se concurrencer. Une configuration courante : la CLI contrôle chaque déploiement dans le pipeline, tandis que le runner exécute une suite de tests de fumée horaire sur l'environnement de staging et une régression complète nocturne, détectant les défaillances causées par la dérive de l'infrastructure et l'expiration des identifiants plutôt que par des modifications de code.

Une mise en garde concernant le timing : selon la documentation des tâches planifiées, les tâches planifiées sont conçues pour s'exécuter sur un runner auto-hébergé, Apidog Cloud étant sélectionnable à mesure que la disponibilité est déployée. Si vous avez besoin d'une exécution planifiée aujourd'hui et ne pouvez pas attendre la disponibilité du cloud pour votre plan, le runner est la voie fiable.

FAQ

Ai-je besoin du runner si j'utilise déjà Apidog CLI en CI ?

Ils répondent à des questions différentes. La CI vous dit « cette modification a-t-elle cassé l'API ? » au moment du push. Le runner vous dit « l'API est-elle saine en ce moment ? » sur un cycle fixe, détectant les échecs causés par des jetons expirés, des dépendances mortes ou une dérive d'infrastructure sans commit associé. De nombreuses équipes utilisent les deux ; consultez notre guide de configuration des tests API nocturnes pour la moitié du modèle planifiée par la CI.

Le runner peut-il atteindre les API intranet ?

Oui, et c'est sa principale raison d'être. Le runner effectue des requêtes depuis la machine sur laquelle il est déployé. Placez-le à l'intérieur de votre VPC ou de votre réseau de bureau et il pourra tester des hôtes *.internal qu'aucun service cloud ne peut résoudre. Il n'a besoin que d'un accès HTTPS et WebSocket sortant vers le serveur Apidog pour recevoir les tâches et télécharger les rapports.

Quelles sont les spécifications minimales du serveur ?

Deux cœurs de CPU, 4 Go de RAM, 30 Go de disque et Docker 20.10.0 ou ultérieur. Pour les équipes exécutant des tâches planifiées concurrentes, passez à 4+ cœurs et 8 Go. Une petite VM ou un boîtier de rechange dans le rack du bureau fonctionnent tous deux ; la contrainte est la disponibilité, pas la puissance de calcul.

De quel plan ai-je besoin pour les tâches planifiées sur un runner auto-hébergé ?

Les quotas d'exécution des tâches planifiées varient selon le niveau d'abonnement, alors vérifiez les limites actuelles sur la page de tarification Apidog avant de planifier un calendrier à haute fréquence. Si vous évaluez les options d'exécution entre outils, notre comparaison Apidog CLI vs Postman CLI examine ce que le côté runner de test de chaque plateforme inclut.