Skip to main content

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(),測試端便可重複利用。

螢幕截圖與偵錯

排查失敗原因時,儲存螢幕截圖與 console 日誌會很有幫助。
  • 螢幕截圖:tests/Browser/screenshots
  • Console 日誌:tests/Browser/console

在 CI(GitHub Actions)中執行

在 GitHub Actions 中,先啟動 ChromeDriver 與 Laravel 內建伺服器,再執行 php artisan dusk

Dusk 執行流程

官方文件

Laravel Dusk — 官方文件

Dusk 的完整 API(等待、斷言、鍵盤操作、iframe 操作等)請參考官方文件。
最後修改於 2026年8月2日