Laravel Dusk CAPTCHA: ब्राउज़र टेस्ट में Turnstile पास करें

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

यह गाइड बताती है कि Laravel Dusk CAPTCHA को कैसे पास किया जाए, यानी ऐसा टेस्ट जिसे किसी और के widget से गुज़रना है, न कि अपने ऐप में कैप्चा जोड़ना। जब Dusk टेस्ट किसी ऐसे पेज पर पहुँचता है जिसमें Cloudflare Turnstile widget है, तो टेस्ट sitekey पढ़ सकता है, PHP SDK से CapSkip से token माँग सकता है, उसे $browser->script() से widget के छिपे हुए फ़ील्ड में लिख सकता है और असली submit बटन दबा सकता है। CapSkip आपके अपने Windows PC पर चलता है, इसलिए हर token पर कोई प्रति-हल शुल्क नहीं लगता।

आपको क्या चाहिए

  • मौजूदा Laravel 13 लाइन के लिए PHP 8.3 या नया, जिसका framework package ^8.3 माँगता है, या Laravel 12 के लिए PHP 8.2, जो ^8.2 माँगता है। अपना वर्शन php -v से जाँचें, और ज़रूरत हो तो windows.php.net से नया बिल्ड लें। Dusk 8.8.0 और उसके साथ इंस्टॉल होने वाले php-webdriver package को zip extension भी चाहिए। php.ini में मैंने curl, openssl, mbstring, fileinfo, zip, pdo_sqlite, sqlite3 और intl चालू किए। मैंने Laravel 12.72.0 के साथ 8.2.29 चलाया, और Laravel 13.42.0 के साथ 8.3.28, 8.4.15 और 8.5.0 चलाए।
  • Google Chrome। मेरे यहाँ Windows 11 पर 157.0.8103.50 दिखा, और Dusk चरण 1 में उसके लिए ChromeDriver इंस्टॉल करता है।
  • आपके Windows PC पर चलता CapSkip, और capskip/capskip package 1.7.0 पर, जो वह वर्शन है जो मैंने चलाया। सेटअप गाइड की कनेक्शन सेटिंग्स में Local mode, जो सिर्फ़ उसी PC के लिए 127.0.0.1 पर जवाब देता है, और Server mode, जो आपके network address या public IP पर जवाब देता है, में से एक चुनना होता है।
  • ऐसा पेज जिसमें मानक Turnstile widget हो: cf-turnstile क्लास और data-sitekey attribute वाला एक div, जिसे Cloudflare docs उस markup के रूप में बताते हैं जिससे widget फ़ॉर्म में एक अदृश्य cf-turnstile-response फ़ील्ड जोड़ देता है।

नीचे सब कुछ दो mocks के सामने चला, एक CapSkip की जगह और एक Cloudflare की siteverify जाँच की जगह, और जिस पेज का टेस्ट हुआ वह साइन-अप फ़ॉर्म वाला मेरा बनाया छोटा Laravel ऐप था। इस PC के असली CapSkip ऐप को कोई task नहीं मिला, इसलिए मैंने असली Turnstile solve का समय नहीं मापा, और किसी असली Cloudflare पेज ने इस कोड का token स्वीकार नहीं किया है। मैंने यह भी नहीं जाँचा कि automated Chrome में असली Cloudflare widget डाला गया मान वहीं रहने देता है या नहीं।

चरण 1: Dusk, ChromeDriver और CapSkip की सेटिंग्स इंस्टॉल करें

Laravel Dusk दस्तावेज़ Chrome और laravel/dusk package माँगते हैं, फिर dusk:install command, जो tests/Browser बनाता है और ChromeDriver डाउनलोड करता है। CapSkip भी development dependency के रूप में जोड़ा जाता है, क्योंकि उसे सिर्फ़ टेस्ट बुलाते हैं।

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

मेरे Windows PHP बिल्ड्स पर, जिनके php.ini में कोई certificate फ़ाइल नहीं थी, पहले dusk:install ने scaffold बनाया और फिर ChromeDriver की डाउनलोड सूची लाते समय cURL error 60, यानी SSL certificate की समस्या, के साथ फ़ेल हो गया। यही error detect option के साथ dusk:chrome-driver से भी आई। php -i चलाकर Loaded Configuration File पंक्ति से अपनी php.ini ढूँढें, curl.se/docs/caextract.html से cacert.pem डाउनलोड करें, उसे C:\php\cacert.pem के रूप में सेव करें और उसी php.ini में ये दो पंक्तियाँ जोड़ें। उसके बाद detect option ने मेरे 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 आपके लिए ChromeDriver को port 9515 पर शुरू करती है और Chrome को headless चलाती है, जब तक environment variable DUSK_HEADLESS_DISABLED सेट न हो, जैसा इंस्टॉल किया गया source दिखाता है। 8.3.28 और 8.5.0 पर मैंने नीचे के टेस्ट एक बार दिखने वाली विंडो के साथ और एक बार headless चलाए, और दोनों मोड पास हुए।

