Selenium Python : gérer un CAPTCHA sur vos formulaires internes

Périmètre sûr : ce guide ne couvre que vos propres applications — environnements de QA, de préproduction ou de production — et les systèmes pour lesquels vous détenez une autorisation écrite. Il ne décrit ni l'automatisation de sites tiers, ni l'évasion des protections anti-bot.

Un défi CAPTCHA ne casse pas votre navigateur : il casse votre assertion. Le test Selenium charge la page, remplit les champs, soumet — et repart avec une erreur de validation parce que le champ caché est resté vide. La réponse tient en une ligne de partage : Selenium pilote le navigateur, l'API CaptchaAI produit le token, et votre script l'écrit dans le formulaire avant la soumission. Le widget n'est jamais manipulé à la souris, et votre suite redevient déterministe.

Qui fait quoi : Selenium d'un côté, l'API de l'autre

Selenium sait attendre un élément, lire un attribut, exécuter du JavaScript et soumettre un formulaire. Il ne sait pas produire un token valide, et aucun sélecteur n'y changera rien. La résolution se fait côté serveur : vous envoyez le sitekey et l'URL de la page à CaptchaAI, vous recevez un token, vous le posez dans le champ prévu. Conséquence pratique : le mode headless suffit, le navigateur n'ayant qu'à charger la page pour exposer le sitekey.

Le déroulé en quatre temps

1. Selenium ouvre la page du formulaire dans votre environnement autorisé.
2. Le script lit le sitekey dans le DOM (data-sitekey sur le conteneur du widget) et relève l'URL courante.
3. CaptchaAI reçoit ces deux paramètres, traite la tâche, puis renvoie le token une fois la résolution terminée.
4. Le script injecte le token dans le champ caché, déclenche le callback si le formulaire en utilise un, puis soumet.

Récupérer le token depuis Python

L'appel se fait en deux temps : envoi de la tâche, puis interrogation du résultat. La fonction ci-dessous couvre le premier temps et renvoie l'identifiant de tâche que vous interrogerez ensuite en boucle, avec une pause de quelques secondes entre deux tentatives.

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']

La clé arrive par variable d'environnement, jamais en dur : dans une intégration continue, elle vient d'un secret de pipeline ou d'un coffre, et elle n'apparaît dans aucun log.

Injecter le token dans le champ g-recaptcha-response

Le champ cible est un textarea caché. Selenium l'alimente par driver.execute_script(), puis le formulaire part normalement. Deux détails séparent un test stable d'un test capricieux : si la page repose sur un callback JavaScript plutôt que sur une soumission classique, il faut appeler ce callback avec le token ; et si le widget se recharge après une redirection, le token précédent devient inutile — relisez le sitekey et recommencez.

Timeouts, retries et fenêtre de validité

Un token a une durée de vie courte. Structurez le test pour que l'injection et la soumission s'enchaînent immédiatement après la réception, et non après une série d'étapes intermédiaires. Pour les erreurs transitoires de l'API, un backoff exponentiel borné suffit : trois tentatives, délai doublé à chaque essai, plafond à 30 s. Au-delà, échouez franchement : une suite qui met 20 minutes à signaler une panne réseau coûte plus cher qu'une suite qui échoue en 90 s.

Mesurez aussi la durée d'obtention du token : une dérive régulière sur plusieurs jours signale un changement côté formulaire ou côté infrastructure, bien avant que les tests n'échouent.

Ce qu'il faut journaliser — et ce qu'il ne faut pas

Instrumentez chaque appel : durée totale, code retour HTTP, identifiant de tâche, taille de la file d'attente interne. Ces quatre signaux alimentent vos tableaux de bord de QA et vos alertes. Corrélés à votre traçage distribué (OpenTelemetry), ils permettent de rejouer un scénario complet depuis un identifiant unique. Séparez les journaux par environnement : développement, préproduction, production.

Côté RGPD, le réflexe utile est de ne jamais écrire le token complet ni les valeurs saisies dans le formulaire de test. Un identifiant de tâche et un horodatage suffisent au diagnostic ; les données personnelles de vos jeux de tests n'ont rien à faire dans les logs de CI, même en préproduction.

Exemple : la recette nocturne d'un portail RH interne

Une équipe QA fait tourner chaque nuit une suite Selenium contre un portail RH hébergé sur une instance OVHcloud, avec un reCAPTCHA v2 sur l'écran de connexion. Le pipeline lance cinq scénarios en parallèle depuis un runner en région parisienne. Cinq connexions simultanées, donc cinq résolutions en vol au maximum : le plan BASIC ($15/mois, 5 threads) couvre exactement ce besoin, et la facturation au thread signifie qu'une nuit chargée ne creuse pas la facture. En ajoutant la préproduction et le site de recrutement à la même fenêtre nocturne, le passage à STANDARD ($30/mois, 15 threads) a supprimé l'attente en file, sans changer une ligne de code.

Liste de contrôle avant d'activer la suite en CI

• Le périmètre reste limité à vos applications ou à des environnements explicitement autorisés.
• La clé API vit dans un secret de pipeline ou un coffre, jamais dans le dépôt.
• Durées, codes retour et identifiants de tâche sont tracés à chaque exécution.
• Le retry est idempotent, borné, et l'échec définitif est visible dans le rapport de test.
• Les jeux de données sont anonymisés et les journaux ne contiennent ni token complet ni donnée personnelle.
• La suite est rejouable à l'identique en local et depuis l'intégration continue.

FAQ

Combien de temps le token reste-t-il utilisable après la résolution ?

Quelques minutes seulement, et la fenêtre réelle dépend du formulaire. Traitez-le comme une valeur périssable : injectez et soumettez dans la foulée. Si une étape s'intercale (téléversement, navigation, saisie longue), redemandez un token.

CaptchaAI prend-il en charge hCaptcha sur mes formulaires internes ?

Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha (Arkose Labs). GeeTest v4 est annoncé comme à venir. Sont pris en charge : reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, les CAPTCHA image/OCR et les grilles d'images ; CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta) sont disponibles en bêta.

Quel plan choisir pour une suite de tests nocturne ?

Comptez en résolutions simultanées, pas en volume mensuel : la facturation porte sur les threads, avec des résolutions illimitées par thread. Une suite qui lance cinq navigateurs en parallèle tient dans BASIC ($15/mois, 5 threads) ; une matrice de plusieurs environnements passe confortablement avec STANDARD ($30/mois, 15 threads).

Le même déroulé fonctionne-t-il hors de Python ?

Oui. L'ordre des étapes — lire le sitekey, envoyer la tâche, interroger le résultat, injecter le token, soumettre — ne dépend ni du langage ni du pilote. Node.js, Go, Java ou C# suivent la même logique HTTP ; seule la couche d'automatisation change.

Guides connexes

• Le démarrage rapide CaptchaAI
• La QA CAPTCHA en environnements autorisés
• Tester l'endpoint API sur vos propres formulaires
• Intégrer la résolution CAPTCHA à votre CI
• Résoudre reCAPTCHA v2 via l'API
• Résoudre Cloudflare Turnstile via l'API

Une suite de tests qui ne dépend plus d'un clic manuel tourne sans surveillance la nuit. – Obtenez votre clé CaptchaAI.