Laravel-Dusk-Captcha: Turnstile in einem Browser-Test bestehen

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

Dieser Leitfaden zeigt, wie Sie ein Laravel-Dusk-Captcha bestehen, also einen Test, der durch das Widget einer fremden Website kommen muss, und nicht, wie Sie eines in Ihre App einbauen. Erreicht ein Dusk-Test eine Seite mit einem Cloudflare-Turnstile-Widget, kann er den Sitekey lesen, mit dem PHP SDK bei CapSkip einen Token anfordern, ihn mit $browser->script() in das versteckte Feld des Widgets schreiben und den echten Absenden-Button drücken. CapSkip läuft auf Ihrem eigenen Windows-PC, daher kostet ein Token keine Gebühr pro Lösung.

Was Sie brauchen

  • PHP 8.3 oder neuer für die aktuelle Laravel-13-Linie, deren Framework-Paket ^8.3 verlangt, oder PHP 8.2 für Laravel 12, das ^8.2 verlangt. Prüfen Sie Ihre Version mit php -v und holen Sie sich bei Bedarf einen neueren Build von windows.php.net. Dusk 8.8.0 und das Paket php-webdriver, das es installiert, brauchen außerdem die Erweiterung zip. In der php.ini habe ich curl, openssl, mbstring, fileinfo, zip, pdo_sqlite, sqlite3 und intl aktiviert. Ich habe 8.2.29 mit Laravel 12.72.0 sowie 8.3.28, 8.4.15 und 8.5.0 mit Laravel 13.42.0 getestet.
  • Google Chrome. Meiner meldete 157.0.8103.50 unter Windows 11, und Dusk installiert in Schritt 1 den passenden ChromeDriver dazu.
  • CapSkip läuft auf Ihrem Windows-PC, und das Paket capskip/capskip ist in Version 1.7.0 installiert, der Version, die ich getestet habe. Die Verbindungseinstellungen in der Einrichtungsanleitung legen fest, ob Local mode gilt, der nur für diesen PC unter 127.0.0.1 antwortet, oder Server mode, der unter Ihrer Netzwerkadresse oder öffentlichen IP antwortet.
  • Eine Seite mit einem Standard-Turnstile-Widget: ein div mit der Klasse cf-turnstile und einem Attribut data-sitekey. Laut Cloudflare-Dokumentation sorgt dieses Markup dafür, dass das Widget dem Formular ein unsichtbares Feld cf-turnstile-response hinzufügt.

Alles unten lief gegen zwei Mocks, einen als Ersatz für CapSkip und einen für die Cloudflare-Prüfung siteverify. Die getestete Seite war eine kleine eigene Laravel-App mit einem Registrierungsformular. Die echte CapSkip-App auf diesem PC hat keine Aufgabe erhalten, daher habe ich keine echte Turnstile-Lösungszeit gemessen, und keine echte Cloudflare-Seite hat je einen Token von diesem Code akzeptiert. Ich habe auch nicht getestet, ob ein echtes Cloudflare-Widget in automatisiertem Chrome einen eingesetzten Wert stehen lässt.

Schritt 1: Dusk, ChromeDriver und die CapSkip-Einstellungen installieren

Die Laravel-Dusk-Dokumentation verlangt Chrome und das Paket laravel/dusk, danach den Befehl dusk:install, der tests/Browser anlegt und einen ChromeDriver herunterlädt. CapSkip kommt ebenfalls als Entwicklungsabhängigkeit hinzu, weil nur die Tests es aufrufen.

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

Bei meinen Windows-PHP-Builds, deren php.ini keine Zertifikatsdatei nannte, legte das erste dusk:install das Grundgerüst an und scheiterte dann beim Abrufen der ChromeDriver-Downloadliste mit cURL error 60, einem SSL-Zertifikatsproblem. Denselben Fehler lieferte dusk:chrome-driver mit der Option detect. Führen Sie php -i aus und suchen Sie die Zeile Loaded Configuration File, um Ihre php.ini zu finden. Laden Sie cacert.pem von curl.se/docs/caextract.html herunter, speichern Sie es als C:\php\cacert.pem und fügen Sie diese beiden Zeilen zur php.ini hinzu. Danach holte die Option detect für mein Chrome 157 den 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

Die generierte Datei tests/DuskTestCase.php startet ChromeDriver für Sie auf Port 9515 und führt Chrome headless aus, solange die Umgebungsvariable DUSK_HEADLESS_DISABLED nicht gesetzt ist, wie der installierte Quellcode zeigt. Unter 8.3.28 und 8.5.0 habe ich die folgenden Tests mit sichtbarem Fenster und noch einmal headless ausgeführt, und beide Modi bestanden.

Dusk mitteilen, wo CapSkip läuft

