Безопасный scope: Это руководство применимо только к собственным или явно авторизованным QA-, staging- и production-средам. Описаны сценарии диагностики, тестирования и наблюдаемости вашей собственной CAPTCHA-интеграции — не для сторонних сайтов и не для несанкционированных workflow.
User-Agent в QA — это не маскировка, а обычная ось тестовой матрицы. Строка заголовка сообщает вашему собственному приложению, какой клиент пришёл, и от неё зависят и вёрстка формы, и то, каким увидит виджет CAPTCHA живой пользователь. Если весь ночной прогон идёт от python-requests/2.x, вы проверяете один сценарий из десяти реальных, а мобильный WebView ломается уже у клиента.
Ниже — компактная матрица клиентов, порядок прогона формы с CAPTCHA в собственном staging и набор полей в логах, которого хватает, чтобы отличить регрессию вёрстки от регрессии интеграции.
Что именно проверяет User-Agent в тестовой матрице
Заголовок сам по себе ничего не «решает» — он лишь переключает ветки вашего кода и вашей вёрстки. В формах с CAPTCHA от него обычно зависят три вещи:
- какой шаблон страницы отдаёт backend (десктоп, адаптив, облегчённая версия для WebView);
- попадает ли запрос в вашу же политику фильтрации по UA — например, в правило, отбрасывающее клиенты без нормального заголовка;
- как событие раскладывается в аналитике: без явного класса клиента прогоны QA смешиваются с реальным трафиком, и медианы в дашборде перестают что-либо значить.
Отсюда практическое правило: User-Agent тест-клиента должен быть честным и распознаваемым в логах.
Матрица клиентов: минимальный набор
| Класс клиента | Что проверяем | Типичный признак сбоя |
|---|---|---|
| Десктопный Chrome | базовый сценарий формы и виджета | эталонный прогон, сбоев быть не должно |
| Десктопный Firefox | вёрстка и обработчики событий | смещённый или обрезанный виджет |
| Мобильный браузер | адаптивная раскладка, размеры полей | кнопка отправки уезжает за экран |
| WebView в мобильном приложении | загрузка внешних скриптов, cookie | виджет не появляется вовсе |
| QA-runner | сам прогон и его отделимость в логах | прогон неотличим от продового трафика |
Пяти строк достаточно для регулярного прогона. Расширять матрицу стоит только под реальные доли трафика из вашей аналитики.
Прогон формы с CAPTCHA в собственном staging
Порядок простой. QA-runner выставляет User-Agent из матрицы, открывает staging-страницу, забирает sitekey и pageurl, отправляет задачу в CaptchaAI и подставляет полученный токен в форму. Токен проверяется на вашем backend — клиенту здесь доверять нельзя ни в одном сценарии.
Тип CAPTCHA задаёт только параметры запроса, а не логику прогона: механика для reCAPTCHA v2 через API, Cloudflare Turnstile и GeeTest v3 разобрана отдельно, а общий цикл «отправить задачу → опрашивать результат → проверить токен» описан в быстром старте. Один и тот же прогон достаточно параметризовать типом CAPTCHA и классом клиента.
Важная деталь: класс клиента (ua_class) стоит проставлять в самом раннем месте пайплайна — в фикстуре теста, а не при разборе логов. Восстанавливать его потом регулярными выражениями по строке User-Agent — работа, которую придётся переделывать после каждого обновления браузеров.
Логи и наблюдаемость
Структурированные логи — единственный способ сравнивать поведение формы между релизами без ручного пересмотра записей прогона:
import json, time, logging
log = logging.getLogger('captcha-qa')
def record(event: str, **fields) -> None:
payload = {'ts': time.time(), 'event': event, **fields}
log.info(json.dumps(payload, ensure_ascii=False))
Минимальный набор полей для каждой попытки: slug, captcha_type, ua_class, task_id, wait_seconds, verify_status, env. Этого хватает, чтобы построить медиану, P90 и P99 по типу CAPTCHA, по среде и по классу клиента — и увидеть, что деградировал не сервис решения, а конкретная мобильная вёрстка.
Если в логи попадают данные тестовых пользователей, помечайте их как фиктивные и храните ровно столько, сколько нужно прогону. Для команд, у которых рядом лежат таблицы с реальными пользовательскими данными, это ещё и вопрос дисциплины по 152-ФЗ «О персональных данных» и сопоставимым требованиям других юрисдикций: собирайте только то, что вы вправе обрабатывать.
Сценарий: ночной прогон перед релизом мобильного клиента
Команда из пяти человек — часть в Алматы, часть удалённо — поддерживает форму регистрации с reCAPTCHA v2 на вебе и в WebView мобильного приложения. Раньше прогон шёл только с десктопным Chrome, и после каждого релиза приложения приходили обращения «капча не грузится». После добавления двух строк матрицы — мобильный браузер и WebView — ночной прогон стал ловить это до релиза, а не после.
По объёму это около 300 сценариев за ночь в последовательном режиме. Тарификация CaptchaAI считается по потокам, а не по числу решений, поэтому такому прогону хватает плана BASIC ($15/мес, 5 потоков); если классы клиентов и типы CAPTCHA запускаются параллельно, разумнее взять STANDARD ($30/мес, 15 потоков). Предсказуемая месячная стоимость в USD здесь удобнее оплаты за каждое решение: бюджет прогона не зависит от того, сколько раз за ночь упал и перезапустился CI.
Границы: чего в этом сценарии делать нельзя
- не выдавать автоматизированный клиент за обычный браузер на чужих ресурсах;
- не использовать матрицу User-Agent для проверки защиты сайтов, которые вам не принадлежат;
- не подменять клиентский профиль на сторонних сервисах — это уже не QA;
- не смешивать QA-прогоны с продовым трафиком в одной выборке аналитики.
Всё описанное выше работает только на своих или письменно авторизованных средах. Подробнее о границах — в материале QA-тестирование CAPTCHA в авторизованных средах.
Разбор типичных сбоев
| Симптом | Что проверить |
|---|---|
| 403 на эндпоинте с CAPTCHA | собственную политику фильтрации по UA: QA-runner должен быть в списке разрешённых |
| Виджет не загружается в WebView | загрузку внешних скриптов и cookie-политику WebView |
| QA-сессии видны в продовых отчётах | проставляется ли ua_class и фильтруется ли он в дашборде |
| Разные ответы на разных клиентах | серверные логи backend: какой шаблон отдан каждому классу |
| Токен проходит на клиенте, но backend его отклоняет | порядок проверки токена на сервере и срок его жизни |
Если браузерный прогон падает, а прямой вызов API проходит, проблема почти всегда в клиентском слое — такой случай разобран в статье браузерный тест падает, API проходит.
Чек-лист перед мержем
- Прогон обращается только к собственным или авторизованным endpoints.
- В матрице есть хотя бы один мобильный клиент и один WebView-сценарий.
- Тестовые учётные записи, события и платежи помечены как фиктивные.
- CAPTCHA-токен проверяется на backend, а не принимается на слово от клиента.
- В логах есть
task_id, тип CAPTCHA,ua_class, время ожидания и результат. - Скрипт возвращает корректный exit code, чтобы CI мог принять решение.
FAQ
Сколько User-Agent достаточно для QA-матрицы?
Обычно четырёх-пяти: десктопный Chrome, десктопный Firefox, мобильный браузер, WebView и отдельный QA-runner. Шестую строку добавляйте только тогда, когда в аналитике виден заметный сегмент, который матрица не покрывает.
Как отделить QA-прогоны от реальных пользователей в логах?
Проставляйте поле ua_class в фикстуре теста и фильтруйте по нему в дашборде. Разбирать строку User-Agent постфактум ненадёжно: она меняется с каждым обновлением браузера.
Что делать, если CAPTCHA не появляется в WebView?
Сначала проверьте загрузку внешних скриптов и cookie-политику WebView, затем — какой шаблон страницы backend отдал этому клиенту. Причина почти всегда на стороне вашего приложения, а не в самом виджете. Смежный сценарий разобран в статье тестирование CAPTCHA API на собственных формах.
Сколько потоков CaptchaAI нужно ночному прогону?
Поток — это одна задача CAPTCHA в работе одновременно. Для последовательного прогона хватает плана BASIC ($15/мес, 5 потоков); если вы запускаете классы клиентов параллельно, считайте потоки по числу одновременных сценариев, а не по общему количеству тестов за ночь.
Готовы прогнать матрицу клиентов на собственном staging? Подключите CaptchaAI.
