Puppeteer + CaptchaAI für QA-Tests in eigenen Browser-Workflows

Anwendungsbereich: Dieser Leitfaden gilt für Browser-basierte Tests in eigenen oder autorisierten QA- und Staging-Umgebungen. Er zeigt, wie Sie Widgets erkennen, Verifikationspfade prüfen und Testläufe dokumentieren. Er beschreibt keine unautorisierten Logins, keine verdeckte Ausführung und keine Optimierung für fremde Websites.

Puppeteer ist für QA besonders nützlich, wenn Sie Browserzustand, Timing und DOM-Verhalten exakt beobachten möchten. Zusammen mit CaptchaAI lässt sich daraus ein stabiler Testpfad aufbauen: Widget erkennen, Aufgabe anstoßen, Ergebnis im QA-System verifizieren und den gesamten Lauf sauber protokollieren.

Sicherer Anwendungsbereich

Für publish-taugliche QA-Workflows sollte Puppeteer nur Aufgaben abdecken, die Sie in eigenen Umgebungen kontrollieren können:

• CAPTCHA-Widget auf einer Staging-Seite erkennen
• Lade- und Fehlerzustände dokumentieren
• CaptchaAI in eine Test-Suite integrieren
• Backend-Antworten eines eigenen Prüf-Endpoints verifizieren
• Regressionen nach Deployment reproduzierbar nachstellen

Der Mehrwert liegt damit in Transparenz und Teststabilität, nicht in verdeckter Browsersteuerung.

Puppeteer-Setup für 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 };
}

Für QA reicht meist ein bewusst schlichtes Setup. Wichtiger als Spezialflags ist, dass Ihre Suite reproduzierbar dieselbe Staging-Seite, dieselben Testdaten und dieselben Assertions verwendet.

CAPTCHA-Widget auf eigener Staging-Seite erkennen

Das erste Ziel jedes Testlaufs sollte die Diagnose des Widgets sein: Welcher Typ ist aktiv, welcher Sitekey wurde geladen, und in welchem Formularschritt tritt das Widget auf?

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

Wenn Sie zusätzlich Screenshots, Konsolenlogs und Netzwerkmetadaten archivieren, wird derselbe Lauf später deutlich leichter reproduzierbar.

CaptchaAI-Aufgabe senden

Sobald der Widget-Zustand klar ist, kann der QA-Lauf eine CaptchaAI-Aufgabe erzeugen und das Ergebnis für die eigene Testkette protokollieren.

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

In publish-tauglichen QA-Artikeln ist das Ergebnis ein Diagnoseartefakt: Es wird geloggt, gegen die eigene Umgebung geprüft und mit dem jeweiligen Testlauf verknüpft. Es ist kein Ersatz für Freigaben oder Geschäftslogik auf fremden Seiten.

QA-Endpoint validieren

Ein sauberer Testlauf endet nicht beim CAPTCHA-Ergebnis, sondern bei Ihrer eigenen Verifikation. Nutzen Sie dafür einen dedizierten Staging-Endpoint.

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

Sinnvolle Assertions in der Test-Suite sind z. B.:

• der erwartete Widget-Typ wurde erkannt
• der Staging-Sitekey stimmt mit der Deployment-Konfiguration überein
• der QA-Endpoint bestätigt den erwarteten Schritt
• die Antwortzeit bleibt innerhalb Ihres internen Budgets

Logging und Fehlerbehebung

Sichere verwandte Leitfäden

• CaptchaAI Schnellstart
• CAPTCHA-QA in autorisierten Testumgebungen
• Browser-Fehlerbild: API funktioniert, Browserlauf nicht
• CAPTCHA-Endpoints in eigenen Webformularen testen

Prüfen Sie Ihre Browser-Tests mit klaren QA-Metriken und reproduzierbaren Staging-Läufen – CaptchaAI unterstützt nachvollziehbare CAPTCHA-Validierung in eigenen Workflows.