Puppeteer + CaptchaAI ile kendi tarayıcı akışlarınızda QA testleri

Güvenli kapsam: Bu rehber yalnızca size ait veya yetkilendirilmiş QA, staging ve ön üretim ortamları içindir. Anlatılan her adım kendi CAPTCHA entegrasyonlarınızı doğrulamaya yöneliktir — üçüncü taraf siteleri veya izinsiz akışları kapsamaz.

Kendi staging formunuzdaki reCAPTCHA veya Turnstile entegrasyonunun gerçekten çalıştığını nasıl doğrularsınız? En güvenilir yol, gerçek bir tarayıcıyı sürücü olarak kullanmaktır: Puppeteer ile bir Chrome oturumu açar, CaptchaAI ile widget'ın token'ını çözer ve backend'inizin bu token'ı kabul edip etmediğini uçtan uca görürsünüz. Birim testleri bu son adımı — token'ın gerçek DOM'a enjekte edilip form gönderiminde doğrulanmasını — genelde atlar; işte o boşluğu tarayıcı tabanlı bir smoke test kapatır.

Aşağıda reCAPTCHA v2, reCAPTCHA v3 ve Cloudflare Turnstile için kurulumdan token doğrulamasına kadar olan akışı, kendi ortamınızda tekrarlanabilir bir QA testine dönüştürüyoruz.

Bu akış hangi durumlar için uygundur

• Yalnızca size ait veya yetki verilmiş staging formları ve API'ler.
• Tarayıcı tabanlı entegrasyon ve smoke testleri.
• reCAPTCHA v2/v3, Turnstile ve GeeTest v3 doğrulamaları (hCaptcha ve FunCaptcha CaptchaAI tarafından desteklenmez).
• Sahte kullanıcılar, test formları, örnek ödeme akışları ve test token'ları.
• QA çalıştırması başına loglama ve izlenebilirlik.

Puppeteer'ı QA ortamınıza kurma

Tek bağımlılık Puppeteer'ın kendisidir; testleri CI üzerinde çalıştırmak için ek bir eklentiye ihtiyacınız yoktur.

npm install puppeteer

Tarayıcıyı headless modda ve CI konteynerlerinde sorun çıkarmayan --no-sandbox bayrağıyla başlatın:

const puppeteer = require('puppeteer');

async function launchQa() {
  return puppeteer.launch({ headless: 'new', args: ['--no-sandbox'] });
}

Staging formunuzdaki CAPTCHA widget'ını bulma

Testin ilk adımı, sayfanın gerçekten bir CAPTCHA widget'ı içerdiğini ve sitekey değerinin beklediğiniz yapılandırmayla eşleştiğini doğrulamaktır. reCAPTCHA v2 için sitekey, .g-recaptcha öğesinin data-sitekey özniteliğinde bulunur:

const page = await (await launchQa()).newPage();
await page.goto('https://staging.example.com/qa-form');
const sitekey = await page.$eval('.g-recaptcha', el => el.dataset.sitekey);

Seçici boş dönerse widget henüz yüklenmemiş demektir; tespitten önce bir waitForSelector çağrısı ekleyin.

CaptchaAI'ye çözüm görevi gönderme

sitekey ve pageurl elinizde olduğunda görevi in.php uç noktasına gönderin, ardından res.php üzerinden sonucu periyodik olarak sorgulayın. Aşağıdaki fonksiyon, token hazır olana kadar beş saniyede bir sorgulama yapar:

const fetch = require('node-fetch');
const KEY = process.env.CAPTCHAAI_API_KEY;

async function solve(sitekey, pageurl) {
  const submit = await fetch(`https://ocr.captchaai.com/in.php?key=${KEY}&method=userrecaptcha&googlekey=${sitekey}&pageurl=${pageurl}&json=1`).then(r => r.json());
  while (true) {
    await new Promise(r => setTimeout(r, 5000));
    const res = await fetch(`https://ocr.captchaai.com/res.php?key=${KEY}&action=get&id=${submit.request}&json=1`).then(r => r.json());
    if (res.status === 1) return res.request;
  }
}

Turnstile için method parametresini turnstile, GeeTest v3 için geetest yapmanız yeterli; sorgulama döngüsü aynı kalır.

Token'ı QA backend'inizde doğrulama

Asıl testin değeri buradadır. Çözülen token'ı, dahili QA backend uç noktanıza (örneğin https://staging.example.com/checkout-test) form gönderiminin beklediği gövdeyle iletin ve dönen durum kodunu kontrol edin. Test, backend g-recaptcha-response (Turnstile için cf-turnstile-response) alanını doğruladığında başarılı sayılır. Böylece yalnızca token'ın çözüldüğünü değil, uygulamanızın onu doğru işlediğini de kanıtlarsınız.

Yerel senaryo: e-ticaret ödeme akışı QA'si

