Laravel Dusk란
Laravel Dusk는 브라우저를 실제로 조작해서 화면 전체를 검증하는 E2E 테스트 도구입니다.
기본적으로 Selenium 서버를 별도로 준비하지 않아도 ChromeDriver로 테스트를 실행할 수 있습니다.
공식 문서에서는 새 프로젝트에서는 Pest 4의 브라우저 테스트도 권장하고 있습니다. 기존 프로젝트에서 Dusk를 사용하는 경우나 Dusk의 API를 사용하고 싶은 경우에 이 페이지를 활용해 주세요.
composer require laravel/dusk --dev
php artisan dusk:install
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
.env가 백업되고, .env.dusk.local의 내용이 일시적으로 적용됩니다.
기본 브라우저 테스트
테스트를 생성하고 php artisan dusk로 실행합니다.
php artisan dusk:make LoginTest
php artisan dusk
기본 조작 예시
<?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' => '[email protected]',
]);
$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', '[email protected]')
->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 조작 등)는 공식 문서에서 확인해 주세요.
