什么是 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 操作等）请查阅官方文档。
