Périmètre sûr : ce guide s'applique exclusivement à vos propres applications — environnements de développement, 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 l'évasion de protections anti-bot.
Un défi CAPTCHA sur votre propre moteur de recherche interne transforme une suite de tests verte en suite rouge intermittente. La réponse tient en une phrase : ne désactivez pas la protection en préproduction, faites résoudre le défi par une API pendant l'exécution, puis injectez le token comme le ferait un navigateur réel. CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge et GeeTest v3 — l'essentiel de ce que les équipes déploient devant un formulaire de recherche.
Le cas typique : une plateforme SaaS hébergée chez OVHcloud ou Scaleway ajoute reCAPTCHA v3 devant /recherche, et le jour même les scénarios Playwright du pipeline CI échouent une fois sur trois. L'objectif ici : les remettre au vert de manière déterministe, sans toucher à la configuration de sécurité.
Pourquoi le défi apparaît sur vos environnements de test
Les runners d'intégration continue cochent presque toutes les cases d'un score faible : IP de datacenter, absence de cookies persistants, cadence régulière à la milliseconde près, empreinte incomplète en mode headless. Le moteur de risque voit exactement le profil qu'il est censé filtrer.
Deux conséquences : le défi ne se déclenche pas à chaque exécution, ce qui rend les tests instables (« flaky ») plutôt que franchement cassés ; et baisser min_score en préproduction seulement crée un écart avec la production, donc un angle mort de test. Traiter le défi comme une étape normale du scénario conserve la parité entre environnements.
Préparer l'environnement avant d'automatiser
| Prérequis | Détail |
|---|---|
| Autorisation | Application interne, ou autorisation écrite du propriétaire du système |
| Clé API | Stockée dans un secret CI ou un coffre, jamais en clair dans le dépôt |
| Plan | BASIC ($15/mois, 5 threads) pour une suite de tests ; STANDARD ($30/mois, 15 threads) si plusieurs pipelines tournent en parallèle |
| Environnement | Préproduction isolée, jeu de données de recherche reproductible |
| RGPD | Ne journalisez pas les requêtes de recherche contenant des données personnelles réelles ; utilisez un jeu de test anonymisé |
Le point RGPD n'est pas décoratif : une page de résultats interne rejoue souvent des requêtes saisies par de vrais utilisateurs, et les capturer dans vos logs crée un traitement de données. Un jeu de requêtes synthétiques règle le problème à la source. Côté dimensionnement, la facturation est basée sur les threads, résolutions illimitées : ce qui compte est le nombre de résolutions simultanées au pic.
Le déroulé du scénario, étape par étape
- Lancer la requête. Le test soumet une recherche depuis l'interface, comme un utilisateur.
- Détecter le widget. Attendez le conteneur du défi, pas un délai fixe : un
sleep(5)est la première cause de faux négatifs. - Extraire le sitekey. Lisez
data-sitekeydepuis le DOM plutôt que de le coder en dur : il change d'un environnement à l'autre. - Envoyer la tâche à l'API avec le sitekey et l'URL de la page.
- Interroger le résultat jusqu'à obtention du token, avec un timeout global.
- Injecter le token dans le champ attendu, puis valider.
- Vérifier la page de résultats — nombre d'éléments, facettes, tri — pas seulement l'absence d'erreur HTTP.
Le déroulé est identique en Node.js, Go, Java ou PHP ; seul le client HTTP change. 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']
L'identifiant de tâche renvoyé sert au polling : gardez-le, il corrèle tout le scénario.
Observabilité et journalisation
Instrumentez chaque appel : temps de résolution, code retour HTTP, identifiant de tâche et profondeur de la file d'attente interne. Ces quatre signaux suffisent à distinguer une lenteur côté API d'une régression côté application.
Séparez les journaux par environnement et propagez l'identifiant de trace de votre outillage distribué (OpenTelemetry) jusqu'à l'appel CAPTCHA. Deux seuils d'alerte suffisent au quotidien : une dérive de plus de 50 % du temps de résolution médian sur sept jours, et plus de 2 % d'exécutions en timeout de polling.
Liste de contrôle avant de lancer la suite complète
- Le périmètre reste limité à vos applications ou à des sources autorisées.
- La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
- Durées d'appel et codes retour tracés à chaque exécution.
- Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires (3 tentatives, plafond 30 s).
- Les requêtes de test sont synthétiques, sans donnée personnelle réelle.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
| Le défi apparaît à chaque exécution | IP de runner mutualisé mal notée | Isolez le runner ou réduisez la cadence entre scénarios |
| Sitekey introuvable dans le DOM | Widget chargé après le rendu initial | Attendez le sélecteur du conteneur |
| Token accepté mais résultats vides | Le formulaire est validé avant la fin du rendu | Vérifiez un élément de la liste de résultats, pas le seul statut HTTP |
| Timeout de polling récurrent | Threads du plan saturés au pic | Sérialisez les scénarios ou passez au palier de threads supérieur |
FAQ
Combien de threads faut-il pour une suite de tests ?
Comptez les scénarios CAPTCHA réellement parallèles au pic, pas le nombre total de tests. Une suite classique tient dans BASIC ($15/mois, 5 threads) ; passez à STANDARD ($30/mois, 15 threads) si plusieurs pipelines partagent le compte.
CaptchaAI prend-il en charge hCaptcha sur mes environnements ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha ou GeeTest v4 (annoncé « à venir »). Les types couverts : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, CAPTCHA image/OCR et grilles d'images. CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) restent en bêta.
Comment rester conforme au RGPD dans mes journaux de test ?
Utilisez des requêtes de recherche synthétiques et appliquez à vos logs de test la même politique de rétention qu'ailleurs. Journalisez l'identifiant de tâche et les durées, pas le contenu saisi ; anonymisez toute donnée réelle avant de la verser dans le pipeline.
Vaut-il mieux désactiver le CAPTCHA en préproduction ?
C'est tentant, mais cela supprime précisément la partie du parcours à valider avant la mise en production. Gardez la protection active et traitez la résolution comme une étape du scénario : vous testez alors le comportement réel de la page, délais compris.
Guides connexes
- Le démarrage rapide CaptchaAI
- Tests QA CAPTCHA en environnements autorisés
- Tester vos formulaires web via l'endpoint API
- Intégrer la résolution CAPTCHA à votre CI
- Résoudre reCAPTCHA v2 via l'API
- Résoudre Cloudflare Turnstile via l'API
Vos scénarios de recherche méritent la même stabilité que le reste de votre suite. – Obtenez votre clé CaptchaAI.
