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

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

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

## Instalación

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

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

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

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

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

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

Para reejecutar solo las pruebas fallidas:

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

### Ejemplo de operaciones básicas

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

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

## Patrón Page Object

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

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

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

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

$browser->visit(new Login)
    ->type('@email', 'taylor@laravel.com')
    ->type('@password', 'password')
    ->click('@submit')
    ->assertSee('Dashboard');
```

## Capturas de pantalla y depuración

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

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

```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
```

## Flujo de ejecución de Dusk

```mermaid theme={null}
flowchart TD
    A["php artisan dusk"] --> B["Copia de seguridad de .env"]
    B --> C["Aplicación de .env.dusk.local"]
    C --> D["Inicio de ChromeDriver"]
    D --> E["Ejecución de pruebas Browser<br>visit / type / click / assertSee"]
    E --> F{"¿Falló?"}
    F -->|Sí| G["Guardar captura y logs"]
    F -->|No| H["Prueba finalizada"]
    G --> I["Restauración de .env"]
    H --> I
```

## Documentación oficial

<Card title="Laravel Dusk — Documentación oficial" icon="arrow-right" href="https://laravel.com/docs/dusk">
  Consulta la documentación oficial para conocer toda la API de Dusk (esperas, aserciones, teclado, operaciones sobre iframes, etc.).
</Card>


## Related topics

- [Laravel Maestro — Orquestador de desarrollo de starter kits](/es/blog/maestro-introduction.md)
- [Laravel Sail](/es/sail.md)
- [Pruebas HTTP](/es/http-tests.md)
- [Instalación](/es/installation.md)
- [Pruebas de consola](/es/console-tests.md)