Dusk को बताएँ कि CapSkip कहाँ है

Dusk लोकल environment से शुरू करने पर .env.dusk.local नाम की फ़ाइल पढ़ता है। docs के अनुसार वह आपकी .env का बैकअप लेता है, रन के लिए Dusk वाली फ़ाइल का नाम .env कर देता है और बाद में असली फ़ाइल लौटा देता है। मेरे रन में .env का checksum पहले और बाद में एक जैसा रहा, और कोई .env.backup फ़ाइल नहीं बची।

यह अदला-बदली सिर्फ़ उस process तक पहुँचती है जो आपके टेस्ट चलाता है। Dusk ब्राउज़र को APP_URL पर चलाता है और आपका ऐप शुरू नहीं करता: Dusk docs के CI उदाहरण उसके साथ php artisan serve चलाते हैं। इसलिए ऐप खुद चलाएँ, और APP_URL को उसी address से मिलाएँ जिस पर ब्राउज़र जाएगा। .env में CapSkip की कोई सेटिंग न होने पर भी mock को हर task मिला, यानी टेस्ट process ने .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: widget को हल करने वाला helper

मैंने reCAPTCHA और MTCaptcha के बजाय Turnstile तीन कारणों से चुना। widget एक सादा div है, इसलिए Dusk attribute() से data-sitekey पढ़ सकता है और कोई JavaScript parse नहीं करनी पड़ती। SDK का call turnstile(sitekey, url, options) वही दो मान लेता है जो टेस्ट के पास पहले से हैं। और Cloudflare फ़ील्ड का नाम, cf-turnstile-response, और वह जाँच, जो server उस पर चलाता है, दोनों documented रखता है।

tests/Concerns फ़ोल्डर बनाएँ, जो Laravel में अभी नहीं है, और यह 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 source कहता है कि waitFor तब तक रुकता है जब तक element displayed न हो, और छिपा हुआ input कभी displayed नहीं होता: मेरे रन में 3 सेकंड की साफ़ सीमा वाला waitFor 3.19 सेकंड बाद WebDriver TimeoutException के साथ खत्म हुआ, जिसमें Waited 3 seconds for selector लिखा था, और default सीमा के साथ वह 5.17 सेकंड बाद Waited 5 seconds for selector के साथ खत्म हुआ, जबकि फ़ील्ड पेज में पहले से मौजूद था। दूसरा, पेज का address CapSkip को ब्राउज़र के मौजूदा URL के रूप में जाता है। मेरी mock साइट token के पीछे के hostname की तुलना अपने hostname से करती है, और 127.0.0.1 पर चल रही साइट के लिए localhost बताकर भेजा गया task hostname संदेश के साथ ठुकरा दिया गया। वह नियम मेरा है, फिर भी siteverify दस्तावेज़ response में hostname सूचीबद्ध करते हैं, इसलिए असली साइट भी यही तुलना कर सकती है।

तीसरा, helper data-action और data-cdata को action और data options के रूप में आगे भेजता है, जिन्हें CapSkip API दस्तावेज़ उन दो मानों के स्रोत के रूप में नाम से बताते हैं। मेरे widget में data-action था, और mock ने task पर action=signup लॉग किया। चौथा, sitekey न होने पर जल्दी फ़ेल होता है: attribute() किसी अनुपस्थित attribute के लिए null लौटाता है, और SDK ने TypeError के साथ जवाब दिया कि argument 1 string होना चाहिए। जो पेज अपना widget turnstile.render से बनाता है उसमें data-sitekey बिल्कुल न हो सकता है, और तब sitekey उसी call से लेनी होगी।

token दो बार json_encode से गुज़रता है, इसलिए उसका कोई अक्षर JavaScript string को तोड़ नहीं सकता। छोटा रूप Dusk का value() मेथड है, जो executeScript के ज़रिए उसी तरह लिखता है। मैंने पुष्टि की कि वह छिपे हुए input को भी भर देता है।

नतीजे में userAgent भी आ सकता है, जिसे Turnstile PHP गाइड challenge पेजों के लिए ज़रूरी मानती है। Dusk के तहत Chrome अपनी string बताता है, यहाँ Chrome/157.0.0.0, और मेरे mock ने Chrome/140 वाली string बताई। अगर आपकी साइट इनकी तुलना करती है, तो 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']],
    ]);
}

8.3.28 पर mock के सामने, उस call के बाद खोले गए पेज ने server और navigator.userAgent को Chrome/140 string दिखाई। मैंने यह नहीं जाँचा कि असली साइट को मेल की परवाह है या नहीं।

