브라우저 테스트(Dusk)

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

​

Laravel Dusk란

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

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

​

설치

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

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

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

# 로컬 Chrome에 맞는 버전을 감지해서 설치
php artisan dusk:chrome-driver --detect

​

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

Dusk 전용 환경 변수를 사용하려면 프로젝트 루트에 .env.dusk.{environment}를 생성합니다.
로컬 환경이라면 .env.dusk.local을 사용합니다.

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로 실행합니다.

php artisan dusk:make LoginTest
php artisan dusk

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

php artisan dusk:fails

​

기본 조작 예시

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

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

​

페이지 객체 패턴

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

php artisan dusk:page Login

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

use Tests\Browser\Pages\Login;

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

​

스크린샷과 디버깅

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

$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를 실행합니다.

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 실행 플로우

​

공식 문서

Laravel Dusk — 공식 문서

Dusk의 모든 API(대기, 어서션, 키보드 조작, iframe 조작 등)는 공식 문서에서 확인해 주세요.