Déboguer l'extension CaptchaAI avec captchaai.com/emulator

Périmètre sûr : ce guide s'applique exclusivement à vos propres applications, à vos 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 pas l'automatisation de sites tiers.

L'émulateur captchaai.com est une page de test contrôlée : vous y reproduisez le comportement de l'extension CaptchaAI hors de vos vraies applications, puis vous observez chaque étape — chargement de l'extension, sélection du gestionnaire de CAPTCHA, injection du token — au lieu de la deviner. C'est toute la différence entre un débogage reproductible et un cycle d'essais-erreurs sur la production. La règle qui fait tenir l'ensemble : traitez l'extension comme un workflow de navigateur, pas comme une case à cocher activée une seule fois.

Les quatre variables qui font échouer l'extension

• L'état du compte : la bonne clé et un solde suffisant, chargés dans le bon profil.
• Le profil de navigateur : dédié aux tests et identique d'un lancement à l'autre.
• Le gestionnaire de CAPTCHA : le type sélectionné correspond bien à la page.
• Le comportement après résolution : le token est appliqué dans la session qui a déclenché le défi, pas dans une autre.

Le déroulé du débogage, étape par étape

Trois étapes suffisent, dans cet ordre :

1. Isolez l'environnement. Séparez la QA de la production, stockez la clé CaptchaAI en secret CI, et chargez un profil de navigateur dédié via --user-data-dir avec un chemin d'extension fixe.
2. Encapsulez l'appel à CaptchaAI dans une fonction réutilisable qui prend le sitekey et l'URL de votre page, retourne un token et trace la durée et le code retour.
3. Vérifiez le token côté backend, dans la même session que celle qui a déclenché le défi, avant toute opération métier.

La facturation se fait au thread — BASIC ($15/mois, 5 threads) au premier palier, résolutions illimitées par thread — donc multiplier les tests ne gonfle pas la note. Voici un exemple commenté qui crée une tâche Turnstile :

import fetch from 'node-fetch';

const API_KEY = process.env.CAPTCHAAI_KEY;

export async function createTurnstileTask(siteKey, pageUrl) {
  const res = await fetch('https://api.captchaai.com/createTask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      clientKey: API_KEY,
      task: {
        type: 'TurnstileTaskProxyless',
        websiteURL: pageUrl,
        websiteKey: siteKey,
      },
    }),
  });
  const data = await res.json();
  return data.taskId;
}

Instrumenter et journaliser chaque appel

Instrumentez les appels CAPTCHA pour obtenir des signaux exploitables : durée d'obtention du token, code retour HTTP, identifiant de tâche et taille de la file d'attente. Corrélez ces identifiants à votre traçage distribué (OpenTelemetry, par exemple) afin de rejouer un scénario complet à partir d'un seul identifiant, et gardez à l'œil l'écart entre « résolution réussie » et « workflow accepté ». Pensez RGPD au passage : minimisez les données personnelles qui transitent dans les logs, surtout sur une région européenne comme eu-west-3 (Paris).

Dépannage

Liste de contrôle avant la mise en production

• Le périmètre reste limité à vos propres applications ou à des sources autorisées.
• La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
• Un profil dédié et un chemin d'extension fixe rendent les exécutions rejouables.
• Les durées d'appel et les codes retour sont tracés à chaque exécution.
• Une stratégie de retry idempotent couvre les erreurs transitoires.

FAQ

Comment savoir si l'extension a bien injecté le token dans la page ?

Observez le champ de réponse attendu par le formulaire une fois le défi résolu, puis confirmez côté backend que la validation aboutit. Un token présent dans le DOM mais rejeté à la soumission signale presque toujours un décalage de session entre l'injection et l'envoi.

Faut-il un profil de navigateur dédié pour déboguer l'extension ?

Oui. Un profil dédié, chargé via --user-data-dir avec un chemin d'extension fixe, isole l'état du compte et évite qu'un cookie hérité ne fausse vos tests. C'est la condition d'un débogage reproductible : chaque lancement repart du même point connu.

CaptchaAI prend-il en charge hCaptcha via l'extension ?

Non — hCaptcha n'est pas encore pris en charge, tout comme FunCaptcha (Arkose Labs). L'extension et l'API couvrent reCAPTCHA v2/v3, Cloudflare Turnstile et Challenge, GeeTest v3 et les CAPTCHA image/OCR et grilles ; CaptchaFox, Friendly Captcha et Lemin sont en bêta.

Guides connexes

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

Fiabilisez vos workflows CAPTCHA avec une approche méthodique et reproductible. — Obtenez votre clé CaptchaAI.