Puppeteer + CaptchaAI pour vos tests Node.js internes

Puppeteer ne résout pas un défi CAPTCHA lui-même, et il n'a pas à le faire : le token attendu par votre formulaire se demande à l'API CaptchaAI avec le sitekey et l'URL de la page, puis s'écrit dans le champ caché juste avant la soumission. L'aller-retour prend quelques secondes et laisse votre suite Node.js aussi déterministe qu'un test sans CAPTCHA. Reste à décider où loger ce code, comment borner l'attente et quoi tracer à chaque exécution.

Périmètre sûr : ce guide s'applique à vos propres applications — 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'anti-détection.

Comment le token arrive dans votre page Puppeteer

Le déroulé est toujours le même, quel que soit le type de défi :

1. Puppeteer ouvre la page de test et lit le sitekey dans le DOM.
2. Votre helper envoie une tâche à l'API CaptchaAI avec le sitekey et l'URL de la page.
3. Le service résout le défi côté serveur ; votre code interroge le résultat (polling) jusqu'à obtenir le token.
4. Puppeteer injecte le token dans le champ attendu via page.evaluate, puis soumet le formulaire.

Aucune extension de navigateur, aucun script tiers dans la page : le navigateur de test reste celui que vos développeurs utilisent au quotidien. C'est ce qui rend l'approche compatible avec un environnement headless en CI.

Prérequis de l'environnement de test

CaptchaAI facture des threads simultanés, pas des résolutions à l'unité, et le nombre de résolutions par thread n'est pas plafonné : une suite de tests tient largement dans BASIC ($15/mois, 5 threads), et STANDARD ($30/mois, 15 threads) couvre une CI qui parallélise ses jobs.

Écrire le helper de résolution

Définissez une fonction qui envoie la tâche, puis une seconde qui interroge le résultat. Gardez-les dans un module séparé : vos tests appellent le helper, ils n'appellent jamais l'API directement.

Exemple Node.js :

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;
}

Côté test, l'attente doit être bornée. Fixez un timeout global cohérent avec le type de défi : Cloudflare Turnstile se résout généralement en moins de 10 s, reCAPTCHA v2 en moins de 60 s. Un test qui attend trois minutes ne signale plus rien d'utile ; il bloque simplement le pipeline.

Injecter le token et soumettre

Une fois le token récupéré, page.evaluate écrit la valeur dans le champ attendu — cf-turnstile-response pour Turnstile, g-recaptcha-response pour reCAPTCHA v2 — puis le test déclenche la soumission normale du formulaire. Deux règles évitent la majorité des faux négatifs :

• Injectez immédiatement. Un token a une durée de vie courte ; si votre test enchaîne des captures d'écran entre la réception et la soumission, il peut expirer.
• Attendez le sélecteur, pas un délai fixe. page.waitForSelector sur le conteneur du défi est fiable ; un setTimeout de deux secondes ne l'est pas quand la CI est chargée.

Mesurer plutôt que supposer

Tracez pour chaque exécution la durée d'obtention du token, le code HTTP de retour, l'identifiant de tâche et la profondeur de votre file d'attente interne. Ces quatre valeurs suffisent à distinguer trois causes qu'on confond souvent : un service lent, un formulaire modifié par une release, et une CI saturée.

Séparez les journaux par environnement et corrélez les identifiants avec votre traçage distribué, OpenTelemetry par exemple : vous rejouerez un scénario complet à partir d'un seul identifiant.

Exemple : une suite QA hébergée en Europe

Prenons une équipe dont les runners tournent sur OVHcloud et qui exécute sa suite Puppeteer chaque nuit sur un formulaire d'inscription protégé par Turnstile. Deux points méritent son attention. La latence d'abord : le temps mesuré côté test inclut l'aller-retour réseau depuis le runner, donc comparez des exécutions issues de la même région, jamais un poste de développeur et un runner mutualisé. Le RGPD ensuite : vos journaux de test ne doivent contenir ni adresse e-mail réelle ni identifiant de compte client. Travaillez sur un jeu de données synthétique en préproduction et limitez la rétention des logs au strict nécessaire. La facturation, elle, reste en dollars US quelle que soit la région.

Dépannage

Liste de contrôle avant intégration en CI

• Le périmètre est limité à vos applications ou à des sources explicitement autorisées.
• La clé CaptchaAI vit dans un secret CI ou un coffre, jamais dans le code source.
• Les durées d'appel et les codes retour sont tracés à chaque exécution.
• Un retry idempotent avec backoff exponentiel borné couvre les erreurs transitoires.
• Les scénarios sont rejouables à l'identique depuis le pipeline, sans intervention manuelle.

FAQ

Quelle offre CaptchaAI faut-il pour une suite de tests ?

BASIC ($15/mois, 5 threads) suffit à la plupart des suites QA, puisque la limite porte sur le nombre de résolutions simultanées et non sur le volume mensuel. Passez à STANDARD ($30/mois, 15 threads) si votre CI lance plusieurs jobs Puppeteer en parallèle.

Combien de temps le token reste-t-il valide ?

Quelques minutes seulement, selon le type de défi. Concevez le test pour injecter et soumettre dans la foulée ; ne mettez jamais un token en cache pour le réutiliser dans un scénario ultérieur.

CaptchaAI prend-il en charge hCaptcha pour mes tests ?

Non — hCaptcha n'est pas pris en charge, pas plus que FunCaptcha. Sont couverts reCAPTCHA v2 et v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 et les CAPTCHA image ou texte, auxquels s'ajoutent CaptchaFox (bêta), Friendly Captcha (bêta) et Lemin (bêta).

Faut-il un proxy pour tester un formulaire interne ?

Rarement. Si votre préproduction est accessible publiquement, la tâche proxyless suffit. Un proxy ne sert que si la page n'est joignable que depuis un réseau précis, et il ajoute alors une latence à surveiller.

Guides connexes

• Le démarrage rapide de l'API
• Tester les CAPTCHA en environnement autorisé
• Valider l'endpoint sur vos formulaires web
• Brancher la résolution CAPTCHA dans votre CI
• Résoudre reCAPTCHA v2 via l'API
• Résoudre Cloudflare Turnstile via l'API

Passez d'une suite Puppeteer capricieuse à des exécutions reproductibles, mesurées et documentées. – Obtenez votre clé CaptchaAI.