Laravel Dusk CAPTCHA: Tarayıcı Testinde Turnstile Geçme

laravel dusk captcha - Laravel Dusk CAPTCHA: Pass Turnstile in a Browser Test

Bu kılavuz, bir Laravel Dusk CAPTCHA’sının nasıl geçileceğini gösterir. Yani uygulamanıza CAPTCHA eklemeyi değil, başkasının widget’ından geçmesi gereken bir testi anlatır. Bir Dusk testi Cloudflare Turnstile widget’ı olan bir sayfaya ulaştığında test sitekey’i okuyabilir, PHP SDK ile CapSkip’ten bir token isteyebilir, onu $browser->script() ile widget’ın gizli alanına yazabilir ve gerçek gönder düğmesine basabilir. CapSkip kendi Windows PC’nizde çalışır, bu yüzden bir token için çözüm başına ücret ödemezsiniz.

Neye ihtiyacınız var

  • Güncel Laravel 13 serisi için PHP 8.3 veya daha yenisi (framework paketi ^8.3 ister), Laravel 12 için ise PHP 8.2 (^8.2 ister). Kendinizinkini php -v ile kontrol edin, gerekirse windows.php.net adresinden daha yeni bir derleme alın. Dusk 8.8.0 ve kurduğu php-webdriver paketi zip eklentisini de ister. php.ini içinde curl, openssl, mbstring, fileinfo, zip, pdo_sqlite, sqlite3 ve intl eklentilerini açtım. Laravel 12.72.0 ile 8.2.29’u, Laravel 13.42.0 ile 8.3.28, 8.4.15 ve 8.5.0’ı çalıştırdım.
  • Google Chrome. Benimki Windows 11’de 157.0.8103.50 sürümünü bildirdi ve Dusk, 1. Adım’da onun için bir ChromeDriver kurar.
  • Windows PC’nizde çalışan CapSkip ve capskip/capskip paketi 1.7.0 (benim çalıştırdığım sürüm). Kurulum kılavuzunun bağlantı ayarları bölümünde Local mode ile Server mode arasında seçim yaparsınız. Local mode yalnızca o PC için 127.0.0.1 adresinde yanıt verir, Server mode ise ağ adresinizde veya genel IP’nizde yanıt verir.
  • Standart bir Turnstile widget’ı taşıyan bir sayfa: cf-turnstile sınıfına ve data-sitekey özniteliğine sahip bir div. Cloudflare belgeleri bunu, widget’ın forma görünmez bir cf-turnstile-response alanı eklemesini sağlayan işaretleme olarak tanımlar.

Aşağıdaki her şey iki mock’a karşı çalıştı: biri CapSkip yerine, biri Cloudflare siteverify denetimi yerine geçiyordu. Test edilen sayfa da bir kayıt formu olan, kendi yazdığım küçük bir Laravel uygulamasıydı. Bu PC’deki gerçek CapSkip uygulaması hiçbir görev almadı, bu yüzden gerçek bir Turnstile çözüm süresi ölçmedim ve hiçbir gerçek Cloudflare sayfası bu koddan bir token kabul etmedi. Otomatik Chrome’daki gerçek bir Cloudflare widget’ının enjekte edilen değeri yerinde bırakıp bırakmadığını da test etmedim.

1. Adım: Dusk, ChromeDriver ve CapSkip ayarlarını kurun

Laravel Dusk belgeleri şu kurulumu anlatır: Chrome ve laravel/dusk paketi, ardından tests/Browser klasörünü oluşturan ve bir ChromeDriver indiren dusk:install komutu. CapSkip de geliştirme bağımlılığı olarak eklenir, çünkü onu yalnızca testler çağırır.

# PowerShell, in the root folder of your Laravel project
composer require --dev laravel/dusk capskip/capskip
php artisan dusk:install

php.ini dosyasında sertifika dosyası belirtilmeyen Windows PHP derlemelerimde ilk dusk:install iskeleti oluşturdu, sonra ChromeDriver indirme listesini alırken SSL sertifika sorunu olan cURL error 60 ile başarısız oldu. Aynı hata dusk:chrome-driver komutunda detect seçeneğiyle de geldi. php.ini dosyanızı bulmak için php -i çalıştırıp Loaded Configuration File satırına bakın, curl.se/docs/caextract.html adresinden cacert.pem dosyasını indirin, C:\php\cacert.pem olarak kaydedin ve bu iki satırı o php.ini dosyasına ekleyin. Ardından detect seçeneği, Chrome 157 sürümüm için ChromeDriver 157.0.8103.78 sürümünü indirdi.

; 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

