Manajemen user-agent di QA milik sendiri dengan CaptchaAI

Lingkup aman: Materi ini hanya berlaku untuk lingkungan QA, staging, dan praproduksi yang Anda miliki atau pegang otorisasinya. Isinya soal diagnostik, pengujian, dan observabilitas untuk integrasi CAPTCHA Anda sendiri, bukan situs pihak ketiga maupun alur tanpa izin.

Jawaban singkatnya: perlakukan user-agent sebagai variabel pengujian yang dikunci, bukan nilai acak. Satu kasus QA dipetakan ke satu string user-agent nyata, dipakai konsisten sepanjang sesi, lalu dicatat di log supaya bug bisa diputar ulang persis. Tim yang melewatkan langkah ini berakhir dengan laporan "kadang gagal, kadang lolos" yang tidak bisa ditelusuri siapa pun.

Kenapa ini penting khusus di alur CAPTCHA? Karena widget seperti reCAPTCHA v2 dan Cloudflare Turnstile merender diri berbeda tergantung browser yang mereka kira sedang dipakai. Kalau string berubah antar-percobaan, Anda menguji tiga skenario berbeda sekaligus lalu membandingkan hasilnya seolah-olah satu.

Tiga cara string user-agent merusak hasil QA

1. Klien HTTP memakai string bawaannya. Library seperti requests mengirim identitas dirinya sendiri, sehingga staging Anda bisa menyajikan varian widget yang berbeda dari yang dilihat pengguna asli dan selector di test suite tidak pernah cocok.
2. String tidak sinkron dengan sisa header. User-agent mengaku Chrome versi terbaru, tetapi Accept-Language dan header Sec-Fetch-* tidak menyertai. Yang Anda reproduksi bukan browser nyata, melainkan kombinasi yang tidak pernah ada di lapangan.
3. String berganti di tengah sesi. Sesi jadi tidak valid menurut backend Anda sendiri, dan kegagalannya tercatat sebagai "masalah CAPTCHA" padahal akarnya di lapisan sesi.

Ketiganya bermuara pada gejala yang sama: hasil tes tidak deterministik, dan tes semacam itu lebih mahal daripada tidak ada tes sama sekali karena tim berhenti percaya.

Susun daftar user-agent yang terkendali

Prinsipnya pendek dan nyata: lima sampai delapan string saja, yaitu Chrome dan Firefox stabil terbaru di Windows, macOS, dan Linux, ditambah satu profil Android untuk skenario mobile-first di pasar Indonesia. Jangan merangkai string sendiri, salin dari browser sungguhan yang Anda pasang, lalu catat tanggal pengambilannya.

Simpan daftar itu sebagai satu file konfigurasi di repositori (misalnya qa/user_agents.yaml), bukan tersebar sebagai konstanta di beberapa berkas tes, dan tinjau tiap satu sampai dua bulan mengikuti siklus rilis browser. Yang sebaiknya tidak Anda lakukan: mengarang string yang tidak berkorespondensi dengan browser mana pun, karena kombinasi versi yang tidak pernah dirilis membuat hasilnya tidak bisa dibandingkan dengan perilaku pengguna sungguhan.

Petakan setiap kasus QA ke satu profil

Buat tabel pemetaan eksplisit, simpan bersama test suite:

Dengan pemetaan ini, kegagalan dilaporkan sebagai "qa_checkout_mobile gagal pada commit X", bukan "CAPTCHA-nya bermasalah", dan itulah yang memangkas waktu triase.

Kunci seluruh header dalam satu sesi

User-agent tidak berdiri sendiri. Dalam satu sesi pengujian, kunci sekaligus User-Agent, Accept, Accept-Language, Accept-Encoding, dan header Sec-Fetch-*. Bungkus semuanya dalam satu objek session, lalu pakai objek itu untuk seluruh permintaan dalam kasus tersebut.

Bila pengujian Anda meneruskan konteks browser ke CaptchaAI, kirim string yang sama persis dengan yang dipakai session. Detail integrasi per tipe ada di panduan menyelesaikan reCAPTCHA v2 dengan API, Cloudflare Turnstile, dan GeeTest v3. Untuk tipe yang belum didukung seperti hCaptcha dan FunCaptcha, rencanakan jalur pengujian terpisah sejak awal.

Contoh pemanggilan QA

Contoh Python berikut menunjukkan alur minimum untuk memvalidasi widget CAPTCHA di staging milik Anda lewat CaptchaAI: kirim task, simpan task ID, polling, lalu pakai token.

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)