Dusk liest eine Datei namens .env.dusk.local, wenn Sie es aus der lokalen Umgebung starten. Laut Dokumentation sichert es Ihre .env, benennt die Dusk-Datei für den Lauf in .env um und stellt danach das Original wieder her. In meinen Läufen war die Prüfsumme der .env vorher und nachher identisch, und es blieb keine Datei .env.backup zurück.

Dieser Austausch wirkt nur auf den Prozess, der Ihre Tests ausführt. Dusk steuert einen Browser auf APP_URL und startet Ihre App nicht: Die CI-Beispiele in der Dusk-Dokumentation führen daneben php artisan serve aus. Starten Sie sie also selbst und sorgen Sie dafür, dass APP_URL zu der Adresse passt, die der Browser aufruft. Auch ohne CapSkip-Einstellungen in der .env erhielt der Mock jede Aufgabe, also hat der Testprozess die Datei .env.dusk.local gelesen.

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

Schritt 2: ein Helfer, der das Widget löst

Ich habe Turnstile aus drei Gründen gegenüber reCAPTCHA und MTCaptcha gewählt. Das Widget ist ein einfaches div, daher kann Dusk data-sitekey mit attribute() lesen, ohne dass JavaScript geparst werden muss. Der SDK-Aufruf turnstile(sitekey, url, options) nimmt die beiden Werte, die der Test schon hat. Und Cloudflare dokumentiert sowohl den Feldnamen cf-turnstile-response als auch die Prüfung, die ein Server damit durchführt.

Legen Sie den Ordner tests/Concerns an, den Laravel noch nicht hat, und speichern Sie dieses Trait dort als SolvesTurnstile.php. Vier Details darin stammen aus den Läufen.

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

Erstens: Warten Sie mit waitUntilPresent. Laut Dusk-Quellcode wartet waitFor, bis ein Element angezeigt wird, und ein verstecktes Input wird nie angezeigt: In meinem Lauf endete waitFor mit einem ausdrücklichen Limit von 3 Sekunden nach 3,19 Sekunden mit einer WebDriver-TimeoutException mit dem Text Waited 3 seconds for selector, und mit dem Standardlimit endete es nach 5,17 Sekunden mit Waited 5 seconds for selector, obwohl das Feld längst in der Seite war. Zweitens: Die Seitenadresse geht als aktuelle URL des Browsers an CapSkip. Meine Mock-Website vergleicht den Hostnamen hinter dem Token mit ihrem eigenen, und eine Aufgabe für localhost gegen eine Website, die unter 127.0.0.1 läuft, wurde mit einer Hostnamen-Meldung abgelehnt. Diese Regel stammt von mir, aber die siteverify-Dokumentation nennt hostname in der Antwort, sodass auch eine echte Website denselben Vergleich durchführen kann.

Drittens: Der Helfer reicht data-action und data-cdata als die Optionen action und data weiter, die die CapSkip-API-Dokumentation als Quellen dieser beiden Werte nennt. Mein Widget trug data-action, und der Mock protokollierte action=signup bei der Aufgabe. Viertens: Ein fehlender Sitekey führt früh zum Fehler: attribute() gibt für ein fehlendes Attribut null zurück, und das SDK antwortete mit einem TypeError, der besagt, dass Argument 1 vom Typ string sein muss. Eine Seite, die ihr Widget mit turnstile.render erzeugt, hat vielleicht gar kein data-sitekey, und dann muss der Sitekey aus diesem Aufruf kommen.

Der Token läuft doppelt durch json_encode, damit kein Zeichen darin den JavaScript-String sprengen kann. Die kürzere Form ist die Methode value() von Dusk, die auf demselben Weg über executeScript schreibt. Ich habe bestätigt, dass sie auch ein verstecktes Input befüllt.

Das Ergebnis kann außerdem einen userAgent enthalten, den der Turnstile-PHP-Leitfaden auf Challenge-Seiten als erforderlich behandelt. Chrome unter Dusk meldet seinen eigenen String, hier Chrome/157.0.0.0, und mein Mock meldete einen Chrome/140-String. Wenn Ihre Website die beiden vergleicht, fügen Sie dies dem Helfer hinzu.

// 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']],
    ]);
}

Unter 8.3.28 gegen den Mock zeigte eine Seite, die nach diesem Aufruf besucht wurde, dem Server und navigator.userAgent den Chrome/140-String. Ob eine echte Website auf die Übereinstimmung achtet, habe ich nicht getestet.

Schritt 3: den Test schreiben und ausführen

Die getestete Seite

Die Tests erwarten diesen Vertrag: eine Route unter /signup, ein Texteingabefeld namens username, ein div mit der Klasse cf-turnstile, ein data-sitekey und ein data-action, einen Button mit der Beschriftung Create account, eine Weiterleitung nach /welcome, die Welcome und den Namen anzeigt, und die Validierungsmeldung „The cf-turnstile-response field is required.“, wenn das Feld leer ist. Wenn Sie keine solche Seite haben, ersetzen Sie routes/web.php und speichern Sie die View als 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>

