Périmètre sûr : ce guide s'applique uniquement à vos propres applications et à vos environnements de QA, de préproduction ou de production — ou à tout système pour lequel vous disposez d'une autorisation écrite. Il ne couvre ni l'automatisation de sites tiers, ni les techniques d'évasion d'anti-bot.
Pour valider un parcours protégé par CAPTCHA sans désactiver la protection, votre suite Cypress délègue la résolution à CaptchaAI : une tâche Node récupère un token valide, une commande personnalisée l'injecte dans le champ attendu, et le scénario se poursuit jusqu'à l'assertion finale. Vous obtenez des tests E2E déterministes, exécutés contre exactement la même protection qu'en production.
C'est la différence entre un test qui passe en préproduction et un défaut qui ne se révèle qu'en production. Le formulaire réel exerce l'injection du token, le champ caché de réponse et le déclenchement du callback — trois chemins qu'une protection désactivée ne teste jamais.
Pourquoi garder le CAPTCHA actif en préproduction ?
La tentation est de neutraliser le CAPTCHA dans les environnements de test. Le tableau ci-dessous résume ce que chaque raccourci vous coûte :
| Approche | Ce que vous risquez |
|---|---|
| Désactiver le CAPTCHA en préproduction | Les bugs d'intégration et les différences de flux de soumission passent inaperçus |
| Clés de test « toujours valides » | L'injection du token et la gestion du callback ne sont jamais vérifiées |
| Résoudre via CaptchaAI | Parité complète avec la production, du chargement au callback |
La troisième ligne est la seule qui teste le formulaire tel que vos utilisateurs le rencontrent. Pour les types couverts — reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile et Cloudflare Challenge, GeeTest v3, image/OCR et grilles — vous gardez la protection en place et laissez CaptchaAI produire un token exploitable.
Une commande Cypress réutilisable pour vos tests E2E
Isolez toute la logique CAPTCHA dans une seule commande personnalisée. Elle demande un token à une tâche Node — côté Node, car la clé API ne doit jamais transiter par le navigateur — puis l'injecte dans le champ g-recaptcha-response :
Cypress.Commands.add('solveCaptcha', (sitekey, pageUrl) => {
return cy.task('captchaai:solve', { sitekey, pageUrl }).then((token) => {
cy.window().then((win) => {
win.document.getElementById('g-recaptcha-response').value = token;
});
});
});
Vos scénarios appellent ensuite cy.solveCaptcha(sitekey, pageUrl) sans se soucier du protocole sous-jacent : soumission de la tâche, interrogation régulière du résultat, injection. Pour un formulaire Cloudflare Turnstile, la même approche vise le champ cf-turnstile-response au lieu de g-recaptcha-response ; le reste du déroulé est identique. Placez la commande dans cypress/support/commands.js pour qu'elle soit disponible dans toute la suite.
Garder la suite rapide : cache de token et exécutions parallèles
Chaque résolution ajoute plusieurs dizaines de secondes à un scénario. Deux leviers limitent l'impact sur le temps total de la suite :
- Cache dans la TTL du token. Réutilisez un token tant qu'il reste valide plutôt que d'appeler CaptchaAI à chaque test. Isolez les caches par environnement pour qu'une exécution de préproduction ne pollue jamais la production.
- Exécutions parallèles. CaptchaAI facture au thread concurrent, pas à la résolution : chaque plan inclut un lot de threads — BASIC ($15/mois, 5 threads) — et des résolutions illimitées par thread. Vos machines Cypress parallèles partagent la même clé API et consomment ces threads en simultané, sans surcoût par CAPTCHA.
Regroupez les scénarios protégés par CAPTCHA dans une suite dédiée : vous les exécutez en parallèle des tests rapides plutôt que de les intercaler, et le temps de bout en bout reste maîtrisé.
Observabilité et journalisation
Quel que soit le langage de votre pack d'exemples, instrumentez les appels CAPTCHA pour obtenir des métriques exploitables : durée totale d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente interne. Ces signaux alimentent vos tableaux de bord de QA et vos alertes.
Corrélez chaque identifiant de tâche à votre traçage distribué — OpenTelemetry, par exemple — pour rejouer un scénario complet à partir d'un seul identifiant. Séparez les journaux par environnement (développement, préproduction, production). Côté conformité, gardez des comptes de test synthétiques : minimisez les données personnelles manipulées dans vos scénarios et vérifiez vos obligations RGPD avant d'introduire des données réalistes.
Dépannage
| Problème | Cause probable | Correctif |
|---|---|---|
cy.task expire |
La résolution a dépassé le délai par défaut | Augmentez defaultCommandTimeout et le timeout de la tâche |
| Token refusé à la soumission | Le token a expiré avant l'injection | Réduisez le délai entre la résolution et le clic de soumission |
data-sitekey introuvable |
Le CAPTCHA se charge dynamiquement | Ajoutez un cy.wait() explicite ou interceptez la requête |
| Callback jamais déclenché | Nom de callback personnalisé | Inspectez ___grecaptcha_cfg dans les DevTools |
| Échec en CI, succès en local | Variable d'environnement absente | Ajoutez CAPTCHAAI_KEY aux secrets de votre intégration continue |
Liste de contrôle avant la mise en production de vos tests
- Le périmètre reste strictement limité à vos propres applications ou à des sources autorisées.
- La clé CaptchaAI est stockée dans un secret CI ou un coffre, jamais dans le code source.
- Les durées d'appel et les codes retour sont tracés pour chaque exécution.
- Une stratégie de retry idempotent couvre les erreurs transitoires (backoff exponentiel borné).
- Les tests sont rejouables et reproductibles depuis votre intégration continue.
FAQ
Ce guide couvre-t-il l'automatisation de sites tiers ?
Non. Tous les exemples portent sur vos propres applications ou sur des environnements de test pour lesquels vous disposez d'une autorisation écrite. Si votre projet implique une source externe, validez d'abord les conditions d'utilisation et la base juridique avant toute automatisation.
Comment injecter le token dans un formulaire Turnstile plutôt que reCAPTCHA ?
Le principe reste identique : vous récupérez le token via la tâche Node, puis vous le posez dans le champ caché cf-turnstile-response au lieu de g-recaptcha-response. Ciblez ce champ dans la commande personnalisée et laissez le reste du scénario inchangé.
Comment brancher CaptchaAI dans mon pipeline d'intégration continue ?
Exposez votre clé sous forme de variable d'environnement (CAPTCHAAI_KEY) issue des secrets de votre CI — GitHub Actions, GitLab CI ou autre — et ne l'écrivez jamais en clair. Vos runners parallèles partagent la même clé et consomment les threads de votre plan.
CaptchaAI prend-il en charge hCaptcha pour mes tests Cypress ?
Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). CaptchaAI couvre reCAPTCHA v2 et v3, Cloudflare Turnstile et Challenge, GeeTest v3, ainsi que les CAPTCHA image/OCR et en grille ; GeeTest v4 est annoncé « à venir ».
Guides connexes
- Le démarrage rapide CaptchaAI
- Tester le CAPTCHA en environnements autorisés
- Tester l'endpoint API sur vos propres formulaires
- Intégrer la résolution CAPTCHA dans votre CI
- Résoudre reCAPTCHA v2 via l'API
- Résoudre Cloudflare Turnstile via l'API
Fiabilisez vos parcours protégés par CAPTCHA dans vos propres environnements, avec une méthode reproductible et mesurable. — Obtenez votre clé CaptchaAI.
