Une suite de tests réussie n'est utile que si elle continue de l'être. Votre processus de paiement fonctionne aujourd'hui, mais une dépendance introduit un changement incompatible à 2h du matin, un certificat expire pendant le week-end, ou une dérive de configuration désactive le point de terminaison de paiement un dimanche. Vous le découvrez par un client en colère au lieu d'une exécution de test. La solution est simple et fiable : exécutez vos tests d'API selon un calendrier, sans qu'un humain n'ait à cliquer sur un bouton, et soyez informé dès que quelque chose ne fonctionne plus.
Apidog dispose d'une fonction intégrée de tâches planifiées (Scheduled Tasks) précisément pour cela. Vous la pointez vers les scénarios de test que vous avez déjà construits, définissez une cadence, choisissez une machine sur laquelle l'exécuter et configurez les alertes. Ce guide vous expliquera tout cela en toute honnêteté, y compris les limites actuelles. Si vous débutez avec les vérifications automatisées sur des points de terminaison en direct, notre introduction sur la surveillance d'API vous donnera le contexte général, et la documentation des tâches planifiées d'Apidog est la référence pour l'interface utilisateur.
Une brève remarque avant de commencer. La fonction de tâches planifiées est actuellement en version Bêta, et le nombre exact d'exécutions planifiées dont bénéficie votre compte dépend de votre forfait. Gardez ces deux points à l'esprit pendant votre lecture.
Ce que font les tâches planifiées (et comment elles diffèrent des « scrapers » planifiés)
Une tâche planifiée dans Apidog exécute un ou plusieurs scénarios de test sauvegardés selon un cycle récurrent. Pensez à une régression nocturne sur votre API principale, à un test de fumée toutes les quelques heures sur l'environnement de staging, ou à une vérification de santé le week-end. La tâche mémorise quels scénarios exécuter, quel environnement cibler, à quelle fréquence s'exécuter, quelle machine exécute le travail et qui notifier en cas d'échec.
Si vous avez déjà vu l'expression « tâches planifiées » associée au web scraping ou à la collecte de données, il s'agit d'une chose différente. Cette fonctionnalité ne concerne pas l'exploration de pages à intervalles réguliers. Elle réside dans le module Tests et exécute vos scénarios de test d'API : assertions, requêtes en chaîne, variables extraites, etc. Le résultat est un rapport de réussite ou d'échec sur votre contrat d'API, et non un ensemble de données extrait.
Cette distinction est importante car elle modifie ce que vous configurez. Vous n'écrivez pas de sélecteurs ou de règles de crawl. Vous choisissez des scénarios de test existants et indiquez à Apidog quand et où les exécuter.
Avant de commencer : configurez un Runner auto-hébergé
Voici le prérequis qui pose problème à certains. Pour exécuter des tâches planifiées, vous devez d'abord configurer un Runner auto-hébergé. La documentation est explicite à ce sujet.
Un Runner est une machine qui exécute la suite de tests. Lorsqu'une tâche planifiée se déclenche, Apidog n'exécute pas les requêtes dans votre client de bureau ; il confie la tâche au Runner que vous avez sélectionné, et chaque requête de la suite est envoyée depuis cette machine. Un serveur d'intégration continue (CI), un petit serveur toujours allumé ou une VM dédiée fonctionnent tous très bien. Quelle que soit votre sélection, elle reste active et joignable selon le calendrier que vous souhaitez.
Le champ cible du runner propose deux choix : Apidog Cloud, marqué « bientôt disponible », ou un Runner auto-hébergé. Comme Apidog Cloud n'est pas encore disponible, un Runner auto-hébergé est la seule option fonctionnelle aujourd'hui. Ne prévoyez pas d'exécution dans le cloud avant sa sortie.
Étant donné que les requêtes proviennent de la machine du Runner, son environnement réseau influe sur vos résultats. Un Runner derrière un VPN d'entreprise, dans une région différente ou sur un sous-réseau protégé par un pare-feu peut voir des réponses différentes de celles de votre ordinateur portable. C'est généralement ce que vous souhaitez pour une surveillance réaliste, mais il est bon de le savoir lorsqu'une exécution planifiée n'est pas cohérente avec une exécution locale.
Pas à pas : créer une tâche planifiée
Une fois le Runner enregistré, le reste se passe dans le client. L'exemple en cours ci-dessous est une suite de régression nocturne pour une API e-commerce qui couvre l'inscription de l'utilisateur, la liste des produits, le panier et un paiement pris en charge par Stripe.
1. Ouvrez les tâches planifiées dans le module Tests
Ouvrez le module Tests dans le client Apidog. Dans l'arborescence des dossiers Tests, cliquez sur Tâches planifiées (Scheduled Tasks) pour afficher et gérer toutes les tâches planifiées du projet. Toutes les tâches du projet apparaissent ici sous la section Tâches planifiées, c'est donc votre seul endroit pour voir ce qui est en cours d'exécution et à quel moment.
2. Créez la tâche
Cliquez sur + Nouveau pour créer une nouvelle tâche planifiée. Vous pouvez également créer un dossier ici pour regrouper les tâches associées, ce qui est pratique une fois que vous avez des suites distinctes pour l'environnement de staging et de production ou pour différents services.
Donnez à la tâche un nom de tâche et une description clairs. Ceux-ci servent à distinguer les tâches et à expliquer leur objectif, afin que votre futur moi sache ce que couvre réellement « Régression nocturne, prod » sans l'ouvrir. Chaque tâche dispose également d'un bouton d'activation/désactivation, et les tâches de l'arborescence peuvent être activées ou désactivées à tout moment.
3. Sélectionnez les scénarios de test à exécuter
Sous Scénario de test, choisissez un ou plusieurs scénarios à inclure. Pour l'exemple e-commerce, vous pourriez sélectionner « Inscription et connexion », « Parcourir et ajouter au panier » et « Payer avec la carte de test Stripe » afin qu'une seule tâche couvre l'ensemble du chemin critique.
Chaque scénario peut comporter ses propres paramètres d'exécution : Environnement, données de test, itérations, délai et si les requêtes et réponses doivent être enregistrées. Si vous préférez ne pas régler chacun d'eux, activez « Utiliser la même configuration d'exécution » pour appliquer une seule configuration d'exécution à tous les scénarios sélectionnés en même temps. Cela permet de maintenir une grande suite cohérente et rapide à configurer.
La sélection de l'environnement est le paramètre le plus important pour les utilisateurs. Dirigez un moniteur de production nocturne vers votre environnement de production, et un test de fumée de pré-version vers l'environnement de staging. Étant donné que chaque scénario peut spécifier son propre environnement, une tâche peut même mélanger les cibles si vous en avez besoin, bien qu'il soit plus simple de se limiter à un seul environnement par tâche.
4. Définissez le cycle d'exécution
Définissez le champ du calendrier d'exécution (run-schedule) sur la cadence souhaitée. Selon l'écran sur lequel vous vous trouvez, ce champ peut être intitulé « Cycle d'exécution » ou « Mode d'exécution » ; il s'agit du même paramètre, et la formulation de l'étiquette varie selon l'interface utilisateur. La documentation fournit des exemples concrets que vous pouvez reproduire : chaque dimanche à 23h, toutes les 6 heures, ou toutes les 8 heures.
Pour une régression nocturne, une exécution quotidienne tard le soir maintient le bruit au minimum et détecte les problèmes avant la journée de travail. Pour un test de fumée de staging, toutes les 6 heures vous donne un retour plus rapide sans surcharger l'environnement.
5. Choisissez où il s'exécute
Définissez le champ du runner sur votre Runner auto-hébergé. Comme le champ de planification, celui-ci est étiqueté de manière incohérente sur les différents écrans comme « S'exécute sur », « Exécuter sur » ou « S'exécute sur » ; tous signifient la même chose, la machine qui exécute la suite. Apidog Cloud apparaît également ici mais sera bientôt disponible, alors choisissez votre Runner auto-hébergé. Si vous avez enregistré plusieurs Runners polyvalents, choisissez celui que vous souhaitez spécifiquement, par exemple un Runner qui se trouve dans le même VPC que votre API.
N'oubliez pas que toutes les requêtes initiées dans la suite de tests sont envoyées depuis la machine spécifiée ici, choisissez donc un Runner dont le réseau voit votre API de la même manière que le trafic réel.
6. Activez les notifications
Activez les notifications pour que la tâche vous avertisse en cas de problème. La documentation le recommande pour les tâches planifiées, et c'est tout l'intérêt des exécutions automatisées : le silence doit signifier le succès, et un échec doit vous parvenir rapidement.
Apidog prend en charge ces canaux par leur nom : Slack, Teams, Webhook, Jenkins et E-mail. Pour l'e-mail, les adresses des membres du projet se complètent automatiquement, et vous pouvez saisir manuellement des adresses non-membres pour une rotation d'astreinte ou une boîte de réception partagée. Slack envoie les échecs directement dans le canal de votre équipe ; l'option Webhook vous permet de diffuser vers tout autre service que vous utilisez, de PagerDuty à un point de terminaison personnalisé.
Vous choisissez également quand les alertes se déclenchent : après chaque exécution, ou uniquement en cas d'échec. Pour une suite nocturne saine, l'option « uniquement en cas d'échec » maintient le canal silencieux jusqu'à ce que cela soit nécessaire. Lors d'un déploiement incertain, l'option « chaque exécution » vous donne un signe de vie qui confirme que la tâche est bien en cours d'exécution.
7. Enregistrez et activez
Basculez l'interrupteur de la tâche pour l'activer, et elle commencera à s'exécuter à la cadence que vous avez définie. Vous pouvez la désactiver ultérieurement sans la supprimer, ce qui est utile lors d'une panne planifiée ou d'une fenêtre de migration bruyante.
8. Lisez l'historique des exécutions
Après chaque exécution, les résultats sont automatiquement téléchargés du Runner vers le serveur. Ouvrez la section « Tâches planifiées - Historique des exécutions » dans le client pour les consulter. C'est votre piste d'audit : quelle exécution a réussi, quelle a échoué, quelle assertion a posé problème, et quand. Lorsqu'une alerte arrive sur Slack, l'historique des exécutions est l'endroit où vous allez pour en voir les détails.
Paramètres avancés et variations
Une fois la tâche de base exécutée, quelques options la rendent plus robuste.
Portée des variables. Lorsque vos scénarios transmettent des données entre les exécutions, Apidog vous offre trois niveaux de partage, du plus petit au plus grand : Partager uniquement dans le scénario de test actuel, ce qui conserve une variable dans un fichier dédié pour ce seul scénario ; Partager entre tous les scénarios de test de la tâche planifiée actuelle, ce qui permet aux scénarios de la même tâche de lire les valeurs des autres ; et Partager entre toutes les tâches planifiées dans le dossier de tâches planifiées actuel, la portée la plus large. Choisissez la portée la plus petite qui permette encore à vos données de circuler, afin qu'un jeton d'authentification d'un scénario ne soit pas divulgué à un scénario non lié.
Persistance des variables. Les valeurs ne sont transmises d'une exécution à l'autre que si l'option « Conserver les valeurs des variables » est activée sur la page de conception du scénario de test. Si votre exécution nocturne a besoin de l'ID de commande capturé hier ou d'un jeton rafraîchi, activez cette option. Sans cela, chaque exécution démarre à zéro et toute hypothèse inter-exécution se brise silencieusement.
Regroupement par dossiers. Au fur et à mesure que votre suite de tests s'agrandit, créez des dossiers sous « Tâches planifiées » pour séparer, par exemple, les moniteurs de production des vérifications de pré-version. La portée des variables au niveau du dossier permet alors à un groupe de tâches liées de partager une configuration de manière propre.
Limites du forfait. Le nombre d'exécutions planifiées dont vous bénéficiez dépend de votre abonnement. La documentation renvoie à la page des tarifs d'Apidog pour les chiffres exacts, alors vérifiez votre forfait avant de définir une cadence agressive toutes les heures. Si vous avez besoin d'une couverture plus approfondie du regroupement et de modèles de planification plus complexes, notre présentation des tâches planifiées avancées va plus loin, et le guide connexe sur la logique conditionnelle dans les scénarios de test d'API vous aide à construire des scénarios qui valent la peine d'être planifiés en premier lieu. Pour les équipes qui mettent en place leurs premières vérifications automatisées, l'article sur les exécutions nocturnes de tests d'API dans la CI s'accorde bien avec celui-ci.
Automatisez le flux de travail avec l'Apidog CLI
L'interface utilisateur des Tâches planifiées est une voie. L'outil CLI d'Apidog est la troisième, et c'est une option concrète : vous exécutez un scénario enregistré sans interface graphique, puis laissez cron ou votre fournisseur d'intégration continue gérer la cadence. Pour être clair, le CLI n'a pas de commande de planification native ; la planification se fait en dehors d'Apidog, avec l'outil que vous utilisez déjà pour cron.
Installez et authentifiez-vous, puis exécutez un scénario par ID sur un environnement choisi. Le guide d'installation de l'Apidog CLI couvre entièrement la configuration du jeton :
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
Ici, -t est l'ID du scénario de test, -e est l'ID de l'environnement, et -r est le rapporteur (cli, html ou junit, séparés par des virgules pour plusieurs). Pour l'exécuter toutes les nuits avec cron, ajoutez une ligne :
0 2 * * * cd /srv/api-tests && apidog run --access-token $APIDOG_ACCESS_TOKEN -t 4471 -e 88 -r junit >> run.log 2>&1
Ou déclenchez-le à partir d'une tâche GitHub Actions planifiée. Dans tous les cas, le rapport JUnit apparaît dans vos tableaux de bord de pipeline existants. Consultez Apidog CLI dans votre pipeline CI/CD pour la configuration complète, y compris cron et les déclencheurs de planification GitHub Actions.
FAQ
Puis-je exécuter des tests planifiés sur Apidog Cloud aujourd'hui ? Pas encore. La cible du runner répertorie Apidog Cloud comme « bientôt disponible », donc un Runner auto-hébergé est la seule machine d'exécution fonctionnelle pour l'instant. Enregistrez d'abord un Runner, puis sélectionnez-le dans la tâche.
À quelle fréquence les tâches planifiées peuvent-elles s'exécuter ? Aussi souvent que votre forfait le permet. La cadence elle-même est flexible, avec des exemples documentés comme toutes les 6 heures ou chaque dimanche à 23h, mais le nombre d'exécutions planifiées est limité par votre abonnement. Consultez la page des tarifs d'Apidog pour la limite exacte de votre niveau plutôt que de supposer un nombre.
Comment être notifié uniquement lorsqu'un test échoue ? Dans les paramètres de notification de la tâche, choisissez l'option « uniquement en cas d'échec » au lieu de « chaque exécution », puis ajoutez un canal : Slack, Teams, Webhook, Jenkins ou E-mail. Cela maintient votre canal silencieux les nuits sans problème et bruyant lorsque quelque chose ne va pas. Associez-le à une vérification de santé d'API légère pour un signal de vivacité rapide en plus de la suite de régression plus approfondie.
Pourquoi mes résultats planifiés diffèrent-ils de mes exécutions de tests locaux ? Parce que les requêtes proviennent de la machine du Runner, et non de votre ordinateur portable. Son réseau, sa région et tout VPN ou pare-feu façonnent les réponses. C'est attendu, et c'est souvent la vision la plus réaliste de ce que vos utilisateurs rencontrent.
Mes variables se réinitialisent à chaque exécution. Qu'ai-je manqué ? L'option « Conserver les valeurs des variables » sur la page de conception du scénario de test. Activez-la pour que les valeurs capturées persistent d'une exécution à l'autre. Sans cela, chaque exécution planifiée démarre à zéro et toute dépendance inter-exécution échoue.
En résumé
Les tests planifiés transforment « nous pensons que l'API fonctionne » en « nous savons, et nous l'aurions déjà su si ce n'était pas le cas ». Construisez vos scénarios une fois, enregistrez un Runner auto-hébergé, définissez un cycle d'exécution, configurez Slack ou l'e-mail en cas d'échec, et laissez-le s'exécuter pendant que vous dormez. Si vous souhaitez les mêmes vérifications au sein d'un pipeline, le CLI et cron vous offrent une troisième voie sans outil supplémentaire. Téléchargez Apidog pour configurer votre première suite de régression planifiée. C'est gratuit pour commencer, aucune carte de crédit n'est requise.