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

# 브라우저 테스트(Dusk)

> Laravel Dusk를 사용해 ChromeDriver 기반의 브라우저 E2E 테스트를 실행하는 방법

## Laravel Dusk란

Laravel Dusk는 브라우저를 실제로 조작해서 화면 전체를 검증하는 E2E 테스트 도구입니다.\
기본적으로 Selenium 서버를 별도로 준비하지 않아도 ChromeDriver로 테스트를 실행할 수 있습니다.

<Warning>
  공식 문서에서는 새 프로젝트에서는 Pest 4의 브라우저 테스트도 권장하고 있습니다. 기존 프로젝트에서 Dusk를 사용하는 경우나 Dusk의 API를 사용하고 싶은 경우에 이 페이지를 활용해 주세요.
</Warning>

## 설치

먼저 Google Chrome을 설치하고, Dusk를 개발 의존성으로 추가합니다.

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

ChromeDriver 버전을 조정하고 싶은 경우에는 `dusk:chrome-driver` 명령을 사용합니다.

```shell theme={null}
# 로컬 Chrome에 맞는 버전을 감지해서 설치
php artisan dusk:chrome-driver --detect
```

## 환경 설정(`.env.dusk.local`)

Dusk 전용 환경 변수를 사용하려면 프로젝트 루트에 `.env.dusk.{environment}`를 생성합니다.\
로컬 환경이라면 `.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
```

Dusk 실행 중에는 `.env`가 백업되고, `.env.dusk.local`의 내용이 일시적으로 적용됩니다.

## 기본 브라우저 테스트

테스트를 생성하고 `php artisan dusk`로 실행합니다.

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

실패한 테스트만 재실행하는 경우:

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

### 기본 조작 예시

```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()`, `assertSee()`는 Dusk에서 가장 자주 사용하는 조작입니다.

<Warning>
  Dusk 테스트에서는 `RefreshDatabase`를 사용하지 않습니다. 공식 문서에 따라 `DatabaseMigrations`나 `DatabaseTruncation`을 사용해 테스트 간 데이터를 초기화해 주세요.
</Warning>

## 페이지 객체 패턴

복잡한 화면을 테스트할 때는 `dusk:page`로 페이지 객체를 만들면 유지 보수가 쉬워집니다.

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

`tests/Browser/Pages/Login.php`에서 `url()`이나 `elements()`를 정의하고, 테스트 쪽에서 재사용합니다.

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

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

## 스크린샷과 디버깅

실패 조사에서는 스크린샷과 콘솔 로그 저장이 유용합니다.

```php theme={null}
$browser->screenshot('login-failed');
$browser->responsiveScreenshots('login-page');
$browser->screenshotElement('#login-form', 'login-form');
$browser->storeConsoleLog('login-console');
```

* 스크린샷: `tests/Browser/screenshots`
* 콘솔 로그: `tests/Browser/console`

## CI(GitHub Actions)에서 실행하기

GitHub Actions에서는 ChromeDriver와 Laravel의 내장 서버를 기동한 후 `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
```

## Dusk 실행 플로우

```mermaid theme={null}
flowchart TD
    A["php artisan dusk"] --> B[".env를 백업"]
    B --> C[".env.dusk.local을 적용"]
    C --> D["ChromeDriver를 기동"]
    D --> E["Browser 테스트를 실행<br>visit / type / click / assertSee"]
    E --> F{"실패했나?"}
    F -->|Yes| G["스크린샷과 로그를 저장"]
    F -->|No| H["테스트 완료"]
    G --> I[".env를 복원"]
    H --> I
```

## 공식 문서

<Card title="Laravel Dusk — 공식 문서" icon="arrow-right" href="https://laravel.com/docs/dusk">
  Dusk의 모든 API(대기, 어서션, 키보드 조작, iframe 조작 등)는 공식 문서에서 확인해 주세요.
</Card>


## Related topics

- [Laravel Maestro — 스타터 킷 개발의 오케스트레이터](/ko/blog/maestro-introduction.md)
- [Laravel Sail](/ko/sail.md)
- [Laravel Telescope 실전 테크닉](/ko/blog/telescope-introduction.md)
- [라우팅](/ko/routing.md)
- [Laravel Passkeys 초기 조사 (passkeys-server + @laravel/passkeys)](/ko/blog/passkeys-introduction.md)