Puppeteer + CaptchaAI untuk pengujian QA di browser milik sendiri

Lingkup aman: Panduan ini khusus untuk lingkungan QA, staging, dan pra-produksi milik sendiri atau yang otorisasinya sudah Anda pegang. Isinya adalah pola diagnostik, pengujian, dan observabilitas untuk integrasi CAPTCHA Anda sendiri — bukan panduan untuk situs pihak ketiga atau alur tanpa otorisasi.

Smoke test yang cuma memastikan halaman staging Anda ter-render sering melewatkan bagian paling rawan gagal: alur CAPTCHA di form login atau checkout. Panduan ini menunjukkan cara memvalidasi reCAPTCHA, Turnstile, dan GeeTest end-to-end dengan Puppeteer dan CaptchaAI, langsung di lingkungan staging milik Anda sendiri — bukan untuk situs pihak ketiga, dan bukan otomatisasi tanpa otorisasi.

Checklist kesiapan

• Cakupan pengujian hanya aplikasi atau sumber daya yang Anda miliki otorisasinya.
• API key CaptchaAI disimpan di secret manager CI atau vault, bukan langsung di source code.
• Setiap eksekusi mencatat latensi dan kode status respons secara konsisten.
• Retry idempoten dengan batas atas untuk error sementara.
• Pipeline CI dapat mereproduksi hasil pengujian tanpa intervensi manual.

Menyiapkan Puppeteer untuk smoke test CAPTCHA

npm install puppeteer

const puppeteer = require('puppeteer');

async function launchQa() {
  return puppeteer.launch({ headless: 'new', args: ['--no-sandbox'] });
}

Mendeteksi sitekey reCAPTCHA di halaman staging sendiri

const page = await (await launchQa()).newPage();
await page.goto('https://staging.example.com/qa-form');
const sitekey = await page.$eval('.g-recaptcha', el => el.dataset.sitekey);

Mengirim task ke API CaptchaAI dan menunggu token

const fetch = require('node-fetch');
const KEY = process.env.CAPTCHAAI_API_KEY;

async function solve(sitekey, pageurl) {
  const submit = await fetch(`https://ocr.captchaai.com/in.php?key=${KEY}&method=userrecaptcha&googlekey=${sitekey}&pageurl=${pageurl}&json=1`).then(r => r.json());
  while (true) {
    await new Promise(r => setTimeout(r, 5000));
    const res = await fetch(`https://ocr.captchaai.com/res.php?key=${KEY}&action=get&id=${submit.request}&json=1`).then(r => r.json());
    if (res.status === 1) return res.request;
  }
}

Memvalidasi token di endpoint QA internal

Submit token ke endpoint backend QA Anda (misal https://staging.example.com/checkout-test) dengan body yang sesuai dan periksa status respons.

Konteks lokal: menguji dari region terdekat

Tim QA dan automation di Indonesia sering menjalankan runner CI dari region seperti AWS ap-southeast-1 (Singapura) atau GCP asia-southeast2 (Jakarta) supaya latensi ke staging tetap rendah. Kondisi jaringan mobile-first pada banyak tim membuat timeout yang longgar dan strategi retry yang jelas lebih penting dibanding di lingkungan lab dengan koneksi stabil — jangan langsung anggap CAPTCHA yang belum selesai dalam 5 detik sebagai bug, ulangi polling dengan jeda wajar sebelum menandainya gagal. Karena data uji berupa pengguna dan formulir fiktif, alur ini juga selaras dengan semangat UU Pelindungan Data Pribadi (UU 27/2022): jangan pernah memakai data pribadi nyata di environment staging.

Logging dan observabilitas

Catat log terstruktur untuk setiap eksekusi, per kasus_qa: waktu solve, kode status respons backend, ID tugas CaptchaAI, kedalaman antrean, dan jumlah percobaan retry. Pisahkan saluran log per lingkungan (development, staging, pra-produksi) supaya angka dari satu environment tidak tercampur dengan yang lain. Korelasikan dengan distributed tracing (mis. OpenTelemetry) lewat correlation id — kemampuan memutar ulang satu skenario penuh dari satu id biasanya memangkas waktu diagnosis insiden setidaknya separuh. Agregasi P50/P95 dari run pipeline Anda; anggap nilainya indikatif untuk staging Anda sendiri, bukan SLA produksi.

Contoh lengkap: validasi reCAPTCHA dengan Python

Contoh Python berikut menunjukkan alur end-to-end untuk mengirim task reCAPTCHA ke CaptchaAI dan menunggu token dari halaman staging Anda sendiri — pola yang sama berlaku untuk Turnstile, tinggal mengganti method dan parameter sitekey-nya.

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)

Kapan pakai Puppeteer, kapan cukup uji API langsung

Puppeteer masuk akal ketika Anda perlu memvalidasi seluruh rantai render: widget CAPTCHA benar-benar muncul di DOM, token benar-benar ter-inject ke field yang tepat, dan submit form benar-benar memicu callback yang diharapkan. Smoke test browser jadi satu-satunya cara mendeteksi regresi di sisi front-end sebelum rilis. Sebaliknya, jika Anda hanya perlu memastikan endpoint CaptchaAI merespons dengan benar untuk sitekey tertentu, memanggil in.php/res.php langsung lewat requests atau curl jauh lebih cepat dan lebih stabil di pipeline CI, tanpa overhead menjalankan browser headless. Kombinasi keduanya — uji API cepat di setiap commit, smoke test Puppeteer penuh sebelum rilis — biasanya memberi cakupan paling seimbang untuk tim QA dengan sumber daya CI terbatas.

Kendala umum dan solusinya

FAQ

Apakah alur pengujian ini menyentuh trafik produksi?

Tidak. Setiap contoh di panduan ini mengasumsikan domain QA milik sendiri seperti staging.example.com. Replikasikan konfigurasi CAPTCHA produksi Anda ke salinan staging untuk validasi, jangan pernah menjalankan skrip ini terhadap domain produksi.

Amankah menyimpan API key CaptchaAI di source code?

Tidak. Suntikkan API key lewat secret manager CI, environment variable, atau vault. Key yang sudah pernah ter-commit ke repository harus segera dirotasi, bukan sekadar dihapus dari commit terbaru.

Bagaimana strategi retry yang disarankan untuk error sementara?

Gunakan retry idempoten dengan exponential backoff (mis. 1 detik, 2 detik, 4 detik) dan batas atas percobaan. Error jaringan, respons 5xx, dan ERROR_NO_SLOT_AVAILABLE layak di-retry; error otorisasi yang persisten sebaiknya langsung digagalkan, bukan diulang terus-menerus.

Kenapa menjalankan Puppeteer headless di pipeline CI, bukan mode berjendela?

Mode headless lebih ringan dan lebih mudah direproduksi di runner CI tanpa display, sehingga cocok untuk smoke test terjadwal. Gunakan mode berjendela (headed) hanya saat Anda men-debug selector atau timing widget CAPTCHA secara lokal.

Panduan terkait yang aman

• Mulai cepat CaptchaAI
• QA CAPTCHA terotorisasi
• Pengujian endpoint CAPTCHA pada formulir sendiri
• Debug saat tes browser gagal padahal API berfungsi
• Menyelesaikan reCAPTCHA v2 dengan API
• Menyelesaikan Cloudflare Turnstile dengan API
• Menyelesaikan GeeTest v3 dengan API

Ambil API key CaptchaAI dan mulai validasi alur CAPTCHA Anda di staging sendiri hari ini.