Laravel Dusk CAPTCHA: как пройти Turnstile в браузерном тесте

Это руководство показывает, как пройти Laravel Dusk CAPTCHA, то есть как заставить тест пройти чужой виджет, а не как добавить капчу в своё приложение. Когда тест Dusk попадает на страницу с виджетом Cloudflare Turnstile, он может прочитать sitekey, запросить у CapSkip токен через PHP SDK, записать его в скрытое поле виджета с помощью $browser->script() и нажать настоящую кнопку отправки. CapSkip работает на вашем собственном ПК с Windows, поэтому за токен не нужно платить за каждое решение.
Что понадобится
- PHP 8.3 или новее для актуальной ветки Laravel 13, пакет фреймворка которой требует ^8.3, или PHP 8.2 для Laravel 12, который требует ^8.2. Проверьте свою версию командой php -v и при необходимости скачайте более новую сборку с windows.php.net. Dusk 8.8.0 и устанавливаемому им пакету php-webdriver также нужно расширение zip. В php.ini я включил curl, openssl, mbstring, fileinfo, zip, pdo_sqlite, sqlite3 и intl. Я запускал 8.2.29 с Laravel 12.72.0, а также 8.3.28, 8.4.15 и 8.5.0 с Laravel 13.42.0.
- Google Chrome. У меня он показывал 157.0.8103.50 на Windows 11, а Dusk ставит для него ChromeDriver на шаге 1.
- CapSkip, запущенный на вашем ПК с Windows, и пакет capskip/capskip версии 1.7.0, той, которую я запускал. Настройки подключения в руководстве по настройке позволяют выбрать между Local mode, при котором CapSkip отвечает по 127.0.0.1 только на этом ПК, и Server mode, при котором он отвечает по вашему сетевому адресу или публичному IP.
- Страница со стандартным виджетом Turnstile: div с классом cf-turnstile и атрибутом data-sitekey. Именно такую разметку документация Cloudflare описывает как ту, из-за которой виджет добавляет в форму невидимое поле cf-turnstile-response.
Всё ниже запускалось на двух имитациях: одна заменяла CapSkip, другая заменяла проверку Cloudflare siteverify, а тестируемой страницей было небольшое моё приложение на Laravel с формой регистрации. Настоящее приложение CapSkip на этом ПК не получило ни одного задания, поэтому реальное время решения Turnstile я не измерял, и ни одна настоящая страница Cloudflare не принимала токен от этого кода. Я также не проверял, сохранит ли настоящий виджет Cloudflare внедрённое значение в автоматизированном Chrome.
Шаг 1: установите Dusk, ChromeDriver и настройки CapSkip
Документация Laravel Dusk предписывает поставить Chrome и пакет laravel/dusk, затем выполнить команду dusk:install, которая создаёт tests/Browser и скачивает ChromeDriver. CapSkip тоже ставится как зависимость для разработки, потому что вызывают его только тесты.
# PowerShell, in the root folder of your Laravel project composer require --dev laravel/dusk capskip/capskip php artisan dusk:install
На моих сборках PHP для Windows, в php.ini которых не был указан файл сертификатов, первый запуск dusk:install создал каркас, а затем завершился ошибкой cURL error 60 (проблема с SSL-сертификатом) при получении списка загрузок ChromeDriver. Та же ошибка пришла от dusk:chrome-driver с параметром detect. Выполните php -i и найдите строку Loaded Configuration File, чтобы узнать, где лежит ваш php.ini, скачайте cacert.pem со страницы curl.se/docs/caextract.html, сохраните его как C:\php\cacert.pem и добавьте эти две строки в тот php.ini. После этого параметр detect скачал ChromeDriver 157.0.8103.78 для моего Chrome 157.
; In php.ini, with cacert.pem saved at this path curl.cainfo="C:\php\cacert.pem" openssl.cafile="C:\php\cacert.pem"
# Install the ChromeDriver that matches the Chrome on this PC php artisan dusk:chrome-driver --detect
Сгенерированный tests/DuskTestCase.php сам запускает ChromeDriver на порту 9515 и открывает Chrome без окна (headless), если не задана переменная окружения DUSK_HEADLESS_DISABLED, как видно по установленному исходному коду. На 8.3.28 и 8.5.0 я запускал приведённые ниже тесты сначала с видимым окном, потом в headless-режиме, и оба режима прошли.
Укажите Dusk, где находится CapSkip
Dusk читает файл .env.dusk.local, когда вы запускаете его из локального окружения. По документации он делает резервную копию вашего .env, на время запуска переименовывает файл Dusk в .env и затем восстанавливает оригинал. В моих запусках контрольная сумма .env до и после совпадала, а файл .env.backup не оставался.
Такая подмена действует только на процесс, который запускает ваши тесты. Dusk управляет браузером по адресу APP_URL и не запускает ваше приложение: в примерах для CI из документации Dusk рядом запускают php artisan serve. Так что запустите его сами и сделайте APP_URL равным адресу, который откроет браузер. Когда в .env не было настроек CapSkip, имитация всё равно получала каждое задание, а значит, тестовый процесс читал .env.dusk.local.
# PowerShell, in the project folder: copy .env, then change and add lines Copy-Item .env .env.dusk.local (Get-Content .env.dusk.local) -replace '^APP_URL=.*', 'APP_URL=http://127.0.0.1:8000' | Set-Content .env.dusk.local Add-Content .env.dusk.local "`nCAPSKIP_HOST=127.0.0.1`nCAPSKIP_PORT=8080"
Шаг 2: хелпер, который решает виджет
Я выбрал Turnstile, а не reCAPTCHA или MTCaptcha, по трём причинам. Виджет представляет собой обычный div, поэтому Dusk может прочитать data-sitekey через attribute(), и разбирать JavaScript не нужно. Вызов SDK turnstile(sitekey, url, options) принимает два значения, которые тест уже знает. А Cloudflare документирует и имя поля, cf-turnstile-response, и проверку, которую сервер выполняет над ним.
Создайте папку tests/Concerns, которой в Laravel пока нет, и сохраните в ней этот трейт как SolvesTurnstile.php. Четыре детали в нём появились по итогам запусков.
<?php
namespace Tests\Concerns;
use CapSkip\CapSkip;
use Laravel\Dusk\Browser;
trait SolvesTurnstile
{
/**
* Ask CapSkip for a token for the Turnstile widget on the current page
* and write it into the widget's hidden field.
*/
protected function solveTurnstile(Browser $browser, string $widget = '.cf-turnstile'): string
{
$solver = new CapSkip([
'host' => env('CAPSKIP_HOST', '127.0.0.1'),
'port' => (int) env('CAPSKIP_PORT', 8080),
'apiKey' => env('CAPSKIP_API_KEY', 'capskip'),
]);
// The widget adds its hidden field after the page loads, and the field
// is never displayed, so wait for presence and not for visibility.
$browser->waitUntilPresent('input[name="cf-turnstile-response"]');
$options = ['timeout' => 60]; // seconds the SDK may wait for the token
foreach (['action' => 'data-action', 'data' => 'data-cdata'] as $option => $attribute) {
$value = $browser->attribute($widget, $attribute);
if ($value !== null) {
$options[$option] = $value;
}
}
$result = $solver->turnstile(
$browser->attribute($widget, 'data-sitekey'),
$browser->driver->getCurrentURL(),
$options
);
$browser->script(sprintf(
'document.querySelector(%s).value = %s;',
json_encode('input[name="cf-turnstile-response"]'),
json_encode($result['code'])
));
return $result['code'];
}
}Первое: ждите через waitUntilPresent. В исходном коде Dusk сказано, что waitFor ждёт, пока элемент будет отображён, а скрытое поле input не отображается никогда: в моём запуске waitFor с явным лимитом 3 секунды завершился через 3.19 секунды с WebDriver TimeoutException с текстом Waited 3 seconds for selector, а с лимитом по умолчанию завершился через 5.17 секунды с текстом Waited 5 seconds for selector, хотя поле уже было на странице. Второе: адрес страницы уходит в CapSkip как текущий URL браузера. Моя имитация сайта сравнивает hostname, зашитый в токен, со своим, и задание, отправленное для localhost при сайте, открытом на 127.0.0.1, было отклонено с сообщением о hostname. Это правило моё, но документация по siteverify тоже указывает hostname в ответе, так что настоящий сайт может провести такое же сравнение.
Третье: хелпер передаёт data-action и data-cdata как параметры action и data. Об этом говорит Документация по API CapSkip и называет эти атрибуты источниками обоих значений. В моём виджете был data-action, и имитация записала в журнал для задания action=signup. Четвёртое: отсутствующий sitekey приводит к раннему сбою: attribute() возвращает null для отсутствующего атрибута, а SDK отвечал TypeError с текстом, что аргумент 1 должен быть типа string. Страница, которая создаёт виджет через turnstile.render, может вообще не иметь data-sitekey, и тогда sitekey нужно брать из этого вызова.
Токен дважды проходит через json_encode, поэтому ни один символ в нём не сломает строку JavaScript. Более короткий вариант: метод value() в Dusk, который записывает так же, через executeScript. Я подтвердил, что он заполняет и скрытое поле input.
Результат может содержать и userAgent, который руководство Turnstile для PHP считает обязательным на страницах с проверкой. Chrome под управлением Dusk сообщает собственную строку, здесь это Chrome/157.0.0.0, а моя имитация сообщила строку Chrome/140. Если ваш сайт их сравнивает, добавьте это в хелпер.
// Optional, before the return line of solveTurnstile(): later requests of this
// browser then carry the User-Agent string that CapSkip reported for the token.
if (isset($result['userAgent'])) {
$browser->driver->executeCustomCommand('/session/:sessionId/goog/cdp/execute', 'POST', [
'cmd' => 'Network.setUserAgentOverride',
'params' => ['userAgent' => $result['userAgent']],
]);
}На 8.3.28 против имитации страница, открытая после этого вызова, показывала серверу и в navigator.userAgent строку Chrome/140. Не проверял, важно ли настоящему сайту это совпадение.
Шаг 3: напишите тест и запустите его
Тестируемая страница
Тесты ожидают такой контракт: маршрут /signup, текстовое поле input с именем username, div с классом cf-turnstile, data-sitekey и data-action, кнопка с подписью Create account, перенаправление на /welcome с текстом Welcome и именем, а также сообщение проверки The cf-turnstile-response field is required. при пустом поле. Если у вас нет такой страницы, замените routes/web.php и сохраните представление как resources/views/signup.blade.php.
<?php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;
Route::get('/signup', fn () => view('signup'));
Route::post('/signup', function (Request $request) {
$data = $request->validate([
'username' => ['required', 'string', 'max:40'],
'cf-turnstile-response' => ['required', 'string'],
]);
return redirect('/welcome')->with('name', $data['username']);
});
Route::get('/welcome', fn (Request $request) =>
'<h1>Welcome, ' . e($request->session()->get('name', 'stranger')) . '</h1>');<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><title>Sign up</title></head>
<body>
@foreach ($errors->all() as $message)
<p class="error">{{ $message }}</p>
@endforeach
<form method="POST" action="/signup">
@csrf
<input type="text" name="username">
<div class="cf-turnstile" data-sitekey="0x4AAAAAAAEXAMPLE" data-action="signup"></div>
<button type="submit">Create account</button>
</form>
<script>
// Stand-in for the Cloudflare script: the real widget adds this hidden
// input to the form a moment after the page has loaded.
setTimeout(function () {
var field = document.createElement('input');
field.type = 'hidden';
field.name = 'cf-turnstile-response';
document.querySelector('.cf-turnstile').appendChild(field);
}, 400);
</script>
</body>
</html>Этот пример лишь проверяет, что поле присутствует. Таблица результатов ниже получена на более полной версии страницы, которая ещё отправляла токен в мой имитированный siteverify.
Первый тест проверяет успешный проход. Второй показывает, что страница действительно отклоняет форму без токена. Сохраните оба в tests/Browser/SignupCaptchaTest.php.
<?php
namespace Tests\Browser;
use Laravel\Dusk\Browser;
use Tests\Concerns\SolvesTurnstile;
use Tests\DuskTestCase;
class SignupCaptchaTest extends DuskTestCase
{
use SolvesTurnstile;
public function test_signup_passes_the_captcha(): void
{
$this->browse(function (Browser $browser) {
$browser->visit('/signup')
->type('username', 'alice');
$this->solveTurnstile($browser);
$browser->press('Create account')
->waitForText('Welcome, alice')
->assertPathIs('/welcome');
});
}
public function test_signup_without_a_token_is_refused(): void
{
$this->browse(function (Browser $browser) {
$browser->visit('/signup')
->type('username', 'bob')
->waitUntilPresent('input[name="cf-turnstile-response"]')
->press('Create account')
->waitForText('The cf-turnstile-response field is required.')
->assertPathIs('/signup');
});
}
}Если ваша страница отличается, измените путь, имена полей, подпись кнопки и тексты. Затем откройте два приглашения PowerShell: одно для приложения, другое для тестов.
# First prompt, in the project folder: serve the app php artisan serve --host=127.0.0.1 --port=8000 # Second prompt, same folder: run the browser tests php artisan dusk # Optional, to watch Chrome: set this PowerShell variable before the line above $env:DUSK_HEADLESS_DISABLED = 'true'
Мой имитированный сайт проверяет, что поле заполнено, отправляет его в имитированный siteverify, принимает токен один раз и сравнивает hostname. Это мои правила, а не правила Cloudflare. Каждая строка ниже получена с имитацией CapSkip, Chrome 157.0.8103.50 и ChromeDriver 157.0.8103.78 на Windows 11 по строке Duration из вывода PHPUnit.
| PHP | Laravel | Окно Chrome | Результат |
|---|---|---|---|
| 8.2.29 | 12.72.0 | видимое | 2 пройдено, 5.20 секунды |
| 8.3.28 | 13.42.0 | видимое, затем headless | 2 пройдено, 4.96 и 5.68 секунды |
| 8.4.15 | 13.42.0 | видимое | 2 пройдено, 5.27 секунды |
| 8.5.0 | 13.42.0 | видимое, затем headless | 2 пройдено, 4.46 и 4.33 секунды |
Лимит времени и таймаут SDK
Параметр PHP max_execution_time не останавливает запуск Dusk. Я поставил его в 30 в php.ini, и проба внутри теста прочитала 0 на 8.2.29, 8.3.28, 8.4.15 и 8.5.0, потому что php artisan dusk запускает PHPUnit из командной строки, где этот лимит отключён.
Для Turnstile PHP SDK 1.7.0 ждёт до своего defaultTimeout, 120 секунд, если вызов не передаёт параметр timeout, как это делает трейт со значением 60. SDK читает результат через 0, 0.25, 0.75, 1.75 и 3.75 секунды после отправки, затем на 7.75 и далее каждые 5 секунд, а срок проверяет только тогда, когда подходит время следующего чтения. Поэтому вызов завершается позже, чем число, которое вы указали.
| Имитация CapSkip, которая никогда не завершает задание | Измерено |
|---|---|
| timeout 5, внутри теста Dusk, PHP 8.3.28 | TimeoutException через 7.83 секунды |
| timeout 60, обычная командная строка, PHP 8.3.28 | TimeoutException через 62.97 секунды, последнее чтение на 57.93 |
| Токен готов через 45 секунд, timeout 60, тест Dusk | Токен возвращён через 48.31 секунды, форма принята |
Последняя строка также показывает, что браузер умеет ждать: Chrome и ChromeDriver простояли без дела эти 48 секунд, и следующая команда сработала. Более долгое ожидание я не проверял. По документации Cloudflare токен Turnstile живёт пять минут и годится для одного использования, поэтому запрашивайте его после загрузки страницы и сразу подставляйте. Токен, отправленный мной второй раз, моя имитация отклонила с timeout-or-duplicate, этот код документация называет для такого случая.
Частые ошибки
В этой таблице «воспроизведено» означает, что я сам получил эту ошибку на имитациях.
| Ошибка | Причина | Исправить |
|---|---|---|
| cURL error 60 при dusk:install | В php.ini не указан пакет CA (воспроизведено) | Задайте curl.cainfo в php.ini, затем запустите dusk:chrome-driver с параметром detect |
| NetworkException: Failed to connect to 127.0.0.1 port 8080 after about 2000 ms: Couldn’t connect to server | По адресу и порту CapSkip ничего не слушает. Ошибка пришла примерно через 2 секунды (воспроизведено, 2.02 с на закрытом порту) | Запустите CapSkip и сверьте CAPSKIP_HOST и CAPSKIP_PORT в .env.dusk.local с его настройками подключения |
| TimeoutException: timeout 60 exceeded | Токен не пришёл до истечения срока (воспроизведено) | Проверьте монитор CapSkip, затем увеличьте параметр timeout |
| ApiException с ERROR_CAPTCHA_UNSOLVABLE | Имитация ответила, но решение не удалось (воспроизведено) | Запустите тест снова: новое задание это новая попытка |
| ValidationException: Unsupported parameters for Turnstile | Параметр, который Turnstile не принимает, например invisible (воспроизведено) | Уберите этот параметр из вызова turnstile |
| TypeError: Argument #1 ($sitekey) must be of type string | У виджета нет атрибута data-sitekey (воспроизведено) | Прочитайте sitekey из вызова turnstile.render на странице |
| Waited 5 seconds for selector | waitFor с лимитом по умолчанию для скрытого поля (воспроизведено) | Используйте waitUntilPresent |
| The cf-turnstile-response field is required. | Форму отправили с пустым полем (воспроизведено, второй тест) | Заполните поле до нажатия кнопки |
| Captcha refused: timeout-or-duplicate | Имитация увидела токен второй раз (воспроизведено) | Запрашивайте новый токен для каждой отправки формы |
| Deprecated: curl_close() | Полный текст: Function curl_close() is deprecated since 8.5, as it has no effect since PHP 8.0. SDK всё ещё вызывает эту функцию. Laravel отправляет это в канал журнала из LOG_DEPRECATIONS_CHANNEL, в основе проекта это null, поэтому ничего не выводилось. Когда канал был single, я насчитал две записи на одно решение (воспроизведено) | Оставьте как есть или отфильтруйте, пока SDK не уберёт этот вызов |
Запуск CapSkip на другой машине
Набор тестов Dusk не обязан работать на том ПК, где стоит CapSkip. Переключите CapSkip в Server mode, впишите адрес этой машины в CAPSKIP_HOST в .env.dusk.local, и больше ничего в хелпере менять не придётся. Если включена API Key Validation, добавьте CAPSKIP_API_KEY с вашим ключом, который хелпер передаёт как apiKey. При запуске Server mode CapSkip открывает свой порт для всех адресов, поэтому, чтобы оставить доступ только нужным машинам, добавьте для остальных правило блокировки в брандмауэре Windows. Решение по-прежнему выполняется на вашей собственной машине с Windows.
FAQ
Нужно ли тестам моего собственного приложения вообще решать его капчу?
Обычно нет. Когда приложение ваше, отключите проверку или подмените верификацию в окружении Dusk. Это руководство для страниц, верификацию которых вы изменить не можете, например для тестового сайта, который ведёт кто-то другой.
Подойдёт ли тот же хелпер для reCAPTCHA или MTCaptcha?
В SDK есть recaptcha() и mtcaptcha() такой же формы, но имена полей отличаются, а я запускал только Turnstile. Руководство по Symfony Panther показывает reCAPTCHA в браузерном скрипте на PHP.
Стоит ли использовать браузерное тестирование Pest вместо Dusk?
Теперь документация Dusk рекомендует Pest 4 для браузерных тестов в новых проектах. Вызов CapSkip это обычный PHP, поэтому та же идея должна работать и там, но я запускал только Dusk.
Подходит ли это и для заданий очереди?
Нет. У задания свои лимиты воркера, и о них рассказывает руководство по очередям Laravel подробно. Тест Dusk это процесс командной строки, поэтому действовал здесь лимит таймаута SDK.
Шаг Laravel Dusk CAPTCHA сводится к четырём действиям: дождаться скрытого поля, прочитать sitekey, запросить токен прямо перед тем, как он понадобится, и записать его через script(). Если нужно распознавание капчи без платы за каждый токен, CapSkip работает на вашем ПК, поэтому неудачный запуск стоит лишь ещё одного прогона теста. Виджет разобран на странице сервиса распознавания Cloudflare Turnstile целиком; руководство по Turnstile для PHP показывает тот же вызов без браузера, а на странице сервиса распознавания капчи для PHP перечислены остальные типы.