Oluşturulan tests/DuskTestCase.php, ChromeDriver’ı sizin yerinize 9515 numaralı portta başlatır ve DUSK_HEADLESS_DISABLED ortam değişkeni ayarlanmadıkça Chrome’u headless çalıştırır. Kurulu kaynak kodu bunu gösteriyor. 8.3.28 ve 8.5.0 üzerinde aşağıdaki testleri önce görünür pencereyle, sonra headless olarak çalıştırdım ve iki mod da geçti.

Dusk’a CapSkip’in nerede olduğunu söyleyin

Dusk, yerel ortamdan başlattığınızda .env.dusk.local adlı bir dosyayı okur. Belgelere göre .env dosyanızı yedekler, çalıştırma boyunca Dusk dosyasını .env olarak yeniden adlandırır ve sonunda aslını geri koyar. Benim çalıştırmalarımda .env sağlama toplamı öncesinde ve sonrasında aynıydı ve geride .env.backup dosyası kalmadı.

Bu değişim yalnızca testlerinizi çalıştıran sürece ulaşır. Dusk, APP_URL adresindeki bir tarayıcıyı yönetir ve uygulamanızı başlatmaz: Dusk belgelerindeki CI örnekleri yanında php artisan serve çalıştırır. Bu yüzden uygulamayı kendiniz sunun ve APP_URL değerini tarayıcının ziyaret edeceği adresle aynı yapın. .env içinde hiç CapSkip ayarı yokken bile mock her görevi aldı, yani test süreci .env.dusk.local dosyasını okudu.

# 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. Adım: widget’ı çözen bir yardımcı

Turnstile’ı reCAPTCHA ve MTCaptcha yerine üç nedenle seçtim. Widget düz bir div olduğu için Dusk, data-sitekey değerini attribute() ile okuyabilir ve hiçbir JavaScript ayrıştırılmaz. turnstile(sitekey, url, options) SDK çağrısı, testin zaten elinde olan iki değeri alır. Cloudflare ise hem alan adını, cf-turnstile-response, hem de sunucunun onun üzerinde çalıştırdığı denetimi belgeler.

Laravel’de henüz olmayan tests/Concerns klasörünü oluşturun ve bu trait’i oraya SolvesTurnstile.php olarak kaydedin. İçindeki dört ayrıntı çalıştırmalardan çıktı.

<?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'];
    }
}

Birincisi, waitUntilPresent ile bekleyin. Dusk kaynağına göre waitFor bir öğe görüntülenene kadar bekler ve gizli bir input hiçbir zaman görüntülenmez: benim çalıştırmamda alan sayfada zaten varken, 3 saniyelik açık sınırla waitFor 3.19 saniye sonra Waited 3 seconds for selector yazan bir WebDriver TimeoutException ile, varsayılan sınırla ise 5.17 saniye sonra Waited 5 seconds for selector ile bitti. İkincisi, sayfa adresi CapSkip’e tarayıcının geçerli URL’si olarak gider. Mock sitem, token’ın arkasındaki hostname değerini kendi hostname değeriyle karşılaştırıyor ve 127.0.0.1 üzerinde sunulan bir site için localhost adına gönderilen görev, hostname mesajıyla reddedildi. Bu kural benim, ama siteverify belgeleri yanıtta hostname alanını listeler, bu yüzden gerçek bir site de aynı karşılaştırmayı yapabilir.

Üçüncüsü, yardımcı data-action ve data-cdata değerlerini action ve data seçenekleri olarak iletir. Bu iki değerin kaynağı olarak bu adları CapSkip API belgeleri gösterir. Widget’ım data-action taşıyordu ve mock, görevde action=signup kaydetti. Dördüncüsü, eksik sitekey erken hata verir: attribute() olmayan bir öznitelik için null döndürür ve SDK, 1. bağımsız değişkenin string türünde olması gerektiğini söyleyen bir TypeError ile yanıt verdi. Widget’ını turnstile.render ile oluşturan bir sayfada hiç data-sitekey olmayabilir. O durumda sitekey o çağrıdan gelmelidir.

Token, json_encode içinden iki kez geçer, bu yüzden içindeki hiçbir karakter JavaScript string’ini bozamaz. Daha kısa biçim, Dusk’ın value() metodudur; o da executeScript üzerinden aynı şekilde yazar. Gizli bir input’u da doldurduğunu doğruladım.

Sonuç bir userAgent da taşıyabilir. Turnstile PHP rehberi, bunu challenge sayfalarında zorunlu sayar. Dusk altındaki Chrome kendi dizesini bildirir (burada Chrome/157.0.0.0), mock’um ise bir Chrome/140 dizesi bildirdi. Siteniz bunları karşılaştırıyorsa şunu yardımcıya ekleyin.

// 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 üzerinde mock’a karşı, o çağrıdan sonra ziyaret edilen bir sayfa, sunucuda ve navigator.userAgent içinde Chrome/140 dizesini gösterdi. Gerçek bir sitenin bu eşleşmeye önem verip vermediğini test etmedim.

