Yetkili kapsam: Bu rehber yalnızca size ait veya açıkça yetkilendirilmiş QA, staging ve ön üretim ortamları içindir. Anlatılan kalıplar kendi CAPTCHA entegrasyonlarınızı tanılamaya, test etmeye ve gözlemlemeye yöneliktir; üçüncü taraf sitelerini veya izinsiz akışları kapsamaz.
Staging ortamınızda formu gönderdiğinizde backend geçerli görünen token'ı reddediyorsa, sorunu en hızlı Chrome DevTools Protocol (CDP) ile görürsünüz: hangi isteğin token'ı taşıdığını, hangi başlıkla gittiğini ve sunucunun tam olarak neyi geri çevirdiğini protokol seviyesinde okursunuz. CDP; ağ trafiğini, sayfa yaşam döngüsünü ve JavaScript yürütmesini tarayıcının içinden dinler — bu sayede CaptchaAI ile kurduğunuz reCAPTCHA v2, Cloudflare Turnstile veya Cloudflare doğrulama akışı entegrasyonunu kara kutu gibi değil, adım adım tanılarsınız.
CDP tanılaması kara kutu testinden ne kazandırır?
Klasik uçtan uca testte forma bir token yapıştırır, yalnızca "başarılı/başarısız" sonucuna bakarsınız. Sorun çıktığında elinizde yalnızca bir hata mesajı kalır. CDP ise aradaki her adımı görünür kılar ve "CAPTCHA mı bozuk, yoksa entegrasyon mu yanlış" sorusunu tahminle değil, kanıtla yanıtlarsınız. Somut olarak şunları protokol seviyesinde okursunuz:
- Widget'ın hangi uç noktalara istek attığını ve bu isteklerin başlıklarını.
- reCAPTCHA v2 veya Turnstile token alanının doldurulup doldurulmadığını.
- Backend'e giden doğrulama isteğinin gövdesini ve dönen yanıt kodunu.
Türkiye'deki çoğu ekip için bu görünürlük, bir sürüm öncesi hata ayıklamada saatler kazandırır.
Yetkili kapsam
- Yalnızca size ait veya yetkilendirilmiş test sayfaları.
- Tarayıcı tanılaması, ağ inceleme ve istek yaşam döngüsü izleme.
- Kendi sayfalarınızda sitekey tespiti ve tür doğrulama.
- Backend doğrulama tanılaması ve token kontrolü.
Adım adım tanılama akışı
Aşağıdaki dört adım, bir CAPTCHA entegrasyonunu staging'de baştan sona tanılamak için izlediğimiz sıradır: önce ağ trafiğini dinler, sonra sitekey'i doğrular, ardından görevi gönderir ve son olarak backend yanıtını denetlersiniz.
1. Ağ trafiğini CDP ile izleme
CDP'nin Network.enable alanı, sayfanın attığı her isteği canlı olarak yayınlar. Aşağıdaki Playwright tabanlı minimal izleyici, staging ortamınızdaki CAPTCHA widget'ının hangi uç noktalara istek attığını konsola yazar:
import asyncio, json
from playwright.async_api import async_playwright
async def trace_qa():
async with async_playwright() as p:
browser = await p.chromium.launch()
ctx = await browser.new_context()
client = await ctx.new_cdp_session(await ctx.new_page())
await client.send('Network.enable')
client.on('Network.requestWillBeSent', lambda e: print(e['request']['url']))
Çıktıda recaptcha, turnstile veya challenges.cloudflare.com alan adlarına giden istekleri görürsünüz. Widget hiç istek atmıyorsa sorun büyük olasılıkla sayfa yükleme sırasında ya da seçici hatasındadır — token tarafına geçmeden önce burayı netleştirin.
2. Kendi test sayfanızda sitekey ve türü doğrulama
Kendi QA sayfanızı (örn. https://staging.example.com/captcha-demo) açın; .g-recaptcha öğesinden data-sitekey, .cf-turnstile öğesinden ise Turnstile sitekey değerini okuyun. Burada kritik nokta token alanının doğru olmasıdır: reCAPTCHA v2 için g-recaptcha-response, Turnstile için cf-turnstile-response. Bu ikisini karıştırmak, backend'in geçerli bir çözümü bile reddetmesinin en sık nedenidir. Okuduğunuz sitekey'i ve türü, backend'de beklenen yapılandırmayla birebir karşılaştırın.
3. CaptchaAI görevini QA ortamından gönderme
Sitekey ve tür doğrulandıktan sonra çözüm görevini CaptchaAI'ye gönderin. Klasik in.php / res.php akışında görevi in.php adresine iletir, durum CAPCHA_NOT_READY olduğu sürece res.php adresini periyodik olarak sorgularsınız. Çözüm süresini bir tanılama metriği olarak kaydedin; staging'de beklenmedik biçimde uzuyorsa sorun genellikle yanlış pageurl veya eksik action parametresindedir. CaptchaAI thread tabanlı çalışır: her plan eşzamanlı thread sayısıyla ölçeklenir ve thread başına çözüm sınırsızdır, bu yüzden QA test hacminizi thread sayısına göre planlayabilirsiniz.
4. Backend doğrulamasını CDP ile denetleme
Token'ı QA formuna yerleştirip gönderin ve backend'in döndürdüğü yanıt kodunu CDP'nin ağ günlüğünden okuyun. Sunucu 2xx yerine hata döndürüyorsa action, sitekey ve secret değerlerini sunucu yapılandırmasıyla karşılaştırın; çoğu red, token'ın geçersiz olmasından değil, doğrulama isteğinin yanlış anahtarla yapılmasından kaynaklanır. Google veya Cloudflare'in doğrulama uç noktasına giden siteverify isteğini CDP'de yakalayıp gövdesini incelemek, sorunu birkaç dakikaya indirir.
Türkiye'den bir senaryo: e-ticaret ödeme akışı QA'i
Türk ekiplerin en sık test ettiği akışlardan biri e-ticaret ödeme adımıdır. Diyelim ki Europe/Istanbul saat diliminde çalışan bir ekip, tr-TR yerelindeki bir ödeme formuna reCAPTCHA v2 ekledi ve staging'de token bazen kabul edilirken bazen reddediliyor. CDP ile ağ trafiğini izlediğinizde, reddedilen isteklerin hepsinin sayfa tam yüklenmeden gönderildiğini görürsünüz — yani sorun CAPTCHA'da değil, formun erken submit edilmesindedir. Bu ayrımı yalnızca protokol seviyesinde net biçimde görebilirsiniz. Bir not: kendi kullanıcı verilerinizle test ederken KVKK kapsamındaki kişisel verileri staging'e taşımayın; maskelenmiş ve sahte test verisi kullanın.
Sık karşılaşılan sorunlar
| Sorun | Önerilen çözüm |
|---|---|
| Test widget'ı bulunamıyor | Staging ortamınızdaki seçiciyi ve sayfa yükleme zamanlamasını kontrol edin |
CaptchaAI ERROR_NO_SLOT_AVAILABLE döndürüyor |
Dahili pipeline'da üstel geri çekilme ile yeniden deneyin |
| Backend QA token'ını reddediyor | action / sitekey / secret değerlerini gerçek yapılandırma ile karşılaştırın |
| Token doğru ama form gönderilmiyor | reCAPTCHA callback'inin tetiklenip tetiklenmediğini Runtime.evaluate ile denetleyin |
Gözlemlenebilirlik ve loglama
Her QA çalıştırması için yapılandırılmış günlükler üretin. Toplam token süresi, HTTP yanıt kodu, görev kimliği ve kuyruk derinliği gibi ölçümler tablolarınızı ve uyarılarınızı besler. Ortamlarınızı (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 bağıntı kimliğinden tüm senaryoyu yeniden oynatabilmek, olay anında tanılama süresini belirgin biçimde kısaltır. CDP'den okuduğunuz ağ olaylarını bu günlüklere işlerseniz, "token gönderildi ama backend reddetti" gibi ara durumları sonradan yeniden kurabilirsiniz.
Yayına almadan önce kontrol listesi
- Kapsam kesinlikle kendi uygulamalarınız veya yetkilendirilmiş kaynaklarla sınırlı.
- CaptchaAI anahtarı CI gizli deposunda ya da kasada saklanıyor, kaynak kodda asla bulunmuyor.
- Her çalıştırma için çağrı süresi ve yanıt kodu kayıt altına alınıyor.
- Geçici hatalar için idempotent yeniden deneme stratejisi kurulu.
- Testler sürekli entegrasyon ortamınızdan tekrarlanabilir biçimde yeniden oynatılıyor.
Minimal QA çağrısı örneği
Aşağıdaki Python örneği, kendi staging ortamınızdaki bir reCAPTCHA v2 widget'ını CaptchaAI'nin görev API'si üzerinden test eden minimal akışı gösterir. Anahtar ve URL'ler ortam değişkenlerinden gelir; hiçbir gizli değer koda gömülmez.
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()
Sık sorulan sorular
Sayfada reCAPTCHA v2 mı yoksa Turnstile mı olduğunu nasıl anlarım?
DOM'a bakın: .g-recaptcha[data-sitekey] reCAPTCHA v2'yi, .cf-turnstile[data-sitekey] Turnstile'ı işaret eder. Token alanları da farklıdır — reCAPTCHA v2'de g-recaptcha-response, Turnstile'da cf-turnstile-response. İkisini birbirine karıştırmak en yaygın entegrasyon hatasıdır.
Backend geçerli görünen token'ı reddediyorsa ilk neye bakmalıyım?
Önce token'ın kendisine değil, doğrulama isteğine bakın. Sunucunun siteverify isteğinde kullandığı secret ile sitedeki sitekey'in aynı projeye ait olduğunu doğrulayın. Redlerin çoğu bu eşleşme hatasından kaynaklanır.
CDP tanılamasını CI hattında çalıştırabilir miyim?
Evet. Headless Chromium'u CI içinde başlatın, CAPTCHAAI_KEY ve staging URL'lerini ortam değişkeni olarak geçin. Anahtarı kasadan veya CI gizli deposundan enjekte edin; kod tabanına asla yazmayın.
CaptchaAI'nin thread tabanlı fiyatı QA test hacmine uygun mu?
Küçük QA yükleri için BASIC ($15/ay, 5 thread) başlangıç noktasıdır ve thread başına sınırsız çözüm sunar. Daha yoğun regresyon paketlerinde daha fazla thread'li bir plana geçerek eşzamanlılığı artırırsınız — maliyet USD cinsinden aylık ve öngörülebilirdir.
Token'ı enjekte ettim ama form gönderilmiyor, neye bakmalıyım?
Genelde reCAPTCHA callback'i tetiklenmemiştir. Runtime.evaluate ile token alanının dolduğunu ve grecaptcha callback'inin çağrıldığını doğrulayın; form gönderimi çoğu zaman bu callback'e bağlıdır.
İlgili güvenli kılavuzlar
- CaptchaAI hızlı başlangıç rehberi
- Yetkili CAPTCHA QA testleri
- Kendi formlarınızda CAPTCHA endpoint 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.