चरण 3: टेस्ट लिखें और चलाएँ

जिस पेज का टेस्ट होगा

टेस्ट इस अनुबंध की उम्मीद करते हैं: /signup पर एक route, username नाम का टेक्स्ट input, cf-turnstile क्लास वाला div, एक data-sitekey और एक data-action, Create account लिखा बटन, /welcome पर redirect जो Welcome और नाम दिखाए, और फ़ील्ड खाली होने पर validation संदेश The cf-turnstile-response field is required. अगर आपके पास ऐसा पेज नहीं है, तो routes/web.php बदल दें और view को 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 को मेरे mock 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');
        });
    }
}

अगर आपका पेज अलग है, तो path, फ़ील्ड के नाम, बटन का लेबल और टेक्स्ट बदलें। फिर दो PowerShell prompts इस्तेमाल करें, एक ऐप के लिए और एक टेस्ट के लिए।

# 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 साइट फ़ील्ड को ज़रूरी मानकर validate करती है, उसे mock siteverify को भेजती है, token को एक बार स्वीकार करती है और hostname की तुलना करती है। ये मेरे नियम हैं, Cloudflare के नहीं। नीचे की हर पंक्ति में mock CapSkip, Chrome 157.0.8103.50 और Windows 11 पर ChromeDriver 157.0.8103.78 इस्तेमाल हुए, और PHPUnit आउटपुट की Duration पंक्ति ली गई।

PHPLaravelChrome विंडोनतीजा
8.2.2912.72.0दिखने वाली2 passed, 5.20 सेकंड
8.3.2813.42.0दिखने वाली, फिर headless2 passed, 4.96 और 5.68 सेकंड
8.4.1513.42.0दिखने वाली2 passed, 5.27 सेकंड
8.5.013.42.0दिखने वाली, फिर headless2 passed, 4.46 और 4.33 सेकंड

समय सीमा और SDK timeout

PHP की सेटिंग max_execution_time Dusk रन को नहीं रोकती। मैंने उसे php.ini में 30 पर रखा, और टेस्ट के भीतर एक probe ने 8.2.29, 8.3.28, 8.4.15 और 8.5.0 पर 0 पढ़ा, क्योंकि php artisan dusk PHPUnit को command line पर शुरू करता है, जहाँ यह सीमा बंद रहती है।

Turnstile के लिए PHP SDK 1.7.0 अपने defaultTimeout, यानी 120 सेकंड, तक इंतज़ार करता है, जब तक call timeout option न दे, जैसा trait 60 के साथ करता है। SDK submit के 0, 0.25, 0.75, 1.75 और 3.75 सेकंड बाद नतीजा पढ़ता है, फिर 7.75 पर और उसके बाद हर 5 सेकंड पर, और deadline तभी जाँचता है जब अगली पढ़ाई का समय आता है। इसलिए call आपके दिए नंबर से देर में खत्म होता है।

Mock CapSkip, कभी पूरा नहीं करतामापा गया
timeout 5, Dusk टेस्ट के भीतर, PHP 8.3.28TimeoutException 7.83 सेकंड बाद
timeout 60, सादी command line, PHP 8.3.28TimeoutException 62.97 सेकंड बाद, आखिरी पढ़ाई 57.93 पर
Token 45 सेकंड बाद तैयार, timeout 60, Dusk टेस्टToken 48.31 सेकंड बाद लौटा, फ़ॉर्म स्वीकार हुआ

आखिरी पंक्ति यह भी दिखाती है कि ब्राउज़र इंतज़ार कर सकता है: Chrome और ChromeDriver उन 48 सेकंड तक खाली बैठे रहे और अगला command चला। मैंने इससे लंबा कुछ नहीं आज़माया। Cloudflare docs Turnstile token को पाँच मिनट की उम्र और एक बार का उपयोग देते हैं, इसलिए उसे पेज लोड होने के बाद माँगें और तुरंत भर दें। जो token मैंने दूसरी बार भेजा, उसे मेरे mock ने timeout-or-duplicate के साथ ठुकरा दिया, यही कोड docs इस स्थिति के लिए बताते हैं।

आम errors

इस तालिका में seen का मतलब है कि मैंने वह error mocks के सामने खुद पैदा की।

