Güvenli kapsam: Bu kılavuz yalnızca size ait veya yetkilendirilmiş QA, staging ve ön üretim ortamları için geçerlidir. İçerik kendi CAPTCHA entegrasyonlarınız için tanılama, test ve gözlemlenebilirlik kalıplarını ele alır — üçüncü taraf siteleri veya yetkisiz akışları kapsamaz.
Bir QA koşusunda CAPTCHA sayısını azaltmanın en hızlı yolu daha fazla çözüm satın almak değil, aynı token'ı geçerlilik süresi içinde birden fazla adımda kullanacak biçimde senaryoyu yeniden kurgulamaktır. Çoğu ekipte gece çalışan regresyon paketi, her test adımında yeni bir doğrulama tetiklediği için hem yavaşlar hem de rastgele kırmızıya döner. Aşağıdaki dört kalıp — adımları gruplama, geçerlilik süresi içinde yeniden kullanım, kalıcı staging oturumu ve yapılandırılmış loglama — bu kesintileri ölçülebilir biçimde düşürür.
Adımları tek doğrulama etrafında gruplayın
Senaryonuzu tek tek adımlar olarak değil, işlem bloğu olarak düşünün. Bir e-ticaret staging ortamında sepete ekleme, adres girişi ve ödeme adımı ayrı ayrı çalıştırıldığında üç ayrı CAPTCHA doğrulaması tetiklenebilir; aynı üç adım tek bir oturum içinde art arda koşturulduğunda genellikle tek doğrulama yeterli olur. Türkiye'deki ekiplerin QA yükü büyük ölçüde bu tip ödeme ve satın alma akışlarında yoğunlaştığı için kazanç doğrudan koşu süresine yansır.
Blok sınırını nasıl seçersiniz
Pratik kural: bir token'ın kapsayabileceği en geniş işlem bloğunu belirleyin ve testi o bloğun sınırında bölün. Blok sınırı genellikle üç yerden birine denk gelir:
- Kimlik doğrulama sonrası ilk korunan sayfa.
- Ödeme adımının başladığı nokta.
- Oturumun bilinçli olarak sonlandırıldığı çıkış senaryosu.
Aynı senaryonun iki kurgusu
| Kurgu | Tetiklenen doğrulama | Koşu süresine etkisi |
|---|---|---|
| Her adım ayrı test, ayrı oturum | Adım başına bir doğrulama | En yüksek |
| Adımlar tek oturumda blok halinde | Blok başına bir doğrulama | Belirgin biçimde düşük |
Token'ı geçerlilik süresi içinde yeniden kullanın
Çözülen token'ın resmi bir geçerlilik penceresi vardır. Aynı senaryo içinde yeniden deneme yapıyorsanız — örneğin backend 5xx döndüğü için adımı tekrarlıyorsanız — o pencere kapanmadan yeni bir görev göndermeyin, elinizdeki token'ı tekrar kullanın. Bu, hem çözüm süresini hem de meşgul ettiğiniz thread sayısını düşürür.
Bütçeye yansıması
Thread bazlı faturalandırma bunu doğrudan bütçeye çevirir: BASIC ($15/ay, 5 thread) ile çalışan bir ekip, gereksiz görev gönderimlerini temizlediğinde aynı paketle belirgin biçimde daha fazla senaryo koşturabilir. Kur dalgalanmasının bütçeyi zorladığı bir pazarda, USD cinsinden öngörülebilir aylık maliyet ile daha az görev göndermek birlikte çalışır.
Staging oturumunu ayakta tutun
Her test adımında sıfırdan tarayıcı oturumu açmak, ortamınıza "ilk kez gelen ziyaretçi" sinyali gönderir ve gereksiz doğrulama sayısını artırır. Oturum çerezlerini senaryo boyunca koruyun, kimlik doğrulama adımını tek sefer çalıştırın ve sonraki adımları aynı oturumda sürdürün.
Test profilini sabitleyin
Test profilinizde Europe/Istanbul saat dilimini ve tr-TR locale değerini sabitlemek, tarih ve para birimi doğrulamalarında ortaya çıkan sahte hataları da ortadan kaldırır. Bu değerleri koşu başına rastgele bırakmak, doğrulama sayısıyla ilgisi olmayan hataları CAPTCHA sorunu gibi gösterir ve tanılamayı uzatır.
Sorun giderme
| Sorun | Önerilen çözüm |
|---|---|
| Test widget'ı bulamıyor | Staging ortamınızdaki seçici ve zamanlamayı kontrol edin |
CaptchaAI ERROR_NO_SLOT_AVAILABLE döndürüyor |
Dahili pipeline'da üstel geri çekilme ile yeniden deneyin |
| Backend QA token'ı reddediyor | Action/sitekey değerlerini gerçek yapılandırma ile karşılaştırın |
| Token süresi dolmuş görünüyor | Görev gönderimi ile form gönderimi arasındaki bekleme adımlarını kısaltın |
Gözlemlenebilirlik: ölçmediğinizi düzeltemezsiniz
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 kimlikten tüm senaryoyu yeniden oynatabilmek, olay sırasında tanılama süresini belirgin biçimde kısaltır.
Takip etmeye değer tek bir gösterge arıyorsanız bu koşu başına düşen çözüm sayısı olsun. Bu sayı düştükçe hem süreniz hem maliyetiniz düşer; yukarıdaki üç kalıbın işe yarayıp yaramadığını da tek başına gösterir.
Yayına almadan önce kontrol listesi
- Kapsam kesinlikle kendi uygulamalarınız veya yetkilendirilmiş kaynaklarla sınırlıdır.
- CaptchaAI anahtarı CI gizli deposunda veya kasada saklanır, kaynak kodda asla bulunmaz.
- Her çalıştırma için çağrı süresi ve yanıt kodu kayıt altına alınır.
- Geçici hatalar için idempotent yeniden deneme stratejisi kuruludur.
- Testler sürekli entegrasyon ortamınızdan tekrarlanabilir biçimde yeniden oynatılır.
- Kişisel veri içeren test verisi kullanılıyorsa KVKK kapsamındaki saklama ve maskeleme kuralları uygulanır.
Örnek QA çağrısı
Aşağıdaki Python örneği, kendi staging ortamınızdaki bir CAPTCHA widget'ını CaptchaAI üzerinden test etmek için kullanılan minimal akışı gösterir: görevi gönderin, taskId değerini saklayın, sonucu sorgulayın.
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()
Dönen token'ı senaryonun geri kalanında saklayın; her adımda submit_qa_recaptcha() çağırmak, bu yazının çözmeye çalıştığı sorunun ta kendisidir.
Sık sorulan sorular
Aynı token'ı kaç kez kullanabilirim?
Sınır sayı değil, süre: token'ın resmi geçerlilik penceresi kapanana kadar aynı senaryo içinde kullanabilirsiniz. Pencere kapandıktan sonra hedef backend token'ı reddeder ve yeni bir görev göndermeniz gerekir.
QA koşularım için hangi plan yeterli olur?
Gece çalışan tek bir regresyon paketi için BASIC ($15/ay, 5 thread) genellikle yeterlidir. Paralel job sayınız arttıkça thread ihtiyacınız da artar; STANDARD ($30/ay, 15 thread) çoğu CI kurulumunda rahat bir aralık sunar.
CaptchaAI hCaptcha'yı destekliyor mu?
Hayır. hCaptcha ve FunCaptcha (Arkose Labs) desteklenmiyor; GeeTest v4 için ise yalnızca "çok yakında" ifadesi geçerli. Desteklenen taraf reCAPTCHA v2/v3, Cloudflare Turnstile ve Cloudflare doğrulama akışı, GeeTest v3, görüntü/OCR, grid ve BLS. CaptchaFox (beta), Friendly Captcha (beta) ve Lemin (beta) beta aşamasındadır.
CI ortamında API anahtarını nasıl yönetmeliyim?
Anahtarı CI gizli yöneticisi, ortam değişkeni veya kasa hizmeti üzerinden enjekte edin. Kod tabanına işlenen bir anahtar derhal döndürülmelidir.
Geçici hatalarda ne yapmalıyım?
İdempotent yeniden deneme kurun: üstel geri çekilme (exponential backoff, örneğin 1s, 2s, 4s) ve bir üst sınır. Ağ hataları, 5xx yanıtları ve ERROR_NO_SLOT_AVAILABLE için yeniden deneme uygundur; kalıcı kimlik doğrulama hataları için değildir.
Güvenli ilgili kılavuzlar
- Beş dakikada ilk çözümünüz
- Yetkili ortamlarda CAPTCHA QA testleri
- Kendi formlarınızda endpoint testleri
- Tarayıcıda hata, API'de başarı: nedenini bulma
- 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.
