> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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é.

<Warning>
  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.
</Warning>

## Installation

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

```shell theme={null}
composer require laravel/dusk --dev
php artisan dusk:install
```

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

```shell theme={null}
# 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`.

```ini theme={null}
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`.

```shell theme={null}
php artisan dusk:make LoginTest
php artisan dusk
```

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

```shell theme={null}
php artisan dusk:fails
```

### Exemple d'opérations de base

```php theme={null}
<?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' => 'taylor@laravel.com',
        ]);

        $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.

<Warning>
  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.
</Warning>

## Pattern Page Object

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

```shell theme={null}
php artisan dusk:page Login
```

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

```php theme={null}
use Tests\Browser\Pages\Login;

$browser->visit(new Login)
    ->type('@email', 'taylor@laravel.com')
    ->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.

```php theme={null}
$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`.

```yaml theme={null}
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

```mermaid theme={null}
flowchart TD
    A["php artisan dusk"] --> B["Sauvegarde du .env"]
    B --> C["Application du .env.dusk.local"]
    C --> D["Démarrage de ChromeDriver"]
    D --> E["Exécution des tests Browser<br>visit / type / click / assertSee"]
    E --> F{"Échec ?"}
    F -->|Oui| G["Sauvegarde des captures et logs"]
    F -->|Non| H["Test terminé"]
    G --> I["Restauration du .env"]
    H --> I
```

## Documentation officielle

<Card title="Laravel Dusk — Documentation officielle" icon="arrow-right" href="https://laravel.com/docs/dusk">
  Consultez l'API complète de Dusk (attentes, assertions, clavier, iframes, etc.) dans la documentation officielle.
</Card>


## Related topics

- [Laravel Maestro — l'orchestrateur de développement des starter kits](/fr/blog/maestro-introduction.md)
- [Installation](/fr/installation.md)
- [Première analyse de Laravel Passkeys (passkeys-server + @laravel/passkeys)](/fr/blog/passkeys-introduction.md)
- [Session](/fr/session.md)
- [Installer PHP, Composer et Node.js avec WSL (Windows)](/fr/blog/windows-setup.md)