त्रुटिकारणफिक्स
dusk:install के दौरान cURL error 60php.ini में कोई CA bundle नहीं है (seen)php.ini में curl.cainfo सेट करें, फिर detect option के साथ dusk:chrome-driver चलाएँ
NetworkException: Failed to connect to 127.0.0.1 port 8080 after about 2000 ms: Couldn’t connect to serverCapSkip के host और port पर कुछ नहीं सुन रहा। यह लगभग 2 सेकंड बाद फ़ेल हुआ (seen, बंद port पर 2.02 s)CapSkip शुरू करें, और .env.dusk.local में CAPSKIP_HOST और CAPSKIP_PORT को उसकी connection सेटिंग्स से मिलाएँ
TimeoutException: timeout 60 exceededdeadline से पहले कोई token नहीं मिला (seen)CapSkip monitor देखें, फिर timeout option बढ़ाएँ
ERROR_CAPTCHA_UNSOLVABLE वाला ApiExceptionmock ने जवाब दिया; solve फ़ेल रहा (seen)टेस्ट दोबारा चलाएँ, क्योंकि नया task एक नई कोशिश है
ValidationException: Unsupported parameters for Turnstileऐसा option जो Turnstile नहीं लेता, जैसे invisible (seen)उस option को turnstile call से हटा दें
TypeError: Argument #1 ($sitekey) must be of type stringwidget में data-sitekey attribute नहीं है (seen)sitekey को पेज के turnstile.render call से पढ़ें
Waited 5 seconds for selectorछिपे हुए फ़ील्ड पर default सीमा वाला waitFor (seen)waitUntilPresent इस्तेमाल करें
The cf-turnstile-response field is required.फ़ॉर्म खाली फ़ील्ड के साथ भेजा गया (seen, दूसरा टेस्ट)बटन दबाने से पहले फ़ील्ड भरें
Captcha refused: timeout-or-duplicatemock ने token को दूसरी बार देखा (seen)हर फ़ॉर्म submission के लिए नया 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 में दिए log channel को भेजता है, जो skeleton में null है, इसलिए कुछ छपा नहीं। channel को single करने पर मैंने एक solve के लिए दो entries गिनीं (seen)इसे रहने दें, या filter करें, जब तक SDK यह call हटा न दे

CapSkip को किसी दूसरी मशीन पर चलाना

Dusk suite का उसी PC पर चलना ज़रूरी नहीं जहाँ CapSkip है। CapSkip को Server mode में बदलें, उस मशीन का address .env.dusk.local के CAPSKIP_HOST में डालें, और helper में और कुछ नहीं बदलता। अगर API Key Validation चालू है, तो अपनी key के साथ CAPSKIP_API_KEY जोड़ें, जिसे helper apiKey के रूप में देता है। Server mode शुरू होते ही CapSkip अपना port हर address के लिए खोल देता है, इसलिए उसे सिर्फ़ अपेक्षित मशीनों तक रखने के लिए बाकी के लिए Windows Firewall की block rule जोड़ें। solver फिर भी आपकी अपनी Windows मशीन पर चलता है।

FAQ

क्या मेरे अपने ऐप के टेस्ट को उसका CAPTCHA हल करना चाहिए?

आम तौर पर नहीं। जब ऐप आपका अपना है, तो Dusk environment में जाँच बंद कर दें या verification को नकली बना दें। यह गाइड उन पेजों के लिए है जिनका verification आप बदल नहीं सकते, जैसे किसी और की चलाई staging साइट।

क्या यही helper reCAPTCHA या MTCaptcha के लिए भी चलता है?

SDK में recaptcha() और mtcaptcha() उसी रूप में हैं, लेकिन फ़ील्ड के नाम अलग हैं और मैंने सिर्फ़ Turnstile चलाया। Symfony Panther गाइड PHP ब्राउज़र script में reCAPTCHA दिखाती है।

क्या Dusk की जगह Pest browser testing इस्तेमाल करूँ?

Dusk docs अब नए प्रोजेक्ट्स में ब्राउज़र टेस्ट के लिए Pest 4 सुझाते हैं। CapSkip का call सादा PHP है, इसलिए यही तरीका वहाँ भी चलना चाहिए, पर मैंने सिर्फ़ Dusk चलाया।

क्या यह queue jobs के लिए भी है?

नहीं। किसी job की अपनी worker सीमाएँ होती हैं, जिन्हें Laravel queue गाइड बताती है। Dusk टेस्ट एक command line process है, इसलिए यहाँ लागू होने वाली सीमा SDK timeout थी।

Laravel Dusk CAPTCHA का चरण चार कदमों में सिमट जाता है: छिपे हुए फ़ील्ड का इंतज़ार करें, sitekey पढ़ें, token तब माँगें जब उसकी ज़रूरत हो और उसे script() से लिखें। प्रति token बिना शुल्क वाले कैप्चा सॉल्वर के लिए CapSkip आपके अपने PC पर चलता है, इसलिए फ़ेल हुए रन की कीमत बस एक और टेस्ट रन है। Cloudflare Turnstile सॉल्वर page खुद widget के बारे में बताता है, Turnstile PHP गाइड वही call बिना ब्राउज़र के दिखाती है, और PHP कैप्चा सॉल्वर पेज बाकी प्रकार सूचीबद्ध करता है।