Périmètre sûr : Ce guide s'applique exclusivement à vos propres applications, environnements de QA, de préproduction ou de production, ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni le contournement de protections, ni l'évasion d'anti-bot.
Dans une suite Selenium interne, le défi CAPTCHA n'est pas un mur : c'est un champ de formulaire de plus à remplir. Votre test demande un token à l'API CaptchaAI, l'écrit dans le champ caché attendu par la page, puis soumet le formulaire comme n'importe quel autre scénario de recette. Tout le travail consiste donc à isoler cet appel dans un helper Python unique, à le rendre reproductible en intégration continue et à le mesurer.
Prérequis : clé API CaptchaAI et driver Selenium stable
Trois choses avant d'écrire la moindre ligne de test :
- Une clé API exposée au runner via une variable d'environnement (
CAPTCHAAI_KEY), jamais écrite dans le dépôt. - Un Chrome headless épinglé : figez les versions du navigateur et du driver dans l'image CI, sinon vos échecs mesureront des mises à jour de Chrome, pas votre application.
- Un plan adapté au parallélisme : la facturation CaptchaAI se fait au thread simultané, avec un nombre de résolutions illimité par thread. BASIC ($15/mois, 5 threads) couvre une suite de recette classique ; STANDARD ($30/mois, 15 threads) convient si votre CI lance plusieurs jobs Selenium en parallèle. La facturation est en dollars US.
Un helper Python qui renvoie le token CAPTCHA
Centralisez l'appel dans une seule fonction — get_recaptcha_token(sitekey, page_url), par exemple — appelée par tous vos tests : quand l'API évolue ou qu'un timeout change, vous corrigez un seul endroit. Le squelette d'envoi ressemble à ceci :
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
def submit_recaptcha_v2(sitekey: str, page_url: str) -> str:
payload = {
'clientKey': API_KEY,
'task': {
'type': 'NoCaptchaTaskProxyless',
'websiteURL': page_url,
'websiteKey': sitekey,
},
}
resp = requests.post('https://api.captchaai.com/createTask', json=payload, timeout=30)
resp.raise_for_status()
return resp.json()['taskId']
L'envoi renvoie un identifiant de tâche ; l'interrogation du résultat se fait ensuite en boucle. Deux règles évitent la majorité des suites instables : un intervalle de polling d'au moins 5 s, et un timeout global explicite plutôt qu'une boucle infinie.
Côté types, un test Cloudflare Turnstile écrit la valeur dans cf-turnstile-response, un test reCAPTCHA v2 ou v3 dans g-recaptcha-response. Turnstile se résout en moins de 10 s, reCAPTCHA v2 en moins de 60 s : dimensionnez vos WebDriverWait en conséquence, sinon le test échouera avant la réponse de l'API.
Où injecter le token dans la page
L'injection se fait en JavaScript depuis le driver : ciblez le champ caché, affectez la valeur, puis déclenchez le callback si le formulaire en attend un. Si le widget est rendu dans une iframe, lisez le sitekey dans le source de la page — inutile d'y basculer, le champ caché vit dans le document parent.
Vérifiez ensuite côté serveur : l'assertion porte sur la réponse du backend (redirection, code HTTP, entrée en base), pas sur la disparition du widget.
Exécuter la suite Selenium en CI : threads, timeouts et RGPD
Un cas courant chez les équipes francophones : un runner GitLab CI auto-hébergé chez OVHcloud ou Scaleway, qui joue la recette de nuit sur une préproduction en région Paris. Trois arbitrages y reviennent.
Le parallélisme. Alignez le nombre de workers pytest-xdist sur les threads de votre plan, pas sur les cœurs de la machine : six workers sur 5 threads produisent des attentes que vous prendrez pour de la lenteur applicative.
Les timeouts. Additionnez temps de résolution et temps de rendu : 30 s pour un scénario reCAPTCHA v2, c'est trop court. Faites échouer le test avec un message qui distingue « pas de token » de « token refusé ».
Les données de test. Sur les formulaires de connexion ou d'inscription, utilisez des comptes synthétiques : aucune donnée personnelle réelle ne devrait transiter par une suite automatisée. C'est la lecture RGPD la plus simple : pas de base légale à justifier pour un jeu de recette.
Observabilité : ce qu'il faut journaliser à chaque exécution
Instrumentez chaque appel CAPTCHA avec quatre champs : durée d'obtention du token, code retour HTTP, identifiant de tâche et nombre de tentatives de polling. Ces signaux suffisent à alimenter un tableau de bord de QA et à alerter quand la médiane dérive.
Séparez les logs par environnement et corrélez l'identifiant de tâche à votre traçage distribué (OpenTelemetry, par exemple) : vous rejouerez un scénario complet à partir d'un seul identifiant.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Le token arrive mais le formulaire ne part pas | Le callback de la page n'a pas été déclenché | Appelez explicitement le callback après l'affectation de la valeur |
| Le test expire avant la réponse | Timeout Selenium inférieur au temps de résolution | Alignez WebDriverWait sur le temps de résolution du type visé |
| Le backend refuse le token | Sitekey issu d'un autre environnement | Ré-extrayez le sitekey depuis la préproduction ciblée |
Liste de contrôle avant la mise en CI
- Le périmètre reste limité à vos applications ou à des environnements autorisés par écrit.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Le nombre de workers est aligné sur le nombre de threads du plan.
- Durées, codes retour et identifiants de tâche sont tracés à chaque exécution, avec un retry borné sur les erreurs transitoires.
- Les jeux de données de test sont synthétiques, sans donnée personnelle réelle.
FAQ
Quel plan choisir pour une suite Selenium qui tourne en parallèle ?
Comptez un thread par test Selenium simultané. BASIC ($15/mois, 5 threads) suffit à une suite qui lance cinq scénarios en parallèle ; au-delà, STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads).
CaptchaAI prend-il en charge hCaptcha dans mes tests ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs) ; GeeTest v4 est annoncé comme à venir. La prise en charge couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images, plus CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).
Le token est injecté mais le backend le refuse : que vérifier ?
Trois causes couvrent presque tous les cas : un sitekey issu d'un autre environnement, un token expiré entre la résolution et la soumission, ou une URL transmise à l'API différente de celle chargée par le driver. Journalisez ces trois valeurs : la comparaison devient immédiate.
Comment gérer les erreurs transitoires de l'API en pipeline ?
Mettez en place un retry avec backoff exponentiel borné — trois tentatives, doublement du délai, plafond à 30 s — et tracez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez le réseau du runner (DNS, certificats sortants) et le solde de votre clé avant de suspecter l'application testée.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester les CAPTCHA en environnement autorisé
- Valider l'endpoint API sur vos formulaires
- Brancher la résolution CAPTCHA sur votre CI
- Résoudre reCAPTCHA v2 via l'API
- Résoudre Cloudflare Turnstile via l'API
Fiabilisez vos scénarios de recette CAPTCHA dans vos propres environnements, avec des mesures reproductibles. – Obtenez votre clé CaptchaAI.
