Menangani CAPTCHA dalam pipeline QA milik sendiri

Lingkup aman: Panduan ini berlaku hanya untuk lingkungan QA, staging, dan praproduksi milik sendiri atau yang Anda miliki otorisasinya. Materi membahas pola diagnostik, pengujian, dan observabilitas untuk integrasi CAPTCHA Anda sendiri — bukan untuk situs pihak ketiga atau alur tanpa otorisasi.

Suite pengujian otomatis Anda tiba-tiba merah, padahal tidak ada bug baru yang masuk. Penyebabnya sering sepele: halaman staging memunculkan CAPTCHA, dan skrip tes berhenti tepat di gerbang itu. Mematikan CAPTCHA di staging bukan jawabannya — justru menghilangkan hal yang ingin Anda uji. Pendekatan yang benar adalah menyelesaikannya secara terprogram: deteksi widget, kirim ke CaptchaAI, ambil token, lalu validasi token tersebut ke backend QA Anda. Panduan ini merangkum pola yang membuat CAPTCHA berhenti menjadi sumber kegagalan tes yang rapuh di lingkungan milik sendiri.

Kapan CAPTCHA muncul di pipeline pengujian Anda

Widget CAPTCHA di staging biasanya identik dengan yang ada di produksi karena tim ingin skenario uji yang realistis. Reproduksi konfigurasi yang sama justru membuatnya menjadi pengganggu ketika CI berjalan berulang kali dari IP yang sama. Beberapa pemicu yang umum di lingkungan pengujian:

• Runner CI menembak endpoint yang sama ribuan kali dari satu IP pusat data.
• Sesi tes tidak membawa cookie atau header yang wajar seperti Accept-Language.
• Skenario headless memicu reCAPTCHA v3 skor rendah pada form login staging.
• Reset database antar-run menghapus state yang sebelumnya menandai sesi sebagai tepercaya.

Alih-alih menambal setiap gejala satu per satu, perlakukan penyelesaian CAPTCHA sebagai satu langkah terkelola dalam pipeline. CaptchaAI mendukung reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest v3, serta image/OCR — cukup untuk sebagian besar widget yang Anda replikasi di staging. hCaptcha dan FunCaptcha belum didukung, jadi rencanakan jalur uji terpisah jika staging Anda memakainya.

Pola alur: dari widget staging ke token tervalidasi

Pertahankan empat langkah yang sama di setiap kasus uji: deteksi widget → kirim task ke CaptchaAI → polling hasil → validasi token ke backend QA. Deteksi widget dilakukan dari selector di halaman staging (div.g-recaptcha, div.cf-turnstile, dan sejenisnya). Setelah task terkirim, Anda menerima task ID; simpan ID itu sebelum masuk ke loop polling. Ketika token selesai, jangan langsung menganggap tes lulus — kirim token ke endpoint validasi backend QA Anda dan pastikan backend menerimanya dengan action/sitekey yang benar. Pemisahan tanggung jawab ini penting: kegagalan penyelesaian CAPTCHA dan kegagalan logika aplikasi harus terlihat sebagai dua sinyal berbeda di laporan tes.

Retry terkontrol tanpa membanjiri pipeline

Error sementara wajar terjadi, terutama saat CI menjalankan banyak job paralel. Gunakan exponential backoff — jeda yang meningkat eksponensial, misalnya 1 detik, 2 detik, lalu 4 detik — dengan batas atas percobaan per kasus_qa. Buat strategi retry idempoten: error jaringan, respons 5xx, dan ERROR_NO_SLOT_AVAILABLE layak dicoba ulang, sedangkan error otorisasi yang persisten (API key salah) tidak boleh di-retry karena hanya membuang waktu build. Catat setiap percobaan ulang beserta alasannya agar lonjakan retry di satu run menjadi sinyal dini, bukan kejutan saat pipeline mendadak melambat.

Model penagihan CaptchaAI berbasis thread, bukan per solve, sehingga retry di CI tidak menambah biaya per panggilan. Paket BASIC ($15/bulan, 5 thread) umumnya cukup untuk satu pipeline, dan Anda bisa naik ke ADVANCE ($90/bulan, 50 thread) saat banyak job paralel menyelesaikan CAPTCHA sekaligus. Harga terkini selalu di captchaai.com/pricing.

Trace: kaitkan token ke kasus uji

