Phạm vi an toàn: Hướng dẫn này chỉ áp dụng cho môi trường QA, staging hoặc pre-production thuộc sở hữu hoặc được uỷ quyền của bạn. Nội dung bao gồm các mẫu chẩn đoán, kiểm thử và quan sát cho tích hợp CAPTCHA của chính bạn — không áp dụng cho bên thứ ba hoặc luồng không được phép.
Một test CAPTCHA chạy xanh trên máy dev rồi đỏ trên CI thường không phải lỗi của solver: trình duyệt test và request gửi tới API đang khai báo hai user-agent khác nhau. Cách xử lý gồm ba việc — chốt danh sách user-agent hợp lệ, gán cố định mỗi qa_case một string, rồi ghi string đó vào log.
Vì sao user-agent quyết định khả năng tái lập
Widget CAPTCHA render khác nhau tuỳ trình duyệt và phiên bản: kích thước khung, thời điểm script load, đôi khi cả selector. Bốc ngẫu nhiên một string mỗi lần chạy là mất mốc so sánh.
Với các đội QA outsourcing ở TP.HCM và Hà Nội, nơi một đội test phục vụ nhiều khách hàng, điều này càng quan trọng: bug report "form đăng ký fail trên Safari" phải dựng lại được trên staging chỉ bằng một qa_case id.
Chốt danh sách user-agent có kiểm soát
Năm đến tám string là đủ cho hầu hết bộ test:
- Chỉ lấy từ trình duyệt thật đang được hỗ trợ, không tự chế biến thể.
- Ghi ngày cập nhật; rà lại mỗi 1–2 tháng.
- Lưu trong repo để thay đổi đi qua code review.
Gán user-agent cố định theo qa_case
Mỗi case ánh xạ tới đúng một user-agent, khai báo trong fixture chứ không sinh lúc runtime. Cùng string đó đi kèm request tới CaptchaAI khi lấy token. Lệch ở bước này là nguyên nhân hàng đầu khiến token hợp lệ nhưng backend QA vẫn từ chối.
Ghi log và khả năng quan sát
Ghi log có cấu trúc mỗi lần chạy: user-agent, thời gian lấy token, mã trạng thái HTTP, ID task, độ sâu hàng đợi. Tách development, staging và pre-production thành kênh riêng, nối các bước bằng một correlation id (ví dụ với OpenTelemetry). Phát lại kịch bản từ một id duy nhất vừa rút ngắn thời gian chẩn đoán, vừa để lại dấu vết đối soát cho yêu cầu tối thiểu hoá dữ liệu theo Nghị định 13/2023/NĐ-CP.
Ví dụ gọi QA
Luồng tối thiểu để test một CAPTCHA widget trên staging qua CaptchaAI:
import os
import requests
API_KEY = os.environ['CAPTCHAAI_KEY']
QA_PAGE_URL = os.environ['QA_PAGE_URL'] # ví dụ 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()
Khắc phục sự cố
| Vấn đề | Nguyên nhân thường gặp | Cách xử lý |
|---|---|---|
| Test không tìm thấy widget | Thay đổi selector hoặc thời điểm load | Kiểm tra selector và wait_for_selector trên staging |
CaptchaAI trả ERROR_NO_SLOT_AVAILABLE |
Hàng đợi đầy tạm thời | Thử lại với backoff trong pipeline nội bộ |
| Backend QA từ chối token | Sai action/sitekey/secret | Đối chiếu cấu hình backend với staging |
| Kết quả khác nhau giữa dev và CI | User-agent không cố định theo case | Đưa string vào fixture và ghi vào log |
Checklist trước khi merge
- Phạm vi test giới hạn trong tài nguyên được uỷ quyền.
- Mỗi
qa_casecó đúng một user-agent, khai báo trong fixture. - API key CaptchaAI nằm trong CI secret hoặc vault, không trong mã nguồn.
- Mỗi lần chạy ghi lại user-agent, thời gian gọi và mã trạng thái.
- Có chính sách thử lại idempotent kèm giới hạn cho lỗi tạm thời.
Câu hỏi thường gặp
Bao lâu nên rà lại danh sách user-agent một lần?
Mỗi 1–2 tháng, hoặc khi trình duyệt hỗ trợ ra bản chính.
Có cần gửi cùng user-agent tới CaptchaAI như trên trình duyệt test không?
Có. Một string duy nhất xuyên suốt một qa_case giúp kết quả tái lập.
Chạy bộ test QA này tốn bao nhiêu?
Giá theo thread, không theo lượt giải. BASIC ($15/tháng, 5 thread) đủ cho một bộ regression hằng đêm; đội chạy nhiều nhánh song song thường lên STANDARD ($30/tháng, 15 thread).
Bộ test của tôi dùng hCaptcha thì sao?
Không dùng được: CaptchaAI hiện không hỗ trợ hCaptcha lẫn FunCaptcha (Arkose Labs). Các loại chạy được: reCAPTCHA v2/v3, Cloudflare Turnstile, Cloudflare Challenge, GeeTest v3, ảnh/OCR; CaptchaFox, Friendly Captcha và Lemin mới ở giai đoạn beta.
Hướng dẫn liên quan an toàn
- Bắt đầu với CaptchaAI
- Kiểm thử QA được uỷ quyền
- Test endpoint CAPTCHA trên form của bạn
- Test trình duyệt fail mà API vẫn chạy
- Giải reCAPTCHA v2 qua API
- Giải Cloudflare Turnstile qua API
- Giải GeeTest v3 qua API
Xác thực tích hợp CAPTCHA của bạn trong môi trường nội bộ với CaptchaAI.
