Обход reCAPTCHA v2: как пользоваться сервисом решения капчи
В автотестах обход reCAPTCHA v2 сводится к двум шагам: получить действительный токен и передать его форме. Сервис решает капчу и возвращает токен. Тест передаёт его форме так же, как это делает виджет. Прежде чем принять запрос, бэкенд проверяет токен через Google. Разберём оба варианта виджета, покажем, где найти нужные параметры и как использовать CapMonster Cloud в тестах на Python и JavaScript.
Главное
- На практике нужно получить действительный токен и передать его форме. Бэкенд всё равно проверяет токен через Google.
- В обычном виджете проверка начинается, когда пользователь ставит галочку. В невидимом виджете проверку запускает кнопка или код приложения. Когда приходит токен, функция обратного вызова продолжает отправку формы.
- Стандартный токен reCAPTCHA v2 действует две минуты. Проверить его можно только один раз. Токен CapMonster Cloud действует 60 секунд с момента решения капчи, поэтому используйте его сразу.
- Для задачи RecaptchaV2Task достаточно указать тип задачи, URL страницы и ключ сайта. Прокси, User-Agent и cookies необязательны. Для некоторых интеграций CapMonster Cloud описывает дополнительные требования к ним.
- Действительный токен сам по себе не гарантирует, что приложение примет форму. Записывайте в журнал отдельно результат работы сервиса, результат проверки Google и итог отправки формы.
Термины
- Ключ сайта (websiteKey). Публичный ключ, который идентифицирует интеграцию reCAPTCHA и определяет, какой виджет загрузит страница. В API CapMonster Cloud это поле называется websiteKey.
- g-recaptcha-response. Поле формы с токеном, который генерирует reCAPTCHA. Виджет сохраняет токен в скрытом элементе textarea с этим именем, а бэкенд проверяет его через Google.
- data-s. Дополнительное одноразовое значение, которое встречается в HTML виджета в некоторых нестандартных интеграциях reCAPTCHA v2. Ключ сайта и токен ответа передаются отдельно.
- isInvisible. Необязательное логическое поле в API CapMonster Cloud. Значение true указывает, что задача относится к невидимому виджету reCAPTCHA v2.
- Задача. Запрос, который CapMonster Cloud обрабатывает асинхронно. Каждая принятая задача получает идентификатор. По нему можно проверить статус и получить результат.
- Срок действия токена. Период, в течение которого токен можно проверить. Одноразовый токен нельзя проверить повторно, даже если этот срок ещё не истёк.
reCAPTCHA v2 с флажком и невидимая reCAPTCHA v2
Два типа виджетов reCAPTCHA v2 различаются прежде всего тем, как начинается проверка. В обычном виджете пользователь нажимает «Я не робот». Google может сразу пропустить пользователя или предложить дополнительное задание. После успешной проверки виджет записывает токен в скрытое поле, и он уходит на сервер вместе с формой.
У невидимого виджета нет флажка. Проверка начинается, когда пользователь нажимает кнопку, например Submit, или когда приложение запускает её из JavaScript. Google при этом может показать дополнительное задание.
Виджеты можно различить по конфигурации. Невидимый режим задаётся атрибутом data-size="invisible" в HTML или параметром size: "invisible" в JavaScript. В этом режиме используется функция обратного вызова. После успешной проверки Google передаёт токен функции, указанной в data-callback или в параметре callback при вызове grecaptcha.render(). Дальнейшие действия определяет код приложения. Обычно эта функция продолжает отправку формы. У виджета с флажком тоже может быть callback, но стандартная форма может отправиться и без него.
Бэкенд проверяет оба варианта одинаково: прежде чем принять защищённый запрос, отправляет токен в Google. Если подключаете виджет к своей форме, посмотрите, как интегрировать reCAPTCHA v2 на сайте. У Enterprise своя настройка ключей. Её мы разбираем в отдельном руководстве по reCAPTCHA Enterprise.
Как работает обход reCAPTCHA v2
Сервис выполняет задание на этапе проверки. Остальные шаги остаются прежними.
- Виджет. Виджет reCAPTCHA запускает проверку в браузере. Google может предложить пользователю выполнить задание.
- Токен ответа. После успешной проверки виджет возвращает токен, который страница отправляет вместе с формой. Когда капчу решает сервис CapMonster Cloud для reCAPTCHA v2, токен приходит в результате задачи.
- Серверная проверка. Бэкенд отправляет токен и секретный ключ в Google. Приложение решает, принять ли форму, по ответу Google и собственным правилам.
Срок действия токена
По правилам серверной проверки Google стандартный токен v2 действует две минуты, и проверить его можно только один раз. CapMonster Cloud указывает для возвращаемого токена срок в 60 секунд с момента решения капчи. Используйте токен сразу после получения.
Что записывать в журнал при тестировании
Отдельно фиксируйте результат работы сервиса решения reCAPTCHA v2, ответ Google и итог отправки формы. Так видно, на каком этапе запрос не прошёл. См. также рабочие способы решения reCAPTCHA v2 в 2026 году.
Как найти параметры
Понадобятся публичный ключ сайта, режим виджета и значение data-s, если оно используется в интеграции. Их можно посмотреть вручную в DevTools.
Проверка вручную
Откройте страницу с виджетом, нажмите на капчу правой кнопкой мыши и выберите Inspect.
На вкладке Elements найдите контейнер виджета. Обычно это div с классом g-recaptcha. В атрибуте data-sitekey указан публичный ключ, который передаётся как websiteKey. Атрибут data-size="invisible" указывает на невидимый режим. В некоторых нестандартных интеграциях есть и атрибут data-s. Его значение передаётся в recaptchaDataSValue. Для каждой задачи нужно новое значение, поскольку оно одноразовое. Если приложение создаёт виджет из JavaScript, ищите параметры sitekey и size в вызове grecaptcha.render().
Откройте вкладку Network, перезагрузите страницу и найдите запрос к endpoint reCAPTCHA anchor. В параметре k указан ключ сайта. Если известно, что страница использует v2, значение size=invisible в этом же запросе подтверждает невидимый режим. Такой способ помогает, когда ключа не видно в HTML страницы. У reCAPTCHA v3 тоже бывает невидимый виджет, поэтому одного этого параметра недостаточно, чтобы определить версию.
Автоматическая проверка
Пример на Playwright ниже рассчитан на конкретную разметку: iframe anchor от Google и data-атрибуты на контейнере виджета. Скрипт считывает ключ сайта и режим виджета, а также выводит необязательное значение data-s, если оно есть. Если приложение отрисовывает виджет иначе, адаптируйте селекторы под его разметку.
import { chromium } from "playwright";
(async () => {
const browser = await chromium.launch({ headless: false });
const page = await browser.newPage();
await page.goto("https://example.com");
await page.waitForSelector('iframe[src^="https://www.google.com/recaptcha/api2/anchor?"]');
const captchaData = await page.evaluate(() => {
const iframeEl = document.querySelector('iframe[src^="https://www.google.com/recaptcha/api2/anchor?"]');
const captchaUrl = iframeEl?.getAttribute("src");
if (captchaUrl) {
const urlParams = new URLSearchParams(captchaUrl.split("?")[1]);
const sitekey = urlParams.get("k");
const size = urlParams.get("size");
const isInvisible = size === "invisible";
const sitekeyEl = document.querySelector("[data-sitekey]");
const datasEl = document.querySelector("[data-s]");
const datas = datasEl?.getAttribute("data-s");
return {
sitekey: sitekey || sitekeyEl?.getAttribute("data-sitekey"),
datas,
isInvisible,
};
}
return null;
});
console.log(captchaData);
await browser.close();
})();
Как решить reCAPTCHA v2 через API CapMonster Cloud
Для стандартной reCAPTCHA v2 в CapMonster Cloud используется тип задачи RecaptchaV2Task. Задачу создают через createTask, а результат запрашивают через getTaskResult. Сервис обрабатывает задачу асинхронно. Запрос формы по-прежнему обрабатывает само приложение по своим правилам проверки и бизнес-логике. Параметры в таблице приведены по документации RecaptchaV2Task.
| Параметр | Обязательность | Описание |
|---|---|---|
| type | Обязательный | Тип задачи. Значение — RecaptchaV2Task. |
| websiteURL | Обязательный | URL страницы с reCAPTCHA v2. |
| websiteKey | Обязательный | Публичный ключ сайта для виджета reCAPTCHA v2. |
| recaptchaDataSValue | Необязательный | Строка. Одноразовое значение data-s, которое используется в некоторых нестандартных интеграциях reCAPTCHA v2. Для каждой задачи получайте новое значение. |
| userAgent | Необязательный | Строка. User-Agent браузера для эмуляции. Используйте строку User-Agent современного браузера. CapMonster Cloud публикует актуальное поддерживаемое значение (см. примечания после таблицы). |
| cookies | Необязательный | Строка. Дополнительные cookies для взаимодействия с целевой страницей или Google. Формат: name1=value1; name2=value2. |
| isInvisible | Необязательный | Логическое значение. true для невидимой reCAPTCHA v2. |
| proxyType | Необязательный | Строка. Тип прокси: http, https (только если http не работает), socks4 или socks5. |
| proxyAddress | Необязательный | Строка. IPv4- или IPv6-адрес прокси. Прозрачные прокси и прокси на локальных машинах не поддерживаются. |
| proxyPort | Необязательный | Целое число. Порт прокси. |
| proxyLogin | Необязательный | Строка. Логин для доступа к прокси. |
| proxyPassword | Необязательный | Строка. Пароль для доступа к прокси. |
Если CapMonster Cloud принимает задачу, он возвращает её идентификатор taskId. При успехе токен reCAPTCHA приходит в solution.gRecaptchaResponse. Для некоторых сайтов в solution также приходит userAgent. В этом случае отправляйте форму с указанным User-Agent, даже если браузер или скрипт использует другой.
Настройка. По умолчанию CapMonster Cloud использует собственные прокси. Поля прокси нужны, если вы хотите использовать свой. Если ваш прокси авторизует подключения по IP-адресу, добавьте адрес CapMonster Cloud в список разрешённых. На момент написания в документации указан 65.21.190.34. Поддерживаемый User-Agent может меняться. Перед запуском тестов проверьте актуальный User-Agent.
reCAPTCHA v2 на Python
Если тесту нужен реальный токен вместо заранее заданного ответа верификатора, можно вызвать API CapMonster Cloud напрямую. В этом примере на Python браузер не используется. Скрипт вызывает createTask, затем опрашивает getTaskResult, пока задача не будет готова. Понадобятся библиотека requests и два значения из вашей формы: URL страницы и ключ сайта.
import time
import requests
API_KEY = "YOUR_API_KEY"
API = "https://api.capmonster.cloud"
def solve_recaptcha_v2(website_url, website_key, timeout=120):
task = requests.post(f"{API}/createTask", json={
"clientKey": API_KEY,
"task": {
"type": "RecaptchaV2Task",
"websiteURL": website_url,
"websiteKey": website_key,
},
}, timeout=30).json()
if task["errorId"]:
raise RuntimeError(task.get("errorCode"))
deadline = time.monotonic() + timeout
while time.monotonic() < deadline:
time.sleep(3)
result = requests.post(f"{API}/getTaskResult", json={
"clientKey": API_KEY,
"taskId": task["taskId"],
}, timeout=30).json()
if result["errorId"]:
raise RuntimeError(result.get("errorCode"))
if result["status"] == "ready":
return result["solution"]
raise TimeoutError("No result from CapMonster Cloud before the deadline")
solution = solve_recaptcha_v2("https://staging.example.com/signup", "YOUR_SITE_KEY")
token = solution["gRecaptchaResponse"]
Функция возвращает весь объект solution вместе с токеном. Для некоторых сайтов в solution также приходит userAgent. В таком случае форму следует отправлять с указанным User-Agent. Три секунды между запросами и примерно две минуты на опрос — ориентиры, которые можно скорректировать под свой набор тестов. Если любой из двух методов возвращает ненулевой errorId, выполнение прекращается с кодом ошибки API. Так сбой CapMonster Cloud можно отличить от ошибки формы.
Используйте токен сразу. По документации CapMonster Cloud он действует 60 секунд с момента решения капчи, а Google проверяет каждый токен только один раз. Отправьте токен на endpoint формы в поле g-recaptcha-response и проверьте ответ приложения. Само получение токена ещё не говорит о том, что форма сработала.
В пошаговом руководстве по Python и Selenium показано, как передать токен странице с помощью браузера.
Пример на JavaScript
В тесте Playwright можно получить токен через SDK CapMonster Cloud и передать его странице. Тест считывает ключ сайта из виджета, решает задачу, записывает токен в поле g-recaptcha-response и для невидимой версии вызывает функцию, указанную в data-callback. Этот вызов важен: в невидимом режиме именно callback продолжает отправку формы. Одного заполнения поля недостаточно.
import { test, expect } from "@playwright/test";
import {
CapMonsterCloudClientFactory, ClientOptions, RecaptchaV2Request,
} from "@zennolab_com/capmonstercloud-client";
const client = CapMonsterCloudClientFactory.Create(
new ClientOptions({ clientKey: process.env.CAPMONSTER_API_KEY })
);
test("signup with invisible reCAPTCHA v2", async ({ page }) => {
test.setTimeout(120_000);
await page.goto("/signup");
await page.getByLabel("Email").fill("qa-run@example.com");
const widget = page.locator("[data-sitekey]");
const result = await client.Solve(new RecaptchaV2Request({
websiteURL: page.url(),
websiteKey: await widget.getAttribute("data-sitekey"),
isInvisible: true,
}));
if (!result.solution) throw new Error(`CapMonster Cloud error: ${result.error}`);
const token = result.solution.gRecaptchaResponse;
await page.evaluate((token) => {
document.querySelector("#g-recaptcha-response").value = token;
const name = document.querySelector("[data-sitekey]").dataset.callback;
window[name](token);
}, token);
await expect(page.getByText("Check your inbox")).toBeVisible();
});
В примере виджет объявлен в HTML с атрибутами data-sitekey и data-callback. Google требует, чтобы в data-callback было передано имя глобальной функции, поэтому тест может вызвать её через window. Если приложение создаёт виджет через grecaptcha.render(), вызовите callback, который передаёт ваш код. Для версии с флажком уберите isInvisible и отправьте форму так, как это обычно делает приложение. Замените маршрут, подпись поля и текст подтверждения на значения вашей формы. Относительный путь /signup предполагает, что в конфигурации Playwright задан baseURL.
Отправляйте форму вскоре после решения капчи: токен CapMonster Cloud действует 60 секунд. Последняя проверка в примере подтверждает, что пользователь видит ожидаемый результат. На бэкенде дополнительно проверьте, что появилась запись о регистрации.
Тот же сценарий с Selenium WebDriver разобран в руководстве по JavaScript и Selenium.
Три способа передать токен
Когда токен уже получен, остаётся передать его приложению. В сценарии обхода reCAPTCHA v2 это можно сделать тремя способами. Выбор зависит от устройства формы и от того, какую часть сценария нужно проверить.
Запись токена в g-recaptcha-response
Виджет хранит токен в скрытом textarea с идентификатором g-recaptcha-response. Стандартная форма отправляет это поле вместе с остальными данными. Тест может записать значение в textarea из скрипта страницы, а затем отправить форму обычным способом. Для виджета с флажком это работает, если форма отправляется напрямую и не ждёт callback.
await page.evaluate((token) => {
document.querySelector("#g-recaptcha-response").value = token;
}, token);
Вызов функции из data-callback
В невидимой версии заполнения поля недостаточно: форма ждёт вызова callback виджета. Возьмите имя функции из атрибута data-callback и вызовите её с токеном. Google требует, чтобы в этом атрибуте было имя глобальной функции, поэтому тест может обратиться к ней через window. Если приложение создаёт виджет через grecaptcha.render(), вызовите callback, который передаёт ваш код. Если форма также читает textarea, сначала заполните это поле.
await page.evaluate((token) => {
const name = document.querySelector("[data-sitekey]").dataset.callback;
window[name](token);
}, token);
Передача g-recaptcha-response в HTTP-запросе
Данные формы можно отправить без браузера, напрямую на endpoint приложения, добавив токен в поле g-recaptcha-response. Это самый быстрый способ проверить бэкенд, но запрос должен соответствовать запросу со страницы. Нужны те же cookies сессии, CSRF-токен, если его требует форма, и заголовок User-Agent со значением userAgent, если CapMonster Cloud вернул это поле. Бэкенд по-прежнему проверяет токен через Google. Такой сценарий покрывает серверную проверку. Виджет и JavaScript страницы в нём не задействованы.
Почему токен отклоняют
Если форму не удалось отправить, сначала выясните, на каком этапе возникла ошибка. Google мог отклонить токен, а приложение — саму форму из-за правил валидации или авторизации. Обычно ответ быстрее найти в серверных логах запроса. В браузере одно уведомление может соответствовать нескольким ошибкам.
Токен истёк или уже использован. Google принимает стандартный токен v2 в течение двух минут и проверяет его только один раз. CapMonster Cloud отсчитывает свои 60 секунд с момента решения задачи. В обоих случаях Google возвращает timeout-or-duplicate, поэтому по одному коду различить причины нельзя. Проверьте, сколько времени прошло между решением и отправкой и в скольких запросах был один и тот же токен. Повторная попытка, двойной клик или параллельная отправка могут привести к тому, что токен уйдёт дважды.
Устаревший User-Agent. Ошибка возникает на стороне клиента до выдачи токена. Если userAgent, который вы передаёте в CapMonster Cloud, не соответствует поддерживаемому браузеру, Google может показать сообщение update your browser вместо завершения проверки. CapMonster Cloud публикует актуальное значение в справочнике User-Agent.
Не совпадают прокси, User-Agent или cookies. Google принимает в запросе SiteVerify секретный ключ, токен и необязательный remoteip. User-Agent и cookies среди документированных параметров этого запроса отсутствуют. Для некоторых интеграций CapMonster Cloud описывает дополнительные требования. Если задачу решали через свой прокси, отправляйте токен через тот же прокси. Если в solution пришёл userAgent, отправляйте форму с указанным User-Agent, даже если браузер или скрипт обычно использует другой. Для cookies документация рекомендует передавать значения, которые автоматизация использует на целевой странице.
Неверный websiteKey. Значение websiteKey в задаче должно совпадать с data-sitekey виджета на странице, которую вы тестируете. Токен, выпущенный для другого ключа, не пройдёт проверку с секретным ключом вашего бэкенда. Такое бывает, если на стенде и в продакшене разные ключи, а тест берёт из конфигурации ключ другого окружения. Если интеграция проверяет поле hostname в ответе, убедитесь, что она принимает и домен стенда.
Другие распространённые причины разобраны в статье об ошибках проверки reCAPTCHA и способах их устранения.
Что не работает
Если скрыть или удалить виджет reCAPTCHA либо отключить JavaScript, сервер всё равно будет ждать токен в поле g-recaptcha-response. Без действительного токена он отклонит запрос. Уже проверенный токен повторно использовать нельзя. Токен с другой страницы или из другого окружения тоже не пройдёт проверку, если его выдали для другого ключа сайта.
При ручной проверке можно воспользоваться расширением CapMonster Cloud для Chrome или Firefox прямо в браузере, где открыта форма. В автотестах важно проверить и ответ сервера, и результат отправки формы в приложении.
FAQ
CapMonster Cloud
CapMonster Cloud — облачный сервис, который автоматически решает капчу. Для reCAPTCHA v2 он поддерживает виджет с флажком и невидимый виджет через RecaptchaV2Task и возвращает токен, который можно передать форме. Подключиться к сервису можно через API или официальные SDK. В QA-сценарии токен — лишь часть проверки. Также важно проверить верификацию на сервере, обработку формы и ожидаемый результат работы приложения.
NB: Пожалуйста, обратите внимание, что продукт предназначен для автоматизации тестирования исключительно ваших собственных веб-сайтов и ресурсов, к которым у вас есть законное право доступа.






