Laravel Dusk CAPTCHA: Melewati Turnstile di Test Browser

Panduan ini menunjukkan cara melewati Laravel Dusk CAPTCHA, yaitu test yang harus melewati widget milik pihak lain, bukan cara memasang CAPTCHA di aplikasi Anda. Saat test Dusk sampai di halaman dengan widget Cloudflare Turnstile, test itu dapat membaca sitekey, meminta token ke CapSkip lewat SDK PHP, menuliskannya ke field tersembunyi pada widget dengan $browser->script(), lalu menekan tombol submit yang asli. CapSkip berjalan di PC Windows Anda sendiri, jadi satu token tidak dikenai biaya per pemecahan.
Apa yang Anda butuhkan
- PHP 8.3 atau lebih baru untuk Laravel 13 yang berlaku saat ini, yang paket framework-nya mensyaratkan ^8.3, atau PHP 8.2 untuk Laravel 12, yang mensyaratkan ^8.2. Periksa versi Anda dengan php -v, dan unduh build yang lebih baru dari windows.php.net jika perlu. Dusk 8.8.0 dan paket php-webdriver yang diinstalnya juga memerlukan ekstensi zip. Di php.ini saya mengaktifkan curl, openssl, mbstring, fileinfo, zip, pdo_sqlite, sqlite3 dan intl. Saya menjalankan 8.2.29 dengan Laravel 12.72.0, serta 8.3.28, 8.4.15 dan 8.5.0 dengan Laravel 13.42.0.
- Google Chrome. Milik saya melaporkan 157.0.8103.50 di Windows 11, dan Dusk menginstal ChromeDriver untuknya di Langkah 1.
- CapSkip yang berjalan di PC Windows Anda, dan paket capskip/capskip pada 1.7.0, yaitu versi yang saya jalankan. Bagian pengaturan koneksi di panduan penyiapan menjelaskan pilihan antara Local mode, yang menjawab di 127.0.0.1 hanya untuk PC itu, dan Server mode, yang menjawab di alamat jaringan atau IP publik Anda.
- Halaman yang memuat widget Turnstile standar: sebuah div dengan class cf-turnstile dan atribut data-sitekey, yang dalam dokumentasi Cloudflare dijelaskan sebagai markup yang membuat widget menambahkan field cf-turnstile-response yang tidak terlihat ke formulir.
Semua yang ada di bawah dijalankan terhadap dua mock, satu sebagai pengganti CapSkip dan satu sebagai pengganti pemeriksaan siteverify dari Cloudflare, dan halaman yang diuji adalah aplikasi Laravel kecil buatan saya dengan formulir pendaftaran. Aplikasi CapSkip asli di PC ini tidak menerima task apa pun, jadi saya tidak mengukur waktu pemecahan Turnstile yang sebenarnya, dan tidak ada halaman Cloudflare asli yang pernah menerima token dari kode ini. Saya juga tidak menguji apakah widget Cloudflare asli di Chrome otomatis membiarkan nilai yang disuntikkan tetap ada.
Langkah 1: instal Dusk, ChromeDriver dan pengaturan CapSkip
Dokumen Laravel Dusk meminta Chrome dan paket laravel/dusk, lalu perintah dusk:install, yang membuat tests/Browser dan mengunduh ChromeDriver. CapSkip juga dimasukkan sebagai dependensi pengembangan, karena hanya test yang memanggilnya.
# PowerShell, in the root folder of your Laravel project composer require --dev laravel/dusk capskip/capskip php artisan dusk:install
Pada build PHP Windows saya, yang php.ini-nya tidak menyebut file sertifikat, dusk:install pertama membuat kerangka lalu gagal dengan cURL error 60, masalah sertifikat SSL, saat mengambil daftar unduhan ChromeDriver. Error yang sama muncul dari dusk:chrome-driver dengan opsi detect. Jalankan php -i dan cari baris Loaded Configuration File untuk menemukan php.ini Anda, unduh cacert.pem dari curl.se/docs/caextract.html, simpan sebagai C:\php\cacert.pem dan tambahkan dua baris ini ke php.ini tersebut. Setelah itu opsi detect mengambil ChromeDriver 157.0.8103.78 untuk Chrome 157 saya.
; 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
File tests/DuskTestCase.php yang dihasilkan menjalankan ChromeDriver untuk Anda di port 9515 dan menjalankan Chrome dalam mode headless kecuali variabel lingkungan DUSK_HEADLESS_DISABLED diatur, seperti yang terlihat di source yang terinstal. Pada 8.3.28 dan 8.5.0 saya menjalankan test di bawah dengan jendela yang terlihat lalu lagi dalam mode headless, dan kedua mode lulus.
Beri tahu Dusk di mana CapSkip berada
Dusk membaca file bernama .env.dusk.local saat Anda menjalankannya dari lingkungan lokal. Menurut dokumentasi, Dusk mencadangkan .env Anda, mengganti nama file Dusk itu menjadi .env selama proses berjalan, lalu memulihkan yang asli sesudahnya. Pada proses saya, checksum .env sama persis sebelum dan sesudahnya, dan tidak ada file .env.backup yang tertinggal.
Pertukaran itu hanya berlaku untuk proses yang menjalankan test Anda. Dusk mengendalikan browser ke APP_URL dan tidak menjalankan aplikasi Anda: contoh CI di dokumentasi Dusk menjalankan php artisan serve di sampingnya. Jadi jalankan sendiri aplikasinya, dan pastikan APP_URL sama dengan alamat yang akan dikunjungi browser. Tanpa pengaturan CapSkip di .env, mock tetap menerima setiap task, jadi proses test membaca .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"
Langkah 2: helper yang memecahkan widget
Saya memilih Turnstile dibanding reCAPTCHA dan MTCaptcha karena tiga alasan. Widget-nya hanya sebuah div, jadi Dusk bisa membaca data-sitekey dengan attribute() tanpa perlu mengurai JavaScript. Panggilan SDK turnstile(sitekey, url, options) memakai dua nilai yang sudah dimiliki test. Dan Cloudflare mendokumentasikan nama field-nya, cf-turnstile-response, serta pemeriksaan yang dijalankan server terhadapnya.
Buat folder tests/Concerns, yang belum ada di Laravel, lalu simpan trait ini di sana sebagai SolvesTurnstile.php. Empat detail di dalamnya berasal dari hasil percobaan.
<?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'];
}
}Pertama, tunggu dengan waitUntilPresent. Source Dusk menyebut waitFor menunggu sampai elemen ditampilkan, dan input tersembunyi tidak pernah ditampilkan: pada percobaan saya waitFor dengan batas eksplisit 3 detik berakhir setelah 3.19 detik dengan TimeoutException dari WebDriver yang berbunyi Waited 3 seconds for selector, dan dengan batas default berakhir setelah 5.17 detik dengan Waited 5 seconds for selector, padahal field-nya sudah ada di halaman. Kedua, alamat halaman dikirim ke CapSkip sebagai URL browser saat ini. Situs mock saya membandingkan hostname di balik token dengan hostname miliknya sendiri, dan task yang dikirim untuk localhost terhadap situs yang dilayani di 127.0.0.1 ditolak dengan pesan hostname. Aturan itu buatan saya, tetapi dokumen siteverify mencantumkan hostname dalam respons, sehingga situs asli dapat melakukan perbandingan yang sama.
Ketiga, helper meneruskan data-action dan data-cdata sebagai opsi action dan data, yang dalam Dokumentasi API CapSkip disebut sebagai sumber kedua nilai itu. Widget saya membawa data-action, dan mock mencatat action=signup pada task. Keempat, sitekey yang hilang membuat proses gagal lebih awal: attribute() mengembalikan null untuk atribut yang tidak ada, dan SDK menjawab dengan TypeError yang menyatakan argumen 1 harus bertipe string. Halaman yang membuat widget-nya dengan turnstile.render mungkin tidak punya data-sitekey sama sekali, dan dalam kasus itu sitekey harus diambil dari panggilan tersebut.
Token melewati json_encode dua kali, sehingga tidak ada karakter di dalamnya yang bisa merusak string JavaScript. Bentuk yang lebih singkat adalah metode value() milik Dusk, yang menulis dengan cara sama, lewat executeScript. Saya memastikan bahwa metode itu juga mengisi input tersembunyi.
Hasilnya juga bisa membawa userAgent, yang oleh panduan Turnstile PHP dianggap wajib pada halaman tantangan. Chrome di bawah Dusk melaporkan string-nya sendiri, di sini Chrome/157.0.0.0, dan mock saya melaporkan string Chrome/140. Jika situs Anda membandingkannya, tambahkan ini ke helper.
// 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']],
]);
}Pada 8.3.28 terhadap mock, halaman yang dikunjungi setelah panggilan itu menampilkan string Chrome/140 pada server dan navigator.userAgent. Saya tidak menguji apakah situs asli peduli pada kecocokan itu.
Langkah 3: tulis test dan jalankan
Halaman yang diuji
Test mengharapkan kontrak ini: sebuah route di /signup, input teks bernama username, sebuah div dengan class cf-turnstile, sebuah data-sitekey dan sebuah data-action, tombol berlabel Create account, pengalihan ke /welcome yang menampilkan Welcome dan nama, serta pesan validasi The cf-turnstile-response field is required. saat field kosong. Jika Anda tidak punya halaman seperti itu, ganti routes/web.php dan simpan view sebagai 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>Contoh ini hanya memeriksa bahwa field-nya ada. Tabel hasil di bawah berasal dari versi halaman yang lebih lengkap, yang juga mengirim token ke siteverify mock saya.
Test pertama adalah yang lulus. Test kedua menunjukkan bahwa halaman benar-benar menolak formulir tanpa token. Simpan keduanya di 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');
});
}
}Jika halaman Anda berbeda, ubah path, nama field, label tombol dan teksnya. Lalu gunakan dua prompt PowerShell, satu untuk aplikasi dan satu untuk test.
# 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'
Situs mock saya memvalidasi field sebagai wajib, mengirimkannya ke siteverify mock, menerima token satu kali dan membandingkan hostname. Itu aturan saya, bukan aturan Cloudflare. Setiap baris di bawah memakai CapSkip mock, Chrome 157.0.8103.50 dan ChromeDriver 157.0.8103.78 di Windows 11, dengan baris Duration dari output PHPUnit.
| PHP | Laravel | Jendela Chrome | Hasil |
|---|---|---|---|
| 8.2.29 | 12.72.0 | terlihat | 2 passed, 5.20 detik |
| 8.3.28 | 13.42.0 | terlihat, lalu headless | 2 passed, 4.96 dan 5.68 detik |
| 8.4.15 | 13.42.0 | terlihat | 2 passed, 5.27 detik |
| 8.5.0 | 13.42.0 | terlihat, lalu headless | 2 passed, 4.46 dan 4.33 detik |
Batas waktu dan timeout SDK
Pengaturan PHP max_execution_time tidak menghentikan proses Dusk. Saya mengaturnya ke 30 di php.ini, dan probe di dalam test membaca 0 pada 8.2.29, 8.3.28, 8.4.15 dan 8.5.0, karena php artisan dusk menjalankan PHPUnit di command line, tempat batas itu nonaktif.
Untuk Turnstile, SDK PHP 1.7.0 menunggu hingga defaultTimeout-nya, 120 detik, kecuali panggilan menyertakan opsi timeout, seperti yang dilakukan trait dengan 60. SDK membaca hasilnya pada 0, 0.25, 0.75, 1.75 dan 3.75 detik setelah pengiriman, lalu pada 7.75 dan setiap 5 detik, dan hanya memeriksa batas waktu ketika pembacaan berikutnya jatuh tempo. Jadi panggilan berakhir lebih lambat daripada angka yang Anda berikan.
| CapSkip mock, tidak pernah selesai | Terukur |
|---|---|
| timeout 5, di dalam test Dusk, PHP 8.3.28 | TimeoutException setelah 7.83 detik |
| timeout 60, command line biasa, PHP 8.3.28 | TimeoutException setelah 62.97 detik, pembacaan terakhir pada 57.93 |
| Token siap setelah 45 detik, timeout 60, test Dusk | Token dikembalikan setelah 48.31 detik, formulir diterima |
Baris terakhir juga menunjukkan bahwa browser bisa menunggu: Chrome dan ChromeDriver diam selama 48 detik itu dan perintah berikutnya tetap berjalan. Saya tidak menguji waktu yang lebih lama. Dokumentasi Cloudflare memberi token Turnstile masa hidup lima menit dan satu kali pakai, jadi minta token setelah halaman selesai dimuat dan isikan segera. Token yang saya kirim untuk kedua kalinya ditolak oleh mock saya dengan timeout-or-duplicate, kode yang disebut dokumentasi untuk kasus itu.
Kesalahan umum
Dalam tabel ini, seen berarti saya sendiri yang memunculkan error itu terhadap mock.
| Kesalahan | Penyebab | Perbaiki |
|---|---|---|
| cURL error 60 saat dusk:install | php.ini tidak menyebut CA bundle (seen) | Atur curl.cainfo di php.ini, lalu jalankan dusk:chrome-driver dengan opsi detect |
| NetworkException: Failed to connect to 127.0.0.1 port 8080 after about 2000 ms: Couldn’t connect to server | Tidak ada yang mendengarkan di host dan port CapSkip. Gagal setelah sekitar 2 detik (seen, 2.02 detik pada port tertutup) | Jalankan CapSkip, dan bandingkan CAPSKIP_HOST dan CAPSKIP_PORT di .env.dusk.local dengan pengaturan koneksinya |
| TimeoutException: timeout 60 exceeded | Tidak ada token sebelum batas waktu (seen) | Periksa monitor CapSkip, lalu naikkan opsi timeout |
| ApiException dengan ERROR_CAPTCHA_UNSOLVABLE | Mock menjawabnya; pemecahan gagal (seen) | Jalankan test lagi, karena task baru adalah percobaan baru |
| ValidationException: Unsupported parameters for Turnstile | Opsi yang tidak diterima Turnstile, seperti invisible (seen) | Hapus opsi itu dari panggilan turnstile |
| TypeError: Argument #1 ($sitekey) must be of type string | Widget tidak memiliki atribut data-sitekey (seen) | Baca sitekey dari panggilan turnstile.render di halaman |
| Waited 5 seconds for selector | waitFor dengan batas default pada field tersembunyi (seen) | Gunakan waitUntilPresent |
| The cf-turnstile-response field is required. | Formulir dikirim dengan field kosong (seen, test kedua) | Isi field sebelum Anda menekan tombol |
| Captcha refused: timeout-or-duplicate | Mock melihat token itu untuk kedua kalinya (seen) | Minta token baru untuk setiap pengiriman formulir |
| Deprecated: curl_close() | Teks lengkapnya adalah Function curl_close() is deprecated since 8.5, as it has no effect since PHP 8.0. SDK masih memanggilnya. Laravel mengirimnya ke log channel di LOG_DEPRECATIONS_CHANNEL, null di skeleton, jadi tidak ada yang tercetak. Dengan channel diatur ke single, saya menghitung dua entri untuk satu pemecahan (seen) | Biarkan saja, atau saring, sampai SDK menghapus panggilan itu |
Menjalankan CapSkip di mesin lain
Test suite Dusk tidak harus berjalan di PC yang menjadi host CapSkip. Alihkan CapSkip ke Server mode, masukkan alamat mesin itu di CAPSKIP_HOST pada .env.dusk.local, dan tidak ada hal lain di helper yang berubah. Jika API Key Validation aktif, tambahkan CAPSKIP_API_KEY dengan kunci Anda, yang diteruskan helper sebagai apiKey. CapSkip membuka port-nya untuk semua alamat saat Server mode dimulai, jadi untuk membatasinya hanya ke mesin yang Anda harapkan, tambahkan aturan blokir Windows Firewall untuk yang lain. Solver-nya tetap berjalan di mesin Windows Anda sendiri.
FAQ
Apakah test aplikasi saya sendiri perlu memecahkan CAPTCHA-nya?
Biasanya tidak. Jika aplikasinya milik Anda, matikan pemeriksaannya atau palsukan verifikasinya di lingkungan Dusk. Panduan ini untuk halaman yang verifikasinya tidak bisa Anda ubah, seperti situs staging yang dikelola orang lain.
Apakah helper yang sama berfungsi untuk reCAPTCHA atau MTCaptcha?
SDK memiliki recaptcha() dan mtcaptcha() dengan bentuk yang sama, tetapi nama field-nya berbeda dan saya hanya menjalankan Turnstile. Panduan Symfony Panther menunjukkan reCAPTCHA di skrip browser PHP.
Sebaiknya saya memakai Pest browser testing, bukan Dusk?
Dokumentasi Dusk kini merekomendasikan Pest 4 untuk test browser di proyek baru. Panggilan CapSkip adalah PHP biasa, jadi ide yang sama seharusnya bisa dipakai, tetapi saya hanya menjalankan Dusk.
Apakah ini juga untuk queue job?
Tidak. Job memiliki batas worker sendiri, dan panduan queue Laravel membahasnya. Test Dusk adalah proses command line, jadi batas yang berlaku di sini adalah timeout SDK.
Langkah CAPTCHA di Laravel Dusk pada dasarnya empat gerakan: tunggu field tersembunyi, baca sitekey, minta token tepat sebelum Anda membutuhkannya dan tuliskan dengan script(). Untuk pemecah captcha tanpa biaya per token, CapSkip berjalan di PC Anda sendiri, jadi proses yang gagal hanya berarti satu kali menjalankan test lagi. Lihat halaman pemecah Cloudflare Turnstile untuk widget-nya sendiri, lalu panduan Turnstile PHP untuk panggilan yang sama tanpa browser, dan halaman pemecah CAPTCHA PHP untuk jenis lainnya.