Dieses Beispiel prüft nur, ob das Feld vorhanden ist. Die Ergebnistabelle unten stammt von einer ausführlicheren Version der Seite, die den Token außerdem an meinen Mock von siteverify schickte.

Der erste Test ist der erfolgreiche Durchlauf. Der zweite zeigt, dass die Seite ein Formular ohne Token wirklich ablehnt. Speichern Sie beide in 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');
        });
    }
}

Wenn Ihre Seite abweicht, ändern Sie den Pfad, die Feldnamen, die Beschriftung des Buttons und die Texte. Öffnen Sie dann zwei PowerShell-Eingabeaufforderungen, eine für die App und eine für die Tests.

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

Meine Mock-Website validiert das Feld als Pflichtfeld, schickt es an den Mock von siteverify, akzeptiert einen Token nur einmal und vergleicht den Hostnamen. Das sind meine Regeln, nicht die von Cloudflare. Jede Zeile unten verwendete den Mock von CapSkip, Chrome 157.0.8103.50 und ChromeDriver 157.0.8103.78 unter Windows 11, mit der Zeile Duration aus der PHPUnit-Ausgabe.

PHPLaravelChrome-FensterErgebnis
8.2.2912.72.0sichtbar2 bestanden, 5,20 Sekunden
8.3.2813.42.0sichtbar, dann headless2 bestanden, 4,96 und 5,68 Sekunden
8.4.1513.42.0sichtbar2 bestanden, 5,27 Sekunden
8.5.013.42.0sichtbar, dann headless2 bestanden, 4,46 und 4,33 Sekunden

Das Zeitlimit und der SDK-Timeout

Die PHP-Einstellung max_execution_time stoppt einen Dusk-Lauf nicht. Ich habe sie in der php.ini auf 30 gesetzt, und eine Sonde im Test las unter 8.2.29, 8.3.28, 8.4.15 und 8.5.0 den Wert 0, weil php artisan dusk PHPUnit auf der Kommandozeile startet, wo das Limit abgeschaltet ist.

Für Turnstile wartet das PHP SDK 1.7.0 bis zu seinem defaultTimeout von 120 Sekunden, es sei denn, der Aufruf übergibt eine Option timeout, wie es das Trait mit 60 tut. Das SDK liest das Ergebnis nach 0 s, 0,25 s, 0,75 s, 1,75 s und 3,75 s nach dem Absenden, danach bei 7,75 s und alle 5 Sekunden, und es prüft die Frist nur, wenn die nächste Abfrage fällig ist. Der Aufruf endet also später als die Zahl, die Sie angegeben haben.

Mock von CapSkip, wird nie fertigGemessen
timeout 5, in einem Dusk-Test, PHP 8.3.28TimeoutException nach 7,83 Sekunden
timeout 60, einfache Kommandozeile, PHP 8.3.28TimeoutException nach 62,97 Sekunden, letzte Abfrage bei 57,93
Token nach 45 Sekunden bereit, timeout 60, Dusk-TestToken nach 48,31 Sekunden zurückgegeben, Formular akzeptiert

Die letzte Zeile zeigt auch, dass der Browser warten kann: Chrome und ChromeDriver lagen diese 48 Sekunden im Leerlauf, und der nächste Befehl funktionierte. Etwas Längeres habe ich nicht getestet. Laut Cloudflare-Dokumentation lebt ein Turnstile-Token fünf Minuten und gilt für eine einzige Verwendung, fordern Sie ihn also an, nachdem die Seite geladen ist, und tragen Sie ihn sofort ein. Einen Token, den ich ein zweites Mal sendete, lehnte mein Mock mit timeout-or-duplicate ab, dem Code, den die Dokumentation für diesen Fall nennt.

Häufige Fehler

In dieser Tabelle bedeutet „beobachtet“, dass ich den Fehler selbst gegen die Mocks erzeugt habe.