3. Adım: testi yazın ve çalıştırın

Test edilen sayfa

Testler şu sözleşmeyi bekler: /signup yolunda bir route, username adlı bir metin input’u, cf-turnstile sınıfına, bir data-sitekey’e ve bir data-action’a sahip bir div, Create account etiketli bir düğme, Welcome ve adı gösteren /welcome sayfasına bir yönlendirme ve alan boşken The cf-turnstile-response field is required. doğrulama mesajı. Böyle bir sayfanız yoksa routes/web.php dosyasını değiştirin ve görünümü resources/views/signup.blade.php olarak kaydedin.

<?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>

Bu örnek yalnızca alanın var olduğunu denetler. Aşağıdaki sonuç tablosu, token’ı mock siteverify’a da gönderen daha kapsamlı bir sayfa sürümünden geldi.

İlk test geçiştir. İkincisi, sayfanın token olmadan gönderilen bir formu gerçekten reddettiğini gösterir. İkisini de tests/Browser/SignupCaptchaTest.php dosyasına kaydedin.

<?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');
        });
    }
}

Sayfanız farklıysa yolu, alan adlarını, düğme etiketini ve metinleri değiştirin. Sonra iki PowerShell istemi kullanın: biri uygulama, biri testler için.

# 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'

Mock sitem alanı zorunlu olarak doğrular, mock siteverify’a gönderir, bir token’ı yalnızca bir kez kabul eder ve hostname değerini karşılaştırır. Bunlar benim kurallarım, Cloudflare’ın değil. Aşağıdaki her satır mock CapSkip, Chrome 157.0.8103.50 ve Windows 11 üzerinde ChromeDriver 157.0.8103.78 kullandı ve süreler PHPUnit çıktısındaki Duration satırından alındı.

PHPLaravelChrome penceresiSonuç
8.2.2912.72.0görünür2 geçti, 5.20 saniye
8.3.2813.42.0görünür, sonra headless2 geçti, 4.96 ve 5.68 saniye
8.4.1513.42.0görünür2 geçti, 5.27 saniye
8.5.013.42.0görünür, sonra headless2 geçti, 4.46 ve 4.33 saniye

Zaman sınırı ve SDK timeout değeri

PHP’nin max_execution_time ayarı bir Dusk çalıştırmasını durdurmaz. php.ini içinde 30 yaptım ve testin içindeki bir yoklama 8.2.29, 8.3.28, 8.4.15 ve 8.5.0 üzerinde 0 okudu, çünkü php artisan dusk, PHPUnit’i sınırın kapalı olduğu komut satırında başlatır.

Turnstile için PHP SDK 1.7.0, çağrı bir timeout seçeneği vermedikçe defaultTimeout değerine, yani 120 saniyeye kadar bekler. Trait, 60 vererek bunu yapar. SDK, gönderimden 0, 0.25, 0.75, 1.75 ve 3.75 saniye sonra, ardından 7.75 saniyede ve her 5 saniyede bir sonucu okur ve son tarihi yalnızca bir sonraki okuma zamanı geldiğinde denetler. Bu yüzden çağrı, verdiğiniz sayıdan daha geç biter.

Mock CapSkip, hiç bitirmiyorÖlçülen
timeout 5, bir Dusk testi içinde, PHP 8.3.287.83 saniye sonra TimeoutException
timeout 60, düz komut satırı, PHP 8.3.2862.97 saniye sonra TimeoutException, son okuma 57.93 saniyede
Token 45 saniye sonra hazır, timeout 60, Dusk testiToken 48.31 saniye sonra döndü, form kabul edildi

Son satır, tarayıcının bekleyebildiğini de gösterir: Chrome ve ChromeDriver o 48 saniye boyunca boşta durdu ve sonraki komut çalıştı. Daha uzun bir süreyi test etmedim. Cloudflare belgeleri bir Turnstile token’ına beş dakikalık ömür ve tek kullanım verir, bu yüzden onu sayfa yüklendikten sonra isteyin ve hemen doldurun. İkinci kez gönderdiğim bir token’ı mock’um, belgelerin bu durum için andığı kod olan timeout-or-duplicate ile reddetti.

Yaygın hatalar

Bu tabloda görüldü, hatayı mock’lara karşı kendim ürettim demektir.

