Laravel Dusk 验证码:在浏览器测试中通过 Turnstile

本指南讲解如何通过 Laravel Dusk 的验证码,也就是让测试穿过别人的小组件,而不是给你的应用加验证码。当 Dusk 测试到达带有 Cloudflare Turnstile 小组件的页面时,测试可以读取 sitekey,用 PHP SDK 向 CapSkip 要一个 token,用 $browser->script() 把它写进小组件的隐藏字段,再点击真实的提交按钮。CapSkip 运行在你自己的 Windows PC 上,所以每个 token 不收取识别费用。
你需要什么
- PHP 8.3 或更新版本用于当前的 Laravel 13 系列,其框架包要求 ^8.3;Laravel 12 用 PHP 8.2,它要求 ^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。我这台报告的版本是 Windows 11 上的 157.0.8103.50,Dusk 会在第 1 步里为它安装 ChromeDriver。
- 你的 Windows PC 上要运行 CapSkip,并安装 capskip/capskip 包 1.7.0 版,也就是我运行的版本。设置指南里的 连接设置 可以让你在 Local mode 和 Server mode 之间选择:前者只在 127.0.0.1 上响应这台 PC,后者在你的网络地址或公网 IP 上响应。
- 带有标准 Turnstile 小组件的页面:一个 class 为 cf-turnstile、带 data-sitekey 属性的 div,Cloudflare 文档把它描述为会让小组件向表单添加隐藏的 cf-turnstile-response 字段的标记。
下面的一切都针对两个模拟服务器运行,一个代替 CapSkip,一个代替 Cloudflare 的 siteverify 检查,被测页面是我自己写的一个带注册表单的小型 Laravel 应用。这台 PC 上真实的 CapSkip 应用没有收到任何任务,所以我没有测量真实的 Turnstile 识别时间,也没有任何真实的 Cloudflare 页面接受过这段代码产生的 token。我也没有测试,在自动化的 Chrome 里,真实的 Cloudflare 小组件是否会保留被注入的值。
第 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
在我的 Windows PHP 构建上,php.ini 里没有指定证书文件,第一次 dusk:install 创建了脚手架,随后在获取 ChromeDriver 下载列表时失败,报 cURL error 60,即 SSL 证书问题。带 detect 选项的 dusk:chrome-driver 也报了同样的错误。运行 php -i 并查找 Loaded Configuration File 这一行,找到你的 php.ini,从 curl.se/docs/caextract.html 下载 cacert.pem,保存为 C:\php\cacert.pem,再把这两行加进那个 php.ini。之后带 detect 选项的命令为我的 Chrome 157 获取了 ChromeDriver 157.0.8103.78。
; 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 会替你在 9515 端口启动 ChromeDriver,并以无头方式运行 Chrome,除非设置了环境变量 DUSK_HEADLESS_DISABLED,已安装的源码就是这么写的。在 8.3.28 和 8.5.0 上,我用可见窗口和无头模式各运行了一遍下面的测试,两种模式都通过了。
告诉 Dusk CapSkip 在哪里
从本地环境启动 Dusk 时,它会读取名为 .env.dusk.local 的文件。文档说它会备份你的 .env,运行期间把 Dusk 文件改名为 .env,结束后再恢复原文件。在我的运行里,.env 的校验和前后完全相同,也没有留下 .env.backup 文件。
这种替换只影响运行测试的那个进程。Dusk 驱动浏览器访问 APP_URL,并不启动你的应用:Dusk 文档里的 CI 示例会在旁边运行 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 可以用 attribute() 读取 data-sitekey,不必解析任何 JavaScript。SDK 调用 turnstile(sitekey, url, options) 接受测试本来就有的两个值。而且 Cloudflare 记录了字段名 cf-turnstile-response,也记录了服务器对它运行的检查。
创建 Laravel 目前还没有的 tests/Concerns 文件夹,把这个 trait 保存在里面,文件名为 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,而此时这个字段其实已经在页面里了。第二,页面地址要作为浏览器当前的 URL 发给 CapSkip。我的模拟站点会把 token 背后的 hostname 与自己的比较,为 localhost 发出的任务,到了以 127.0.0.1 提供服务的站点上,会被一条 hostname 消息拒绝。这条规则是我自己定的,但 siteverify 文档 说明响应里带有 hostname,所以真实站点也能做同样的比较。
第三,辅助函数把 data-action 和 data-cdata 作为 action 和 data 选项转发, CapSkip API 文档 把这两个属性名称列为这两个值的来源。我的小组件带有 data-action,模拟服务器在任务上记录了 action=signup。第四,缺少 sitekey 会很早就失败:对不存在的属性,attribute() 返回 null,SDK 回应了一个 TypeError,说参数 1 必须是 string 类型。用 turnstile.render 创建小组件的页面可能根本没有 data-sitekey,这时 sitekey 就必须取自那个调用。
token 经过两次 json_encode,所以其中没有任何字符能破坏 JavaScript 字符串。更短的写法是 Dusk 的 value() 方法,它通过 executeScript 以同样的方式写入。我确认它也能填充隐藏的 input。
结果还可以带一个 userAgent,Turnstile PHP 指南认为它在挑战页面上是必需的。Dusk 下的 Chrome 报告它自己的字符串,这里是 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 上有一个路由,有一个名为 username 的文本输入框,一个 class 为 cf-turnstile 的 div,带 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>这个示例只检查字段是否存在。下面的结果表来自这个页面的一个更完整的版本,它还会把 token 发给我的模拟 siteverify。
第一个测试是通过的情况。第二个证明页面确实会拒绝没有 token 的表单。把两个都保存到 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,只接受一次 token,并比较 hostname。这些是我自己的规则,不是 Cloudflare 的规则。下面每一行都用模拟 CapSkip、Chrome 157.0.8103.50 和 Windows 11 上的 ChromeDriver 157.0.8103.78,数据取自 PHPUnit 输出的 Duration 行。
| PHP | Laravel | Chrome 窗口 | 结果 |
|---|---|---|---|
| 8.2.29 | 12.72.0 | 可见 | 2 个通过,5.20 秒 |
| 8.3.28 | 13.42.0 | 可见,然后无头 | 2 个通过,分别 4.96 秒和 5.68 秒 |
| 8.4.15 | 13.42.0 | 可见 | 2 个通过,5.27 秒 |
| 8.5.0 | 13.42.0 | 可见,然后无头 | 2 个通过,分别 4.46 秒和 4.33 秒 |
时间限制与 SDK 超时
PHP 设置 max_execution_time 不会中止 Dusk 运行。我在 php.ini 里把它设为 30,测试里的一个探针在 8.2.29、8.3.28、8.4.15 和 8.5.0 上读到的都是 0,因为 php artisan dusk 在命令行上启动 PHPUnit,而命令行下这个限制是关闭的。
对于 Turnstile,PHP SDK 1.7.0 最多等待它的 defaultTimeout,即 120 秒,除非调用传了 timeout 选项,就像 trait 里传的 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 秒后 token 就绪,timeout 60,Dusk 测试 | 48.31 秒后返回 token,表单被接受 |
最后一行还表明浏览器可以等待:Chrome 和 ChromeDriver 在那 48 秒里一直空闲,下一条命令仍然正常。更长的时间我没有测试。Cloudflare 文档说 Turnstile token 的有效期是五分钟,只能用一次,所以要在页面加载之后再请求它,并立刻填入。我把同一个 token 发第二次,被我的模拟服务器以 timeout-or-duplicate 拒绝,文档里对这种情况给出的就是这个代码。
常见错误
在这张表里,标记 seen 表示我针对模拟服务器亲自制造了这个错误。
| 错误 | 原因 | 修复 |
|---|---|---|
| dusk:install 期间出现 cURL error 60 | php.ini 没有指定 CA 证书包(seen) | 在 php.ini 里设置 curl.cainfo,然后用 detect 选项运行 dusk:chrome-driver |
| NetworkException: Failed to connect to 127.0.0.1 port 8080 after about 2000 ms: Couldn’t connect to server | CapSkip 的主机和端口上没有任何服务在监听。大约 2 秒后失败(seen,在关闭的端口上是 2.02 秒) | 启动 CapSkip,并把 .env.dusk.local 里的 CAPSKIP_HOST 和 CAPSKIP_PORT 与它的连接设置对照检查 |
| TimeoutException: timeout 60 exceeded | 截止时间之前没有 token(seen) | 检查 CapSkip 监视器,然后调高 timeout 选项 |
| 带 ERROR_CAPTCHA_UNSOLVABLE 的 ApiException | 模拟服务器作出了应答,但识别失败了(seen) | 再运行一次测试,因为新任务就是一次新的尝试 |
| ValidationException: Unsupported parameters for Turnstile | Turnstile 不接受的选项,例如 invisible(seen) | 从 turnstile 调用里删除那个选项 |
| TypeError: Argument #1 ($sitekey) must be of type string | 小组件没有 data-sitekey 属性(seen) | 从页面的 turnstile.render 调用里读取 sitekey |
| Waited 5 seconds for selector | waitFor 对隐藏字段使用默认限制(seen) | 使用 waitUntilPresent |
| The cf-turnstile-response field is required. | 表单是在字段为空时发送的(seen,第二个测试) | 按下按钮之前先填好字段 |
| Captcha refused: timeout-or-duplicate | 模拟服务器第二次看到这个 token(seen) | 每次提交表单都请求一个新的 token |
| 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 后,一次识别我数到两条记录(seen) | 保留它,或者过滤它,直到 SDK 去掉这个调用 |
在另一台机器上运行 CapSkip
Dusk 测试套件不必运行在托管 CapSkip 的那台 PC 上。把 CapSkip 切换到 Server mode,把那台机器的地址写进 .env.dusk.local 里的 CAPSKIP_HOST,辅助函数里的其他内容都不用改。如果开启了 API Key Validation,就加上带你密钥的 CAPSKIP_API_KEY,辅助函数会把它作为 apiKey 传入。Server mode 启动时,CapSkip 会向所有地址开放它的端口,所以要把访问限制在你预期的机器上,就为其他机器添加一条 Windows 防火墙阻止规则。识别工具仍然运行在你自己的 Windows 机器上。
常见问题
我自己应用的测试到底要不要识别它的验证码?
通常不需要。应用是你自己的,就在 Dusk 环境里关闭这项检查,或者伪造验证。本指南针对的是你无法改动其验证的页面,比如别人运行的预发布站点。
同样的辅助函数能用于 reCAPTCHA 或 MTCaptcha 吗?
SDK 有形式相同的 recaptcha() 和 mtcaptcha(),但字段名不同,而且我只运行了 Turnstile。 Symfony Panther 指南 展示了在 PHP 浏览器脚本里处理 reCAPTCHA。
我该用 Pest 浏览器测试代替 Dusk 吗?
Dusk 文档现在建议新项目的浏览器测试使用 Pest 4。CapSkip 的调用是普通 PHP,所以同样的做法应该可以沿用,但我只运行了 Dusk。
这也适用于队列任务吗?
不适用。任务有它自己的 worker 限制,相关内容见 Laravel 队列指南 里的介绍。Dusk 测试是一个命令行进程,所以这里起作用的限制是 SDK 超时。
Laravel Dusk 的验证码步骤归结为四个动作:等待隐藏字段,读取 sitekey,在需要之前才请求 token,并用 script() 写入。如果你需要一个 验证码识别工具 (不按 token 收费),CapSkip 运行在你自己的 PC 上,所以失败的运行只多花一次测试运行的成本。 Cloudflare Turnstile 识别页面 介绍小组件本身, Turnstile PHP 指南 展示不带浏览器的同一调用,而 PHP 验证码识别页面 列出其他类型。