Tautkan setiap token ke kasus_qa yang mengonsumsinya, lengkap dengan waktu submit dan waktu validasi. Ketika sebuah tes gagal, Anda ingin langsung tahu apakah tokennya lambat datang, ditolak backend, atau tidak pernah diminta. Correlation id yang sama sebaiknya mengalir dari runner CI, melewati panggilan CaptchaAI, hingga log backend QA. Tim di Indonesia yang men-deploy staging ke region terdekat seperti AWS ap-southeast-3 (Jakarta) atau ap-southeast-1 (Singapura) dapat memakai selisih latensi antar-region sebagai baseline yang stabil untuk membedakan solve yang benar-benar lambat dari sekadar jarak jaringan.

Contoh: memvalidasi widget di staging

Contoh Python berikut menunjukkan alur minimum untuk memvalidasi widget CAPTCHA pada lingkungan staging milik Anda sendiri lewat CaptchaAI. Konfigurasi dibaca dari environment variable agar tidak ada key yang tertulis di source code.

import os
import time
import requests

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


def submit_qa_recaptcha() -> str:
    payload = {
        'key': API_KEY,
        'method': 'userrecaptcha',
        'googlekey': QA_SITE_KEY,
        'pageurl': QA_PAGE_URL,
        'json': 1,
    }
    response = requests.post(
        'https://ocr.captchaai.com/in.php',
        data=payload,
        timeout=30,
    )
    response.raise_for_status()
    return response.json()['request']


def fetch_qa_result(task_id: str) -> dict:
    params = {
        'key': API_KEY,
        'action': 'get',
        'id': task_id,
        'json': 1,
    }
    while True:
        response = requests.get(
            'https://ocr.captchaai.com/res.php',
            params=params,
            timeout=30,
        )
        response.raise_for_status()
        data = response.json()
        if data.get('request') != 'CAPCHA_NOT_READY':
            return data
        time.sleep(5)

Observabilitas dan korelasi log

Catat log terstruktur untuk setiap eksekusi QA. Metrik yang paling berguna: durasi total sampai token siap, kode respons HTTP, task ID, dan kedalaman antrean saat submit. Pisahkan saluran log per lingkungan (development, staging, pra-produksi) dan korelasikan dengan distributed tracing (mis. OpenTelemetry) lewat correlation id. Kemampuan memutar ulang satu skenario penuh hanya dari satu id biasanya memangkas waktu diagnosis insiden secara signifikan, karena Anda tidak perlu menebak apakah masalahnya di jaringan, di solver, atau di backend.

Pemecahan masalah umum

Checklist sebelum merge

• Cakupan pengujian dibatasi pada aplikasi sendiri atau sumber daya yang Anda miliki otorisasinya. Sesuai UU Pelindungan Data Pribadi (UU 27/2022), uji hanya data yang berhak Anda proses.
• API key CaptchaAI disimpan di secret manager CI atau vault, bukan di source code.
• Setiap eksekusi mencatat latensi dan kode status respons.
• Strategi retry idempoten dengan batas atas untuk error sementara.
• Pengujian dapat direproduksi ulang di pipeline CI dari satu correlation id.

FAQ

Apakah alur ini menyentuh trafik produksi?

Tidak. Semua contoh mengasumsikan domain QA milik sendiri seperti staging.example.com. Replikasi konfigurasi CAPTCHA produksi di salinan staging untuk mendapatkan validasi yang realistis tanpa menyentuh sistem live.

Jenis CAPTCHA apa yang bisa divalidasi CaptchaAI di staging?

reCAPTCHA v2 dan v3, Cloudflare Turnstile, GeeTest v3, serta image/OCR. hCaptcha dan FunCaptcha belum didukung, dan GeeTest v4 masih berstatus segera hadir — siapkan jalur uji terpisah jika staging Anda memakainya.

Berapa biayanya untuk pipeline CI yang sering berjalan?

Penagihan berbasis thread, bukan per solve, jadi jumlah panggilan tidak menaikkan biaya. Satu paket seperti BASIC ($15/bulan, 5 thread) menutup banyak run harian; naik tier hanya saat butuh lebih banyak solve paralel.

Bagaimana menyimpan API key dengan aman di CI?

Suntikkan lewat secret manager CI, environment variable, atau vault — jangan pernah di-commit. Key yang sudah terlanjur masuk source code harus dirotasi segera.

Panduan terkait yang aman

• Panduan mulai cepat CaptchaAI
• Pola QA CAPTCHA yang terotorisasi
• Menguji endpoint CAPTCHA pada formulir milik sendiri
• Debug ketika tes browser gagal padahal API jalan
• Menyelesaikan reCAPTCHA v2 lewat API
• Menyelesaikan Cloudflare Turnstile lewat API
• Menyelesaikan GeeTest v3 lewat API

Validasi integrasi CAPTCHA Anda di lingkungan sendiri dengan CaptchaAI.