HataNedenDüzeltme
dusk:install sırasında cURL error 60php.ini hiçbir CA paketi belirtmiyor (görüldü)php.ini içinde curl.cainfo ayarlayın, sonra dusk:chrome-driver komutunu detect seçeneğiyle çalıştırın
NetworkException: Failed to connect to 127.0.0.1 port 8080 after about 2000 ms: Couldn’t connect to serverCapSkip adresinde ve portunda hiçbir şey dinlemiyor. Yaklaşık 2 saniye sonra başarısız oldu (görüldü, kapalı portta 2.02 sn)CapSkip’i başlatın ve .env.dusk.local içindeki CAPSKIP_HOST ile CAPSKIP_PORT değerlerini onun bağlantı ayarlarıyla karşılaştırın
TimeoutException: timeout 60 exceededSon tarihe kadar token gelmedi (görüldü)CapSkip monitörünü kontrol edin, sonra timeout seçeneğini artırın
ERROR_CAPTCHA_UNSOLVABLE içeren ApiExceptionMock yanıt verdi, çözüm başarısız oldu (görüldü)Testi yeniden çalıştırın, çünkü yeni bir görev yeni bir denemedir
ValidationException: Unsupported parameters for TurnstileTurnstile’ın almadığı bir seçenek, örneğin invisible (görüldü)Bu seçeneği turnstile çağrısından kaldırın
TypeError: Argument #1 ($sitekey) must be of type stringWidget’ta data-sitekey özniteliği yok (görüldü)Sitekey’i sayfanın turnstile.render çağrısından okuyun
Waited 5 seconds for selectorGizli alanda varsayılan sınırla waitFor (görüldü)waitUntilPresent kullanın
The cf-turnstile-response field is required.Form, alan boşken gönderildi (görüldü, ikinci test)Düğmeye basmadan önce alanı doldurun
Captcha refused: timeout-or-duplicateMock token’ı ikinci kez gördü (görüldü)Her form gönderimi için yeni bir token isteyin
Deprecated: curl_close()Tam metin şudur: Function curl_close() is deprecated since 8.5, as it has no effect since PHP 8.0. SDK bu çağrıyı hâlâ yapar. Laravel bunu, iskelette null olan LOG_DEPRECATIONS_CHANNEL içindeki log kanalına gönderir, bu yüzden hiçbir şey yazdırılmadı. Kanalı single yapınca tek bir çözüm için iki kayıt saydım (görüldü)SDK bu çağrıyı bırakana kadar olduğu gibi bırakın ya da filtreleyin

CapSkip’i başka bir makinede çalıştırmak

Bir Dusk paketinin CapSkip’i barındıran PC’de çalışması gerekmez. CapSkip’i Server mode’a geçirin, o makinenin adresini .env.dusk.local içindeki CAPSKIP_HOST değerine yazın; yardımcıda başka hiçbir şey değişmez. API Key Validation açıksa anahtarınızla CAPSKIP_API_KEY ekleyin, yardımcı bunu apiKey olarak geçirir. CapSkip, Server mode başladığında portunu her adrese açar, bu yüzden erişimi beklediğiniz makinelerle sınırlamak için diğerleri için bir Windows Firewall engelleme kuralı ekleyin. Çözücü yine kendi Windows makinenizde çalışır.

FAQ

Kendi uygulamamın testleri CAPTCHA’sını çözmeli mi?

Genellikle hayır. Uygulama sizinse Dusk ortamında denetimi kapatın veya doğrulamayı taklit edin. Bu kılavuz, doğrulamasını değiştiremeyeceğiniz sayfalar içindir, örneğin başkasının işlettiği bir staging sitesi.

Aynı yardımcı reCAPTCHA veya MTCaptcha için de çalışır mı?

SDK’da aynı biçimde recaptcha() ve mtcaptcha() var, ama alan adları farklı ve ben yalnızca Turnstile çalıştırdım. Symfony Panther rehberi PHP tarayıcı betiğinde reCAPTCHA’yı gösterir.

Dusk yerine Pest browser testing kullanmalı mıyım?

Dusk belgeleri artık yeni projelerde tarayıcı testleri için Pest 4’ü öneriyor. CapSkip çağrısı düz PHP, bu yüzden aynı fikir geçmeli, ama ben yalnızca Dusk çalıştırdım.

Bu queue job’ları için de geçerli mi?

Hayır. Bir job’ın kendi worker sınırları vardır, bunları Laravel kuyruk rehberi anlatır. Bir Dusk testi komut satırı sürecidir, bu yüzden burada geçerli olan sınır SDK timeout değeriydi.

Bir Laravel Dusk CAPTCHA adımı dört hamleye iner: gizli alanı bekleyin, sitekey’i okuyun, token’ı tam ihtiyaç duymadan önce isteyin ve script() ile yazın. Token başına ücret almayan bir captcha çözücü için CapSkip kendi PC’nizde çalışır, bu yüzden başarısız bir çalıştırma yalnızca bir test çalıştırması daha demektir. Cloudflare Turnstile çözücü sayfası widget’ın kendisini anlatır, Turnstile PHP rehberi aynı çağrıyı tarayıcısız gösterir, PHP CAPTCHA çözücü sayfası ise diğer türleri listeler.