Tests de navigateur (Dusk)

Comment exécuter des tests E2E basés sur ChromeDriver dans le navigateur avec Laravel Dusk.

​

Qu’est-ce que Laravel Dusk

Laravel Dusk est un outil de test E2E qui pilote un vrai navigateur pour vérifier l’écran dans son ensemble.
Par défaut, il vous permet d’exécuter des tests avec ChromeDriver sans avoir à préparer un serveur Selenium séparé.

La documentation officielle recommande également Pest 4 pour les tests de navigateur dans les nouveaux projets. Utilisez cette page si vous continuez avec Dusk dans un projet existant ou si vous souhaitez utiliser l’API de Dusk.

​

Installation

Installez d’abord Google Chrome, puis ajoutez Dusk comme dépendance de développement.

composer require laravel/dusk --dev
php artisan dusk:install

Pour ajuster la version de ChromeDriver, utilisez la commande dusk:chrome-driver.

# Détecte et installe la version adaptée à votre Chrome local
php artisan dusk:chrome-driver --detect

​

Configuration d’environnement (.env.dusk.local)

Pour utiliser des variables d’environnement spécifiques à Dusk, créez un fichier .env.dusk.{environment} à la racine du projet.
En environnement local, utilisez .env.dusk.local.

APP_URL=http://127.0.0.1:8000
DB_CONNECTION=mysql
DB_DATABASE=app_testing
DB_USERNAME=root
DB_PASSWORD=root

Pendant l’exécution de Dusk, le fichier .env est sauvegardé et le contenu de .env.dusk.local est temporairement appliqué.

​

Tests de navigateur de base

Générez un test et exécutez-le avec php artisan dusk.

php artisan dusk:make LoginTest
php artisan dusk

Pour réexécuter uniquement les tests échoués :

php artisan dusk:fails

​

Exemple d’opérations de base

<?php

namespace Tests\Browser;

use App\Models\User;
use Laravel\Dusk\Browser;
use Tests\DuskTestCase;

class LoginTest extends DuskTestCase
{
    public function test_user_can_login(): void
    {
        $user = User::factory()->create([
            'email' => '[e-mail]',
        ]);

        $this->browse(function (Browser $browser) use ($user) {
            $browser->visit('/login')
                ->type('email', $user->email)
                ->type('password', 'password')
                ->press('Login')
                ->assertPathIs('/dashboard')
                ->assertSee('Dashboard');
        });
    }
}

visit(), type(), press() et assertSee() sont les opérations les plus courantes avec Dusk.

N’utilisez pas RefreshDatabase dans les tests Dusk. Comme le précise la documentation officielle, utilisez DatabaseMigrations ou DatabaseTruncation pour réinitialiser les données entre les tests.

​

Pattern Page Object

Pour tester des écrans complexes, générer un page object avec dusk:page facilite la maintenance.

php artisan dusk:page Login

Dans tests/Browser/Pages/Login.php, définissez url() et elements(), puis réutilisez-les dans le test.

use Tests\Browser\Pages\Login;

$browser->visit(new Login)
    ->type('@email', '[e-mail]')
    ->type('@password', 'password')
    ->click('@submit')
    ->assertSee('Dashboard');

​

Captures d’écran et débogage

Pour analyser les échecs, sauvegarder des captures d’écran et les logs de la console est très utile.

$browser->screenshot('login-failed');
$browser->responsiveScreenshots('login-page');
$browser->screenshotElement('#login-form', 'login-form');
$browser->storeConsoleLog('login-console');

• Captures d’écran : tests/Browser/screenshots
• Logs de console : tests/Browser/console

​

Exécution en CI (GitHub Actions)

Sur GitHub Actions, démarrez ChromeDriver et le serveur intégré de Laravel avant d’exécuter php artisan dusk.

name: Dusk tests

on: [push, pull_request]

jobs:
  dusk:
    runs-on: ubuntu-latest
    env:
      APP_URL: http://127.0.0.1:8000
      DB_USERNAME: root
      DB_PASSWORD: root
      MAIL_MAILER: log
    steps:
      - uses: actions/checkout@v5
      - run: cp .env.example .env
      - run: composer install --no-progress --prefer-dist --optimize-autoloader
      - run: php artisan key:generate
      - run: php artisan dusk:chrome-driver --detect
      - run: ./vendor/laravel/dusk/bin/chromedriver-linux --port=9515 &
      - run: php artisan serve --no-reload &
      - run: php artisan dusk

​

Flux d’exécution de Dusk

​

Documentation officielle

Laravel Dusk — Documentation officielle

Consultez l’API complète de Dusk (attentes, assertions, clavier, iframes, etc.) dans la documentation officielle.