Muat profil user-agent kasus QA dari konfigurasi Anda, lalu pakai nilai yang sama untuk session HTTP maupun parameter yang dikirim ke CaptchaAI. Kalau ini pemakaian pertama, panduan mulai cepat CaptchaAI menjelaskan cara mengambil API key.

Observabilitas: catat profilnya, bukan hanya hasilnya

Log terstruktur membedakan pipeline yang bisa didiagnosis dari yang tidak. Untuk setiap eksekusi, catat nama kasus QA, profil user-agent, durasi sampai token siap, kode respons HTTP, ID task, dan kedalaman antrean. Pisahkan saluran log per lingkungan dan korelasikan dengan distributed tracing, misalnya OpenTelemetry, lewat satu correlation id.

Konteks lokal yang sering terlewat: kalau runner CI berjalan di AWS ap-southeast-1 (Singapura) sementara staging ada di ap-southeast-3 (Jakarta), latensi antar-region ikut masuk ke angka waktu penyelesaian Anda. Catat region runner di log yang sama supaya perbandingan antar-hari tidak salah dibaca, dan tambahkan simulasi jaringan lambat pada kasus qa_checkout_mobile karena kondisi seluler adalah kondisi mayoritas pengguna di sini.

Checklist sebelum pipeline dianggap siap

• Cakupan pengujian dibatasi pada aplikasi sendiri atau sumber daya yang Anda pegang otorisasinya.
• Daftar user-agent tersimpan sebagai satu konfigurasi versi-terkontrol dengan tanggal peninjauan terakhir.
• Setiap kasus QA terikat pada satu profil, dan profil itu ikut tercatat di log.
• API key CaptchaAI disimpan di secret manager CI atau vault, tidak pernah di source code.
• Strategi coba ulang bersifat idempoten dengan batas atas untuk error sementara.
• Seluruh pengujian dapat direproduksi di pipeline CI tanpa langkah manual.

Diagnostik cepat saat tes gagal

Soal thread: CaptchaAI menagih per thread bersamaan, bukan per penyelesaian, dan setiap paket memberi penyelesaian tak terbatas sepanjang bulan. Untuk pipeline QA satu tim, BASIC ($15/bulan, 5 thread) atau STANDARD ($30/bulan, 15 thread) umumnya cukup; suite paralel besar baru perlu ADVANCE ($90/bulan, 50 thread). Menyelaraskan paralelisme runner CI dengan jumlah thread adalah cara paling sederhana menghindari ERROR_NO_SLOT_AVAILABLE berulang.

FAQ

Berapa banyak user-agent yang ideal untuk satu test suite?

Lima sampai delapan sudah memadai. Yang menentukan bukan jumlahnya, melainkan apakah tiap string terpetakan ke satu kasus QA yang jelas; daftar panjang tanpa pemetaan hanya menambah variabel tak terkendali.

Apakah profil user-agent memengaruhi waktu penyelesaian CAPTCHA?

Yang lebih terasa adalah varian widget yang dirender dan perilaku halaman staging Anda. Bandingkan waktu penyelesaian hanya antar-eksekusi dengan profil yang sama; menyandingkan profil desktop dan mobile secara langsung akan menyesatkan.

Bisakah satu kasus QA memakai profil berbeda tiap eksekusi?

Sebaiknya tidak. Kalau profilnya berubah, kegagalan tidak bisa diputar ulang dan dasar perbandingan Anda hilang. Bila perlu menguji beberapa browser, buat kasus QA terpisah.

Tipe CAPTCHA apa saja yang bisa saya pakai di pipeline QA ini?

Keluarga reCAPTCHA, Cloudflare Turnstile dan Challenge, GeeTest v3, serta CAPTCHA gambar dan grid, ditambah CaptchaFox (beta), Friendly Captcha (beta), dan Lemin (beta). hCaptcha dan FunCaptcha tidak didukung, sedangkan GeeTest v4 baru berstatus segera hadir.

Panduan terkait yang aman

• Mulai cepat CaptchaAI
• Menjalankan QA CAPTCHA dengan otorisasi penuh
• Menguji endpoint CAPTCHA pada formulir milik sendiri
• Saat tes browser gagal padahal API berjalan normal
• Menyelesaikan reCAPTCHA v2 dengan API
• Menyelesaikan Cloudflare Turnstile dengan API
• Menyelesaikan GeeTest v3 dengan API

Validasi integrasi CAPTCHA Anda di lingkungan sendiri dengan CaptchaAI.