Pruebas de navegador (Dusk)

Cómo ejecutar pruebas E2E de navegador basadas en ChromeDriver usando Laravel Dusk

​

¿Qué es Laravel Dusk?

Laravel Dusk es una herramienta de pruebas E2E que opera realmente un navegador para verificar la pantalla completa.
Por defecto puedes ejecutar las pruebas con ChromeDriver, sin necesidad de preparar un servidor Selenium aparte.

La documentación oficial recomienda usar las pruebas de navegador de Pest 4 para proyectos nuevos. Usa esta página cuando ya utilices Dusk en un proyecto existente o cuando quieras aprovechar la API de Dusk.

​

Instalación

Primero instala Google Chrome y añade Dusk como dependencia de desarrollo.

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

Si necesitas ajustar la versión de ChromeDriver usa el comando dusk:chrome-driver.

# Detecta e instala la versión compatible con el Chrome local
php artisan dusk:chrome-driver --detect

​

Configuración del entorno (.env.dusk.local)

Para usar variables de entorno específicas de Dusk, crea .env.dusk.{environment} en la raíz del proyecto.
Para el entorno local se usa .env.dusk.local.

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

Durante la ejecución de Dusk se hace una copia de seguridad de .env y se aplica temporalmente el contenido de .env.dusk.local.

​

Prueba básica de navegador

Genera un test y ejecútalo con php artisan dusk.

php artisan dusk:make LoginTest
php artisan dusk

Para reejecutar solo las pruebas fallidas:

php artisan dusk:fails

​

Ejemplo de operaciones básicas

<?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() y assertSee() son las operaciones más habituales en Dusk.

En las pruebas de Dusk no se usa RefreshDatabase. Tal y como indica la documentación oficial, usa DatabaseMigrations o DatabaseTruncation para reiniciar los datos entre pruebas.

​

Patrón Page Object

Al probar pantallas complejas, crear un page object con dusk:page facilita el mantenimiento.

php artisan dusk:page Login

Define url() y elements() en tests/Browser/Pages/Login.php y reutilízalo en las pruebas.

use Tests\Browser\Pages\Login;

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

​

Capturas de pantalla y depuración

Para investigar fallos es útil guardar capturas y logs de consola.

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

• Capturas: tests/Browser/screenshots
• Logs de consola: tests/Browser/console

​

Ejecución en CI (GitHub Actions)

En GitHub Actions se inicia ChromeDriver y el servidor integrado de Laravel antes de ejecutar 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

​

Flujo de ejecución de Dusk

​

Documentación oficial

Laravel Dusk — Documentación oficial

Consulta la documentación oficial para conocer toda la API de Dusk (esperas, aserciones, teclado, operaciones sobre iframes, etc.).