Kendi arama sonuçları sayfanızda CAPTCHA için QA testleri

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.

Kendi arama sonuçları sayfanız reCAPTCHA v3 ile korunuyorsa, uçtan uca test paketiniz sonuç HTML'ini çoğu zaman hiç göremez: doğrulama tamamlanmadan uç nokta boş liste ya da 403 döner. Cevap kısa — staging kopyanızda sahte veriyle çalışın, token'ı CaptchaAI API'si üzerinden üretin ve backend'inizin o token'ı gerçekten doğruladığını ayrı bir testle kanıtlayın. Aşağıda bu üç adım, ölçmeniz gereken metrikler ve CI'da en sık çıkan hatalar var.

Arama sayfaları neden ayrı bir QA vakası?

Arama uç noktası çoğu üründe en pahalı sorgudur; ekipler oraya sıradan bir form gönderiminden daha sıkı koruma koyar. Pratikte bu genellikle görünmez bir reCAPTCHA v3 doğrulaması demektir: kullanıcı hiçbir onay kutusu görmez, ama istemcinin yine de bir token üretmesi gerekir.

Testte asıl sorun şu: token üretilmediğinde anlamlı bir hata da almazsınız. Sonuç sayısı sessizce sıfıra düşer ve test, seçici hatası sanılan bir başarısızlıkla kapanır. Bu yüzden arama sayfası testinde doğrulama (assertion) sayısı normal bir form testinden fazladır.

Adım 1: Staging kopyasını sentetik veriyle doldurun

Üretim veritabanının kopyasıyla test etmeyin. Arama indeksinizi tamamen uydurma kayıtlarla yeniden kurun: sahte ürün adları, +90 5XX XXX XX XX biçiminde telefon alanları, tr-TR yerel ayarı ve Europe/Istanbul zaman damgaları. Bu yalnızca hijyen meselesi değil: KVKK kapsamında gerçek kişisel veri test ortamında da korunmak zorundadır; sentetik fixture ise bu tartışmayı baştan bitirir.

Sorgu kümenizi de sabitleyin: bol sonuç dönen, tek sonuç dönen ve hiç sonuç dönmeyen en az üç sorgu tutun. CAPTCHA akışı çalıştıktan sonra üçünün de doğru yanıtı vermesi, token'ın gerçekten kabul edildiğine dair en ucuz kanıttır.

Adım 2: Token'ı CaptchaAI ile üretin ve süreyi ölçün

Test istemciniz widget'ı tarayıcıda tamamlamak yerine sitekey ile sayfa adresini CaptchaAI API'sine gönderir ve token'ı geri alır. reCAPTCHA v3 için yayınlanan çözüm süresi tavanı 4 saniyenin altındadır; desteklenen türlerde başarı oranı yüksektir. Yine de test zaman aşımınızı tavana göre değil, gözlemlediğiniz p95 değerine göre belirleyin.

Planlama tarafında akılda tutulması gereken tek şey eşzamanlılık. CaptchaAI eşzamanlı thread üzerinden ücretlendirir; thread başına çözüm sayısı sınırsızdır. Yani soru "ayda kaç çözüm" değil, "aynı anda kaç test çözüm bekliyor". Tek bir QA hattı için BASIC ($15/ay, 5 thread) fazlasıyla yeterlidir; gecelik matris testleri onlarca işi paralel çalıştırıyorsa ADVANCE ($90/ay, 50 thread) daha gerçekçidir. Paralel iş sayısını thread sayınızın üstüne çıkarmayın — aksi halde ERROR_NO_SLOT_AVAILABLE yanıtları test gürültüsüne dönüşür.

Adım 3: Backend doğrulamasını kanıtlayın

Token'ın üretilmiş olması, backend'inizin onu doğruladığı anlamına gelmez. Asıl regresyon riski burada: doğrulama adımı bir refactor sırasında devre dışı kalırsa happy path testleri yeşil kalmaya devam eder.

Bunu yakalamak için üç negatif test ekleyin — boş token, süresi dolmuş token ve farklı bir action değeriyle üretilmiş token. Üçü de 4xx ile reddedilmelidir. Ardından pozitif tarafı tamamlayın: geçerli token ile dönen gövdenin fixture kayıtlarınızı içerdiğini ve sonuç sayısının beklenen değere eşit olduğunu doğrulayın.

