Lingkup aman: Panduan ini berlaku untuk lingkungan QA, staging, dan pra-produksi milik sendiri — atau yang otorisasinya sudah Anda pegang. Isinya pola diagnostik, pengujian, dan observabilitas untuk integrasi CAPTCHA Anda sendiri, bukan untuk situs pihak ketiga atau alur tanpa izin.
Sebelum widget CAPTCHA baru ikut naik ke production, tim QA perlu memastikan sitekey-nya benar dan tokennya benar-benar tervalidasi di backend — idealnya tanpa menyalakan browser penuh setiap kali. BeautifulSoup mem-parsing HTML staging Anda dalam hitungan milidetik lewat requests biasa; CaptchaAI menyelesaikan tantangan CAPTCHA di baliknya. Gabungan keduanya jadi pemeriksaan ringan yang cocok masuk ke pipeline CI, jauh lebih murah dibanding menjalankan Selenium atau Playwright hanya untuk cek widget.
Alur singkatnya mengikuti pola yang sama di semua tutorial CaptchaAI: kirim → simpan task ID → polling → pakai token. Urutan detailnya:
- Ambil HTML staging dan temukan sitekey CAPTCHA-nya.
- Kirim sitekey itu ke CaptchaAI, simpan
task_iddari respons. - Polling
res.phpsampai token siap dipakai. - Validasi token itu di backend QA Anda sebelum rilis.
Langkah 1: temukan sitekey CAPTCHA di HTML staging
Ambil HTML staging Anda dengan requests, lalu cari selektor yang stabil lewat BeautifulSoup — .g-recaptcha, [data-sitekey], atau class widget lain sesuai implementasi Anda. Pola soup.find(attrs={"data-sitekey": True}) cukup generik untuk menangkap reCAPTCHA maupun Turnstile sekaligus, jadi satu fungsi pencarian bisa dipakai ulang di banyak halaman staging tanpa branching per jenis CAPTCHA.
Langkah 2: kirim sitekey ke CaptchaAI dan tunggu token
Kirim sitekey beserta URL staging ke in.php, simpan task_id dari respons, lalu polling res.php sampai statusnya bukan lagi CAPCHA_NOT_READY. Karena CaptchaAI menagih per thread aktif — bukan per solve — paket BASIC ($15/bulan, 5 thread) biasanya sudah cukup untuk smoke test staging harian; kalau pipeline CI Anda menjalankan banyak job paralel, naik ke STANDARD ($30/bulan, 15 thread) baru terasa perlu.
Kapan mulai butuh lebih dari paket BASIC
Kalau matrix CI Anda menjalankan beberapa job staging sekaligus — misalnya tiap pull request memicu smoke test paralel — thread yang tersedia bisa habis dalam hitungan detik, dan CaptchaAI membalas ERROR_NO_SLOT_AVAILABLE sampai ada thread kosong lagi. Gejala itu rutin di log CI adalah sinyal untuk naik ke STANDARD, atau menjadwalkan ulang job agar tidak semuanya polling bersamaan.
Langkah 3: validasi token di backend QA Anda
Token dari CaptchaAI baru berarti kalau backend Anda menerimanya. Kirim ke endpoint QA internal untuk verifikasi lengkap — bukan hanya cek "token ada", tapi bandingkan juga action dan sitekey yang dipakai backend dengan yang dikirim saat solve, supaya bug konfigurasi ketahuan di staging, bukan setelah rilis.
Kapan BeautifulSoup saja tidak cukup
Kalau widget CAPTCHA di halaman staging Anda baru dirender lewat JavaScript setelah HTML awal termuat — umum terjadi di SPA atau halaman dengan client-side hydration — soup.find(attrs={"data-sitekey": True}) akan pulang kosong walau widgetnya sebenarnya ada. Untuk kasus itu, jalankan pemeriksaan sitekey sekali lewat Selenium atau Playwright untuk memastikan markup-nya, baru pakai alur BeautifulSoup ini untuk regresi harian setelah Anda tahu selector-nya stabil.
BeautifulSoup vs browser penuh: kapan pakai yang mana
Keduanya punya tempat berbeda dalam pipeline QA Anda, bukan soal mana yang lebih unggul.
| Skenario pengujian | BeautifulSoup + requests | Browser penuh (Selenium/Playwright) |
|---|---|---|
| Sitekey ada langsung di HTML awal | Cocok, jauh lebih cepat | Berlebihan |
| Widget baru muncul setelah JavaScript jalan | Tidak bisa mendeteksi | Wajib |
| Smoke test harian di pipeline CI | Cocok | Lebih lambat, biaya compute lebih tinggi |
| Alur login multi-langkah yang kompleks | Bisa, tapi butuh lebih banyak kode | Lebih mudah dikelola |
Kombinasi praktis: verifikasi markup sekali dengan browser penuh, lalu pakai BeautifulSoup untuk regresi harian.
Kesalahan yang sering muncul dan cara mengatasinya
| Gejala | Tindakan yang disarankan |
|---|---|
| Tes tidak menemukan widget | Periksa selector dan timing render pada staging Anda |
CaptchaAI mengembalikan ERROR_NO_SLOT_AVAILABLE |
Coba ulang dengan backoff di pipeline internal |
| Backend QA menolak token | Bandingkan action/sitekey dengan konfigurasi sebenarnya |
| Token diterima API tapi backend menolaknya sebagai expired | Cek apakah masa berlaku token di sisi backend lebih pendek dari total waktu polling |
Amati setiap eksekusi: log dan tracing
Catat log terstruktur untuk tiap eksekusi QA: durasi total token, kode respons HTTP, ID tugas, dan kedalaman antrean. Pisahkan saluran log per lingkungan (development, staging, pra-produksi), lalu korelasikan dengan distributed tracing (mis. OpenTelemetry) lewat correlation id — kemampuan memutar ulang satu skenario penuh dari satu id saja biasanya memangkas waktu diagnosis insiden setidaknya separuh. Kalau worker QA Anda berjalan di region Asia Tenggara seperti AWS ap-southeast-1 (Singapura) atau GCP asia-southeast2 (Jakarta), latensi ke CaptchaAI juga lebih rendah, jadi siklus polling di log akan terlihat sedikit lebih cepat dibanding worker yang jauh dari region tersebut.
Checklist sebelum masuk pipeline CI
- Cakupan pengujian dibatasi pada aplikasi sendiri atau sumber daya yang otorisasinya Anda pegang.
- Kunci 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 di pipeline CI.
- Kalau log QA menyimpan data uji yang menyerupai data pribadi, patuhi UU Pelindungan Data Pribadi (UU 27/2022) dan jangan simpan lebih lama dari kebutuhan pengujian.
Contoh kode: alur QA BeautifulSoup + CaptchaAI
Contoh Python berikut menunjukkan alur minimum untuk memvalidasi widget CAPTCHA pada lingkungan staging milik Anda sendiri lewat CaptchaAI.
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)
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 Anda untuk validasi.
Boleh menulis API key di source code?
Tidak boleh. Suntikkan lewat secret manager CI, environment variable, atau vault. Key yang sudah ter-commit harus dirotasi segera.
Strategi apa yang disarankan untuk error sementara?
Retry idempoten dengan exponential backoff (mis. 1s, 2s, 4s) dan batas atas. Error jaringan, respons 5xx, dan ERROR_NO_SLOT_AVAILABLE layak di-retry; error otorisasi yang persisten tidak boleh di-retry.
Apakah pendekatan ini berlaku untuk semua tipe CAPTCHA di staging saya?
Untuk yang didukung CaptchaAI secara umum — reCAPTCHA v2/v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3 — ya, alur submit-polling di atas berlaku sama. CaptchaFox, Friendly Captcha, dan Lemin masih berstatus beta. hCaptcha dan FunCaptcha belum didukung; kalau staging Anda memakai salah satunya, BeautifulSoup tetap berguna untuk memastikan widget-nya termuat dengan benar, tapi validasi solve end-to-end lewat CaptchaAI tidak berlaku untuk keduanya.
Berapa lama saya harus menunggu sebelum menganggap polling bermasalah?
Tergantung tipe CAPTCHA-nya — reCAPTCHA v2 biasanya selesai dalam waktu di bawah 60 detik dengan tingkat keberhasilan tinggi pada tipe yang didukung, sementara Turnstile jauh lebih cepat, umumnya di bawah 10 detik. Set batas waktu polling di atas angka itu dengan margin, lalu perlakukan CAPCHA_NOT_READY yang terus berulang lewat batas itu sebagai sinyal untuk investigasi, bukan langsung retry buta.
Panduan terkait yang aman
- Mulai cepat API CaptchaAI
- QA CAPTCHA yang terotorisasi
- Menguji endpoint CAPTCHA pada formulir sendiri
- Debug saat tes browser gagal padahal API berhasil
- Cara menyelesaikan reCAPTCHA v2 lewat API
- Cara menyelesaikan Cloudflare Turnstile lewat API
- Cara menyelesaikan GeeTest v3 lewat API
Validasi integrasi CAPTCHA Anda di lingkungan sendiri dengan CaptchaAI.
