Périmètre sûr : ce guide ne s'applique qu'à vos propres applications — développement, QA, préproduction, production — ou à des systèmes pour lesquels vous disposez d'une autorisation écrite. Il ne traite ni de l'automatisation de sites tiers, ni de l'évitement des protections anti-bot.
Un test de bout en bout qui s'arrête devant un défi CAPTCHA ne vous apprend rien : il passe au rouge sans que votre application soit en cause. La réponse tient en une décision d'architecture : sortez la résolution du corps du test et confiez-la à un fixture pytest qui renvoie un token, comme un fixture renvoie une session de base de données. Le test décrit le parcours utilisateur, le fixture parle à l'API CaptchaAI, et votre suite Playwright redevient déterministe.
Étape 1 : cadrez le périmètre et rangez la clé API
Avant la première ligne de code, écrivez quels environnements la suite a le droit d'atteindre. Une liste blanche de domaines dans la configuration suffit, et elle évite qu'un test copié-collé pointe un jour vers une URL publique.
La clé CaptchaAI, elle, ne vit jamais dans le dépôt : secret de votre CI ou coffre applicatif, lu depuis une variable d'environnement au démarrage. Côté capacité, la facturation repose sur les threads — un thread correspond à une résolution en cours — et chaque plan inclut des résolutions illimitées par thread. Une suite locale s'accommode de BASIC ($15/mois, 5 threads) ; une recette de nuit qui lance douze workers en parallèle demande plutôt STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads).
Étape 2 : un fixture pytest qui renvoie un token
Le fixture n'expose qu'une seule chose au test : une fonction à appeler au moment où le formulaire est prêt. Elle reçoit le sitekey et l'URL de la page, et rend un token. Tout le reste — envoi de la tâche, interrogation du résultat, timeout, retry — reste enfermé dans le fixture.
Ce découpage a deux effets immédiats. Vos tests ne mentionnent plus CaptchaAI, donc ils restent lisibles pour quelqu'un qui découvre la suite. Et le jour où le type de défi change sur la page de connexion, un seul fichier bouge, pas les quarante tests qui traversent ce formulaire.
Exemple Python :
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']
Injectez ensuite le token dans le champ attendu par la page, puis laissez Playwright soumettre le formulaire comme le ferait un utilisateur. Les paramètres varient selon le type de défi — reCAPTCHA v2, Cloudflare Turnstile, GeeTest v3 — mais la mécanique du fixture, elle, ne bouge pas.
Étape 3 : paralléliser vos tests Playwright avec pytest-xdist, sans collisions
pytest-xdist répartit les tests sur plusieurs processus, et c'est là que les suites mal isolées deviennent instables. Un token est à usage unique et lié à une page : deux workers qui se le partagent produisent un échec impossible à reproduire en local.
Trois règles suffisent. Donnez à chaque worker son propre contexte de navigateur, donc ses propres cookies. Ne mettez jamais un token en cache entre deux tests. Et calez le nombre de workers sur les threads de votre plan : seize processus sur un plan à 5 threads n'accélèrent rien, ils créent une file d'attente côté client et des timeouts qui ressemblent à des régressions.
Étape 4 : instrumentez chaque appel CAPTCHA
Pour chaque résolution, enregistrez la durée totale d'obtention du token, le code retour HTTP, l'identifiant de tâche et la profondeur de votre file d'attente interne. Ces quatre signaux transforment un « la suite est lente ce matin » en diagnostic précis, et ils alimentent directement vos tableaux de bord de QA.
Séparez les journaux par environnement et propagez l'identifiant de tâche dans votre traçage distribué (OpenTelemetry, par exemple) : vous pourrez rejouer un scénario complet à partir d'un seul identifiant, ce qui raccourcit nettement l'analyse d'incident. Pensez aussi au volet RGPD — une capture d'écran prise après un échec de formulaire peut contenir des données personnelles. Excluez ou masquez ces champs avant de pousser les artefacts dans votre CI.
Un cas concret : la recette de nuit d'un éditeur SaaS
Une équipe qui héberge sa préproduction chez OVHcloud ou Scaleway lance sa suite Playwright à 2 h du matin, sur huit workers, contre une trentaine de parcours dont quatre traversent un formulaire protégé par Cloudflare Turnstile. Sans fixture partagé, ces quatre parcours produisaient un échec aléatoire par nuit — assez pour que l'équipe finisse par ignorer le rapport du matin.
Résolution extraite dans un fixture, retry avec backoff exponentiel borné, workers alignés sur le plan souscrit : le rapport redevient exploitable, et les échecs restants pointent de vraies régressions. La latence réseau depuis une région européenne (eu-west-3 Paris) pèse peu face au temps de résolution lui-même.
Liste de contrôle avant de brancher la suite en CI
-
Le périmètre est limité à vos applications ou à des environnements explicitement autorisés.
-
La clé CaptchaAI vient d'un secret CI ou d'un coffre, jamais du code source.
-
Durées, codes retour et identifiants de tâche sont tracés à chaque exécution.
-
Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
-
Le nombre de workers pytest-xdist ne dépasse pas les threads de votre plan.
-
Les artefacts d'échec (captures, traces) sont purgés des données personnelles.
FAQ
Quels types de CAPTCHA pouvez-vous couvrir dans une suite Playwright ?
En version générale : reCAPTCHA v2 (invisible, callback et Enterprise compris), reCAPTCHA v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR, les grilles d'images et BLS CAPTCHA. S'y ajoutent CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta). hCaptcha et FunCaptcha (Arkose Labs) ne sont pas pris en charge ; GeeTest v4 est annoncé comme à venir.
Combien de threads faut-il pour une suite parallélisée ?
Comptez un thread par résolution simultanée, pas par test. Une suite de huit workers dont deux parcours seulement croisent un défi CAPTCHA reste confortable sur BASIC ($15/mois, 5 threads) ; une recette complète lancée en parallèle sur plusieurs branches justifie STANDARD ($30/mois, 15 threads) ou ADVANCE ($90/mois, 50 threads). À l'intérieur d'un thread, les résolutions sont illimitées.
Que faire quand l'API renvoie une erreur transitoire ?
Appliquez un retry avec backoff exponentiel borné — trois tentatives, délai doublé à chaque essai, plafond à 30 secondes — et journalisez chaque échec avec son identifiant de tâche. Si l'erreur persiste, vérifiez la résolution DNS, les certificats de votre runner CI et le solde associé à votre clé avant de suspecter la suite.
Puis-je appliquer cette méthode à un site que je ne contrôle pas ?
Non. Le montage décrit ici suppose vos propres applications ou des environnements couverts par une autorisation écrite. Si un projet implique une source externe, examinez d'abord les conditions d'utilisation et la base juridique applicable avant d'écrire la moindre automatisation.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester les CAPTCHA dans des environnements autorisés
- Vérifier l'endpoint API sur vos formulaires
- Brancher la résolution CAPTCHA en intégration continue
- Résoudre reCAPTCHA v2 via l'API
- Résoudre Cloudflare Turnstile via l'API
Des tests qui échouent pour une bonne raison valent mieux qu'une suite verte par hasard. – Obtenez votre clé CaptchaAI.