Ö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 gereken minimum akışı gösterir: görevi gönderin, kimliği 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()

Bir e-ticaret ekibinin arama sayfasında ne oldu

İstanbul'da çalışan bir e-ticaret ekibini düşünün: katalog araması günlük trafiğin yaklaşık üçte birini karşılıyor ve sayfaya geçen ay görünmez bir reCAPTCHA v3 doğrulaması eklendi. Ertesi sabah gecelik test paketindeki 40 senaryodan 12'si kırmızıya döndü. İlk teşhis seçici değişikliğiydi; gerçek sebep token'sız isteklerin boş sonuç döndürmesiydi.

Ekip staging kopyasını sentetik katalogla yeniden kurdu, testlere CaptchaAI çağrısını ekledi ve çözüm süresini ayrı bir metrik olarak kaydetmeye başladı. İkinci fayda bütçe tarafındaydı: thread tabanlı aylık fiyatlandırma USD üzerinden sabit kaldığı için QA maliyeti kur oynaklığından etkilenmedi.

Her koşudan çıkması gereken veriler

Her QA koşusu yapılandırılmış log üretmelidir; aksi halde elinizde nedeni açıklanamayan, ara ara kırmızı yanan bir test paketi kalır. En az şu alanları kaydedin.

Bağıntı kimliklerini dağıtık izleme aracınızla (örneğin OpenTelemetry) eşleştirin: tek bir kimlikten tüm senaryoyu yeniden oynatabilmek, olay anında tanılama süresini kısaltır.

Sorun giderme

Yayına almadan önce kontrol listesi

• Kapsam yalnızca kendi uygulamalarınız ve yetkilendirilmiş ortamlarınızdır.
• CaptchaAI API anahtarı CI gizli deposunda veya kasada durur; depoya asla işlenmez.
• Her koşu için çözüm süresi, görev kimliği ve yanıt kodu kaydedilir.
• Geçici hatalar için idempotent yeniden deneme ve üst sınır tanımlıdır.
• Negatif token testleri (boş, süresi dolmuş, yanlış action) pakette yer alır.
• Fixture verisi tamamen sentetiktir, üretim kaydı kopyalanmaz.

Sık sorulan sorular

Staging'deki reCAPTCHA v3 puanı üretimden neden farklı çıkıyor?

Puan; alan adı geçmişi, trafik hacmi ve istemci davranışının birleşimiyle hesaplanır; yeni bir staging alan adının böyle bir geçmişi yoktur. Testlerinizi puan eşiğine göre değil, "token üretildi mi, backend kabul etti mi" sorusuna göre kurgulayın.

QA testleri için hangi plan yeterli?

Tek bir CI hattı için BASIC ($15/ay, 5 thread) genellikle yeterlidir. Karar kriteri aylık toplam çözüm sayısı değil, aynı anda kaç testin çözüm beklediğidir; thread başına çözüm sınırsızdır.

CaptchaAI hCaptcha'yı destekliyor mu?

Hayır. hCaptcha ve FunCaptcha (Arkose Labs) desteklenmiyor; GeeTest v4 için yalnızca "çok yakında" ifadesi geçerli. Desteklenen türler reCAPTCHA v2/v3 (Enterprise varyantları dahil), Cloudflare Turnstile, Cloudflare doğrulama akışı, GeeTest v3, görüntü/OCR, grid ve BLS; CaptchaFox (beta), Friendly Captcha (beta) ve Lemin (beta) ise beta aşamasındadır.

Token'ı ne kadar süre içinde kullanmalıyım?

Token'lar kısa ömürlüdür; çözüm döndükten sonra isteği geciktirmeden gönderin. Test adımları arasında uzun bekleme varsa token'ı yeniden üretin — "süresi dolmuş token" hatalarının çoğu bu beklemeden çıkar.

Güvenli ilgili kılavuzlar

• CaptchaAI ile ilk çözümünüz: hızlı başlangıç
• Yetkili ortamlarda CAPTCHA QA testleri
• Kendi form uç noktalarınızda CAPTCHA testleri
• Tarayıcıda başarısız, API'de başarılı: hata ayıklama
• reCAPTCHA v2'yi API ile çözme
• Cloudflare Turnstile'ı API ile çözme
• GeeTest v3'ü API ile çözme

Arama sayfanızın CAPTCHA akışını kendi ortamınızda CaptchaAI ile doğrulayın.