跳转到主要内容

什么是 Laravel Dusk

Laravel Dusk 是一款通过实际操作浏览器来验证整个页面的 E2E 测试工具。 默认情况下无需另外准备 Selenium 服务器,即可使用 ChromeDriver 执行测试。
官方文档也建议在新项目中使用 Pest 4 的浏览器测试。如果你在已有项目中使用 Dusk,或希望使用 Dusk 的 API,请参阅本页。

安装

首先安装 Google Chrome,并将 Dusk 添加为开发依赖。
如果想调整 ChromeDriver 的版本,请使用 dusk:chrome-driver 命令。

环境配置(.env.dusk.local

要使用 Dusk 专用的环境变量,请在项目根目录创建 .env.dusk.{environment}。 在本地环境中使用 .env.dusk.local
Dusk 执行期间,.env 会被备份,.env.dusk.local 的内容会临时生效。

基本的浏览器测试

生成测试并使用 php artisan dusk 运行。
只重跑失败的测试:

基本操作示例

visit()type()press()assertSee() 是 Dusk 中最常用的操作。
在 Dusk 测试中不要使用 RefreshDatabase。请按照官方文档所述,使用 DatabaseMigrationsDatabaseTruncation 在测试之间初始化数据。

页面对象模式

在测试复杂页面时,通过 dusk:page 创建页面对象会更易于维护。
tests/Browser/Pages/Login.php 中定义 url()elements(),然后在测试中复用。

截图与调试

排查失败原因时,保存截图和控制台日志会很有帮助。
  • 截图:tests/Browser/screenshots
  • 控制台日志:tests/Browser/console

在 CI(GitHub Actions)中运行

在 GitHub Actions 中,先启动 ChromeDriver 与 Laravel 内置服务器,再执行 php artisan dusk

Dusk 执行流程

官方文档

Laravel Dusk — 官方文档

Dusk 的所有 API(等待、断言、键盘操作、iframe 操作等)请查阅官方文档。
最后修改于 2026年7月18日