CAPTCHA'yı kendi QA pipeline'ınızda yönetme

Güvenli kapsam: Bu rehber yalnızca size ait veya yetkilendirilmiş QA, staging ve ön üretim ortamlarını kapsar. Kendi CAPTCHA entegrasyonlarınız için tanılama, test ve gözlemlenebilirlik kalıplarını ele alır; üçüncü taraf sitelerden veri kazımayı veya yetkisiz akışları kapsamaz.

Otomatik bir QA testi, bir kod hatası yüzünden değil karşısına çıkan bir CAPTCHA doğrulaması yüzünden kırmızıya döndüğünde asıl mesele testin kendisi değildir. Kendi staging ortamınızda reCAPTCHA veya Cloudflare Turnstile ile korunan bir formu test ediyorsanız, o doğrulamayı güvenilir ve tekrarlanabilir biçimde çözecek bir kalıba ihtiyacınız olur. Bu rehber, CaptchaAI API'sini kendi QA pipeline'ınıza bağlayıp çalıştırmaları yeşil tutmanın kalıplarını gösterir: kontrollü yeniden deneme, token izleme ve gözlemlenebilirlik.

CAPTCHA bir QA çalıştırmasını neden durdurur

Staging ortamınız üretimdeki bot korumasının bir kopyasını taşıdığında, test koşucunuz da tıpkı bir bot gibi görünür: yüksek istek hızı, eksik oturum çerezleri, headless tarayıcı imzası. Site de yanıt olarak sayfa yerine bir CAPTCHA döndürür ve senaryo tam bu noktada durur. Sık karşılaşılan tetikleyiciler şunlardır:

Doğru yaklaşım, testi CAPTCHA'yı çözecek şekilde tasarlamaktır; böylece doğrulama, senaryonun geri kalanını bloke etmez.

Uçtan uca akış

Kalıp dört adımdan oluşur ve her QA çalıştırmasında aynı sırayla ilerler:

1. Staging sayfanızdaki CAPTCHA widget'ını ve sitekey değerini tespit edin.
2. Görevi CaptchaAI'ye gönderin — reCAPTCHA için userrecaptcha, Cloudflare Turnstile için turnstile yöntemiyle.
3. Sonucu sorgulayın ve token'ı alın.
4. Token'ı QA backend'inize gönderip yanıtı doğrulayın.

Aynı akış reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3 ve image/OCR türlerinde çalışır; değişen tek şey gönderdiğiniz yöntemdir.

Kontrollü yeniden deneme ve zaman aşımı

Geçici hatalar, QA çalıştırmalarını gereksiz yere kırar. Her testi idempotent bir yeniden deneme stratejisiyle sarın: üstel geri çekilme (exponential backoff) ile 1s, 2s, 4s aralıklarla deneyin ve net bir üst sınır koyun. Yeniden denemeyi yalnızca ağ hataları, 5xx yanıtları ve ERROR_NO_SLOT_AVAILABLE gibi geçici durumlar için uygulayın; kalıcı kimlik doğrulama hataları için asla. Her denemeyi bir çalıştırma kimliğiyle (örneğin qa_run_id) etiketleyin ki hangi senaryonun kaç kez denendiği kayıt altında kalsın ve olay incelemesi kolaylaşsın.

İzleme ve gözlemlenebilirlik

Her token'ı üretildiği çalıştırmaya bağlayın; gönderim ve doğrulama zamanlarını birlikte kaydedin. 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 izlemeyle (örneğin OpenTelemetry) bağıntı kimliklerini eşleştirin. Tek bir bağıntı kimliğinden tüm senaryoyu yeniden oynatabilmek, bir olay sırasında tanılama süresini belirgin biçimde kısaltır.

Örnek: minimal 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 gereken en küçük akışı gösterir: görevi gönderin, 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()

Yayına almadan önce kontrol listesi

• Kapsam kesinlikle kendi uygulamalarınız veya yetkilendirilmiş kaynaklarla sınırlı.
• CaptchaAI API anahtarınız CI gizli deposunda veya bir kasa hizmetinde tutulur; kaynak kodda asla bulunmaz.
• Her çalıştırma için çağrı süresi ve HTTP yanıt kodu kayıt altına alınır.
• Geçici hatalar için idempotent yeniden deneme stratejisi kuruludur.
• Testler CI ortamınızdan tekrarlanabilir biçimde yeniden oynatılır.

Sorun giderme

Yerel bağlam: KVKK ve öngörülebilir maliyet

Türkiye'de e-ticaret ve fintech ekipleri, ödeme ve giriş akışlarını CI üzerinde sürekli test eder; bu akışların CAPTCHA ile korunması QA otomasyonunu doğrudan etkiler. İki noktaya dikkat edin:

• KVKK: Test verileriniz gerçek kişisel veri içeriyorsa Kişisel Verilerin Korunması Kanunu kapsamına girer. Örneklerde tr-TR yerel ayarları ve Europe/Istanbul saat dilimiyle üretilmiş kukla veri kullanın; gerçek müşteri verisini staging'e taşımayın.
• Maliyet: CaptchaAI thread bazlı ve aylık sabit USD fiyatlandırır. BASIC ($15/ay, 5 thread) küçük bir QA paketini rahatça karşılar; paralel test sayınız arttıkça ADVANCE ($90/ay, 50 thread) gibi üst planlara geçebilirsiniz. TL kuru dalgalansa da aylık USD maliyetiniz öngörülebilir kalır — bu, düzenli koşan bir QA pipeline'ı için somut bir avantajdır.

Sık sorulan sorular

Bu kalıp hangi CAPTCHA türlerinde çalışır?

reCAPTCHA v2 ve v3, Cloudflare Turnstile, GeeTest v3 ve image/OCR türlerinde aynı akış geçerlidir; yalnızca gönderdiğiniz yöntem değişir. CaptchaAI hCaptcha ve FunCaptcha türlerini çözmez, bu yüzden staging kopyanızı desteklenen bir türle kurgulayın.

API anahtarımı test kodunda saklayabilir miyim?

Hayır. Anahtarı CI gizli yöneticisi, ortam değişkeni veya bir kasa hizmeti üzerinden enjekte edin. Kod tabanına işlenmiş bir anahtar derhal döndürülmelidir.

Geçici hatalarda ne kadar yeniden denemeliyim?

İdempotent bir strateji kullanın: üstel geri çekilme (örneğin 1s, 2s, 4s) ve bir üst sınır. Ağ hataları, 5xx yanıtları ve ERROR_NO_SLOT_AVAILABLE için yeniden deneyin; kalıcı kimlik doğrulama hataları için denemeyin.

Paralel QA testlerinde CAPTCHA'ları aynı anda çözebilir miyim?

Evet. Birden çok görevi eşzamanlı gönderip her birini ayrı sorgulayın. Planınızdaki thread sayısı aynı anda kaç doğrulamayı işleyebileceğinizi belirler.

Güvenli ilgili kılavuzlar

• CaptchaAI hızlı başlangıç rehberi
• yetkili CAPTCHA QA testleri
• kendi formlarınızda CAPTCHA uç nokta testleri
• tarayıcı testi başarısız ama API çalışıyor: 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.