FehlerUrsacheBeheben
cURL error 60 bei dusk:installphp.ini nennt kein CA-Bundle (beobachtet)Setzen Sie curl.cainfo in der php.ini und führen Sie dann dusk:chrome-driver mit der Option detect aus
NetworkException: Failed to connect to 127.0.0.1 port 8080 after about 2000 ms: Couldn’t connect to serverAm Host und Port von CapSkip lauscht nichts. Der Fehler trat nach etwa 2 Sekunden auf (beobachtet, 2,02 s bei einem geschlossenen Port)Starten Sie CapSkip und vergleichen Sie CAPSKIP_HOST und CAPSKIP_PORT in .env.dusk.local mit den Verbindungseinstellungen
TimeoutException: timeout 60 exceededKein Token vor Ablauf der Frist (beobachtet)Prüfen Sie den CapSkip-Monitor und erhöhen Sie dann die Option timeout
ApiException mit ERROR_CAPTCHA_UNSOLVABLEDer Mock hat geantwortet, aber die Lösung ist fehlgeschlagen (beobachtet)Führen Sie den Test erneut aus, denn eine neue Aufgabe ist ein neuer Versuch
ValidationException: Unsupported parameters for TurnstileEine Option, die Turnstile nicht kennt, etwa invisible (beobachtet)Entfernen Sie diese Option aus dem Aufruf von turnstile
TypeError: Argument #1 ($sitekey) must be of type stringDas Widget hat kein Attribut data-sitekey (beobachtet)Lesen Sie den Sitekey aus dem Aufruf von turnstile.render auf der Seite
Waited 5 seconds for selectorwaitFor mit seinem Standardlimit auf dem versteckten Feld (beobachtet)Verwenden Sie waitUntilPresent
The cf-turnstile-response field is required.Das Formular wurde mit leerem Feld gesendet (beobachtet, der zweite Test)Füllen Sie das Feld, bevor Sie den Button drücken
Captcha refused: timeout-or-duplicateDer Mock hat den Token ein zweites Mal gesehen (beobachtet)Fordern Sie für jedes Absenden eines Formulars einen neuen Token an
Deprecated: curl_close()Der vollständige Text lautet Function curl_close() is deprecated since 8.5, as it has no effect since PHP 8.0. Das SDK ruft sie weiterhin auf. Laravel schickt die Meldung an den Log-Kanal in LOG_DEPRECATIONS_CHANNEL, im Skeleton null, daher wurde nichts ausgegeben. Mit dem Kanal single zählte ich zwei Einträge für eine Lösung (beobachtet)Lassen Sie es so oder filtern Sie es, bis das SDK den Aufruf entfernt

CapSkip auf einem anderen Rechner betreiben

Eine Dusk-Suite muss nicht auf dem PC laufen, der CapSkip hostet. Schalten Sie CapSkip auf Server mode um, tragen Sie die Adresse dieses Rechners in CAPSKIP_HOST in .env.dusk.local ein, und am Helfer ändert sich sonst nichts. Ist API Key Validation aktiviert, fügen Sie CAPSKIP_API_KEY mit Ihrem Schlüssel hinzu, den der Helfer als apiKey übergibt. CapSkip öffnet seinen Port für alle Adressen, sobald Server mode startet. Um den Zugriff auf die erwarteten Rechner zu beschränken, legen Sie daher eine Blockierungsregel in der Windows-Firewall für alle anderen an. Der Solver läuft weiterhin auf Ihrem eigenen Windows-Rechner.

FAQ

Sollen die Tests meiner eigenen App deren Captcha überhaupt lösen?

In der Regel nicht. Gehört die App Ihnen, schalten Sie die Prüfung in der Dusk-Umgebung ab oder täuschen Sie die Verifizierung vor. Dieser Leitfaden ist für Seiten gedacht, deren Verifizierung Sie nicht ändern können, etwa eine Staging-Website, die jemand anderes betreibt.

Funktioniert derselbe Helfer für reCAPTCHA oder MTCaptcha?

Das SDK hat recaptcha() und mtcaptcha() mit derselben Form, aber die Feldnamen unterscheiden sich, und ich habe nur Turnstile ausgeführt. Der Symfony-Panther-Leitfaden zeigt reCAPTCHA in einem PHP-Browserskript.

Sollte ich statt Dusk lieber Pest-Browser-Tests verwenden?

Die Dusk-Dokumentation empfiehlt für Browser-Tests in neuen Projekten inzwischen Pest 4. Der CapSkip-Aufruf ist reines PHP, die Idee sollte sich also übertragen lassen, aber ich habe nur Dusk ausgeführt.

Gilt das auch für Queue-Jobs?

Nein. Ein Job hat eigene Worker-Limits, die der Laravel-Queue-Leitfaden behandelt. Ein Dusk-Test ist ein Kommandozeilenprozess, daher war das Limit, das hier galt, der SDK-Timeout.

Ein Laravel-Dusk-Captcha-Schritt besteht aus vier Handgriffen: auf das versteckte Feld warten, den Sitekey lesen, den Token erst kurz vor dem Bedarf anfordern und ihn mit script() schreiben. Für einen Captcha-Löser ohne Gebühr pro Token läuft CapSkip auf Ihrem eigenen PC, ein fehlgeschlagener Lauf kostet also nur einen weiteren Testlauf. Die Seite zum Cloudflare-Turnstile-Löser behandelt das Widget selbst, der Turnstile-PHP-Leitfaden zeigt denselben Aufruf ohne Browser, und die PHP-Captcha-Solver-Seite listet die weiteren Typen auf.