Türkiye'deki geliştirici ekiplerin büyük bölümü e-ticaret ve ödeme entegrasyonları üzerinde çalışır; ödeme adımına eklenen bir CAPTCHA, regresyon testlerinde en kolay gözden kaçan noktadır. Staging kopyanızda tr-TR yerel ayarı, Europe/Istanbul saat dilimi ve +90 formatında sahte kullanıcı verileriyle bir "sepete ekle → ödeme → doğrulama" akışı kurun; her sürümde Puppeteer bu akışı baştan sona oynatarak CAPTCHA'nın ödeme gönderimini engellemediğini doğrulasın. Test verilerinde gerçek kişisel veri kullanmayın — KVKK kapsamında staging ortamlarında yalnızca sentetik veri tutmak hem uyumluluk hem de tekrarlanabilirlik açısından doğru yaklaşımdır.

Örnek: Python ile minimal QA akışı

Ekibiniz Node.js yerine Python ile test yazıyorsa aynı akış createTask/getTaskResult uç noktalarıyla da kurulabilir. Aşağıdaki örnek, kendi staging ortamınızdaki bir reCAPTCHA widget'ını gönderip sonucu almanın minimal biçimini gösterir:

import os
import requests

API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL']  # ör. https://staging.example.com/qa-login
QA_SITE_KEY = os.environ['QA_SITE_KEY']


def submit_qa_recaptcha() -> str:
    payload = {
        'clientKey': API_KEY,
        'task': {
            'type': 'NoCaptchaTaskProxyless',
            'websiteURL': QA_PAGE_URL,
            'websiteKey': QA_SITE_KEY,
        },
    }
    response = requests.post(
        'https://api.captchaai.com/createTask',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()['taskId']


def fetch_qa_result(task_id: str) -> dict:
    payload = {'clientKey': API_KEY, 'taskId': task_id}
    response = requests.post(
        'https://api.captchaai.com/getTaskResult',
        json=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()

Loglama ve gözlemlenebilirlik

Her QA çalıştırması için yapılandırılmış günlükler üretin: çözüm süresi, HTTP yanıt kodu, görev kimliği, yeniden deneme sayısı ve kuyruk derinliği. Ortamları (geliştirme, staging, ön üretim) ayrı kanallara yazın ve dağıtık izleme (örneğin OpenTelemetry) ile bağıntı kimliklerini eşleştirin — tek bir kimlikten tüm senaryoyu yeniden oynatabilmek, bir hata durumunda tanılama süresini belirgin biçimde kısaltır. Pipeline çalıştırmalarınızdan medyan ve P90 değerlerini toplayın; bu sayılar yalnızca kendi staging ortamınız için gösterge niteliğindedir, mutlak bir SLA değildir.

QA kontrol listesi

• Kapsam kesinlikle kendi uygulamalarınız veya yetki verilmiş kaynaklarla sınırlı.
• CaptchaAI API anahtarı CI gizli deposunda veya kasada; kaynak kodda asla değil.
• Her çalıştırmada çözüm süresi ve yanıt kodu kayıt altında.
• Geçici hatalar için idempotent yeniden deneme stratejisi kurulu.
• Testler CI ortamınızdan tekrarlanabilir biçimde yeniden oynatılıyor.

Sorun giderme

Sık sorulan sorular

Bu QA akışı üretim trafiğini etkiler mi?

Hayır. Tüm örnekler staging.example.com veya kendi QA alan adınız gibi yetkilendirilmiş ortamları varsayar. Üretimdeki CAPTCHA korumasını doğrulamak için onu kendi staging kopyanızda yeniden üretin.

CaptchaAI bu akışta hangi CAPTCHA türlerini çözer?

reCAPTCHA v2 ve v3, Cloudflare Turnstile ve GeeTest v3 desteklenir. hCaptcha ve FunCaptcha (Arkose Labs) desteklenmez; testlerinizi desteklenen türler üzerinde kurgulayın.

API anahtarımı test kodunda saklayabilir miyim?

Hayır. Anahtarı CI gizli yöneticisi, ortam değişkeni veya kasa üzerinden enjekte edin. Depoya işlenmiş bir anahtar derhal yeniden üretilmelidir (rotate).

Puppeteer yerine Playwright veya Selenium kullanabilir miyim?

Evet. Tarayıcı katmanı değişse de in.php/res.php akışı aynı kalır; token'ı DOM'a enjekte eden kısmı kendi sürücünüze uyarlamanız yeterli.

QA testleri için hangi CaptchaAI planı yeterli?

Çoğu QA pipeline'ı düşük eşzamanlılıkla çalışır; BASIC ($15/ay, 5 thread) genellikle yeterlidir. Paralel test sayısını artırdıkça thread ihtiyacınıza göre üst planlara geçebilirsiniz.

İlgili güvenli rehberler

• CaptchaAI hızlı başlangıç rehberi
• Yetkili ortamlarda CAPTCHA QA testleri
• Kendi formlarınızda CAPTCHA uç nokta testleri
• Tarayıcı testi başarısız ama API başarılı: hata ayıklama
• reCAPTCHA v2'yi API ile çözme
• Cloudflare Turnstile'ı API ile çözme
• GeeTest v3'ü API ile çözme

CAPTCHA entegrasyonunuzu kendi ortamınızda CaptchaAI ile doğrulayın.