Puppeteer + CaptchaAI pour les tests QA dans vos workflows de navigateur

Périmètre : ce guide couvre des tests basés sur navigateur dans vos propres environnements QA et staging, ou des environnements explicitement autorisés. Il décrit la détection des widgets, la vérification des chemins backend et la documentation des exécutions. Il ne décrit pas de connexions non autorisées, ni d'exécution dissimulée, ni d'optimisation pour des sites tiers.

Puppeteer est particulièrement utile en QA quand il faut observer précisément l'état du navigateur, le timing et le comportement DOM. Combiné à CaptchaAI, il permet de bâtir un chemin de test stable : détecter le widget, déclencher la tâche, vérifier le résultat dans votre système QA et journaliser proprement l'exécution.

Périmètre sûr

Pour des workflows QA publiables, Puppeteer ne doit couvrir que des tâches que vous contrôlez dans vos propres environnements :

• détecter un widget CAPTCHA sur une page de staging,
• documenter les états de chargement et d'erreur,
• intégrer CaptchaAI à une suite de test,
• vérifier les réponses backend d'un endpoint de contrôle interne,
• rejouer les régressions après un déploiement.

La valeur ajoutée vient de la transparence et de la stabilité du test, pas d'une commande masquée du navigateur.

Setup Puppeteer pour QA

npm install puppeteer

import puppeteer from "puppeteer";

async function openQaPage(url) {
  const browser = await puppeteer.launch({ headless: "new" });
  const page = await browser.newPage();
  await page.goto(url, { waitUntil: "networkidle2" });
  return { browser, page };
}

Pour la QA, une configuration simple suffit. Plus important que les options spéciales : votre suite doit utiliser de manière reproductible la même page de staging, les mêmes données de test et les mêmes assertions.

Détecter un widget CAPTCHA sur une page staging interne

Le premier objectif de chaque exécution est le diagnostic du widget : quel type est actif, quel sitekey est chargé et à quelle étape du formulaire ?

async function detectCaptchaWidget(page) {
  return page.evaluate(() => {
    const recaptcha = document.querySelector(".g-recaptcha[data-sitekey]");
    if (recaptcha) {
      return {
        kind: "recaptcha_v2",
        sitekey: recaptcha.getAttribute("data-sitekey"),
        step: recaptcha.closest("form")?.getAttribute("data-step") || "unknown",
      };
    }

    const turnstile = document.querySelector(".cf-turnstile[data-sitekey]");
    if (turnstile) {
      return {
        kind: "turnstile",
        sitekey: turnstile.getAttribute("data-sitekey"),
        step: turnstile.closest("form")?.getAttribute("data-step") || "unknown",
      };
    }

    return null;
  });
}

Si vous archivez en plus captures d'écran, logs console et métadonnées réseau, la même exécution sera bien plus simple à reproduire.

Envoyer une tâche à CaptchaAI

Une fois l'état du widget connu, l'exécution QA peut créer une tâche CaptchaAI et journaliser le résultat pour la chaîne de test interne.

async function solveWithCaptchaAi(apiKey, widget, pageUrl) {
  const body = new URLSearchParams({
    key: apiKey,
    method: widget.kind === "turnstile" ? "turnstile" : "userrecaptcha",
    pageurl: pageUrl,
    json: "1",
  });

  if (widget.kind === "turnstile") {
    body.set("sitekey", widget.sitekey);
  } else {
    body.set("googlekey", widget.sitekey);
  }

  const submit = await fetch("https://ocr.captchaai.com/in.php", {
    method: "POST",
    body,
  });
  const submitJson = await submit.json();
  if (submitJson.status !== 1) {
    throw new Error(`CaptchaAI submit failed: ${submitJson.request}`);
  }

  for (let attempt = 0; attempt < 30; attempt += 1) {
    await new Promise((resolve) => setTimeout(resolve, 5000));
    const poll = await fetch(
      `https://ocr.captchaai.com/res.php?key=${apiKey}&action=get&id=${submitJson.request}&json=1`
    );
    const pollJson = await poll.json();
    if (pollJson.status === 1) {
      return pollJson.request;
    }
  }

  throw new Error("CaptchaAI polling timed out during QA test");
}

Dans des articles QA publiables, le résultat est un artefact de diagnostic : il est journalisé, contrôlé contre votre propre environnement et associé à une exécution donnée. Ce n'est ni un substitut à une approbation, ni une logique métier sur des sites tiers.

Valider la réponse contre un endpoint QA interne

Une exécution propre ne s'arrête pas au résultat CAPTCHA. Elle se termine sur votre propre vérification. Utilisez un endpoint dédié au staging.

async function verifyQaRun(token, widget, testRunId) {
  const response = await fetch("https://staging.example-app.test/qa/captcha/verify", {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({
      token,
      widgetType: widget.kind,
      sitekey: widget.sitekey,
      expectedStep: widget.step,
      testRunId,
    }),
  });

  if (!response.ok) {
    throw new Error(`QA verification returned ${response.status}`);
  }

  return response.json();
}

Quelques assertions utiles dans la suite :

• le type de widget attendu a été détecté,
• le sitekey de staging correspond à la configuration de déploiement,
• l'endpoint QA confirme l'étape attendue,
• le temps de réponse reste dans votre budget interne.

Logging et dépannage

Guides connexes sûrs

• Démarrage rapide CaptchaAI
• Tests QA CAPTCHA dans des environnements autorisés
• Diagnostic : l'API fonctionne mais l'exécution navigateur échoue
• Tester les endpoints CAPTCHA dans vos formulaires web

Validez vos tests navigateur avec des métriques QA claires et des exécutions staging reproductibles — CaptchaAI facilite la validation CAPTCHA dans vos propres workflows.