跳轉到主要內容

簡介

Laravel 提供豐富的 API 讓你能模擬 HTTP 請求並驗證回應。 不用真的架設 HTTP 伺服器,就能在測試中重現對應用程式的請求。
get() 方法對應用程式送出 GET 請求,assertStatus() 驗證回應的 HTTP 狀態碼。
執行測試期間,CSRF 中介軟體會自動停用,不必在測試中手動關閉。

建立請求

在測試中可用 get、post、put、patch、delete 送出請求。 這些方法不會實際發送網路請求,而是在應用程式內部模擬。 回傳值為 Illuminate\Testing\TestResponse 實例,提供大量斷言方法。
建議每個測試方法內原則上僅送出一次請求。同一測試中發送多次請求可能導致非預期行為。

自訂請求標頭

用 withHeaders() 自訂請求標頭。
以 withCookie() 或 withCookies() 在請求前設定 cookie 值。

Session 與認證

用 withSession() 在請求前設定 session 資料。
用 actingAs() 可以以已認證使用者身份送出請求,常搭配模型工廠使用。
在 actingAs() 的第 2 個參數指定 guard 名稱,可用該 guard 認證。該 guard 在測試期間會成為預設。
若要以未認證狀態發送請求,用 actingAsGuest()。

除錯回應

若想在測試中檢視回應內容,可用 dump、dumpHeaders、dumpSession。
若要中止執行,可用 dd、ddHeaders、ddBody、ddJson、ddSession。

例外測試

要測試是否會拋出特定例外,可用 Exceptions Facade。
確認未拋出例外,用 assertNotReported 或 assertNothingReported。
若要停用例外處理送出請求,用 withoutExceptionHandling()。
要測試閉包中的程式碼是否拋出例外,用 assertThrows()。
確認不會拋出例外,用 assertDoesntThrow()。

JSON API 的測試

Laravel 提供多種 JSON API 測試輔助方法。 json、getJson、postJson、putJson、patchJson、deleteJson、optionsJson 皆可送出 JSON 請求。
JSON 回應資料可用陣列變數方式存取。
assertJson() 會把回應轉為陣列,並驗證所指定陣列是否包含在 JSON 中。JSON 中其他屬性即使存在,只要指定的片段有出現,測試就會通過。

完全比對的斷言

用 assertExactJson() 可驗證回傳 JSON 與指定陣列完全一致。

JSON path 的斷言

用 assertJsonPath() 檢驗特定路徑上的資料。
也可以傳入閉包做更彈性的檢查。

流暢的 JSON 測試

assertJson() 傳入閉包時,可用 AssertableJson 實例以流暢方式撰寫斷言。
etc() 方法允許存在非斷言中的其他屬性。若未加 etc(),一旦有未斷言的屬性存在,測試會失敗。這可避免無意間將機密資訊納入回應。
檢查屬性存在 / 不存在,用 has() 與 missing()。
一次檢查多個屬性可用 hasAll() 或 missingAll()。

JSON 集合的斷言

若路由回傳含多個項目的 JSON,可用 has() 檢驗數量與內容。
要對所有項目套用相同斷言,用 each()。

JSON 的型別斷言

以 whereType() 或 whereAllType() 檢查屬性型別。
也可以用 | 指定多個型別,其中之一符合即算通過。
可用的型別有 string、integer、double、boolean、array、null。

認證測試

用 actingAs() 以已認證使用者身份送出請求。
要以特定 guard 認證,於第 2 個參數指定:

使用者註冊流程測試範例

實際測試使用者註冊端點的範例:

Session 測試

用 withSession() 事先設定 session,用 assertSessionHas() 檢驗 session 是否有指定值。

Session 斷言一覽

檔案上傳的測試

以 Illuminate\Http\UploadedFile 的 fake() 產生虛擬檔案或圖片。 搭配 Storage Facade 的 fake() 可輕鬆測試檔案上傳。
確認檔案不存在可用 assertMissing()。

自訂虛擬檔案

可指定圖片尺寸或檔案大小,適合測試驗證規則。

視圖測試

不需模擬 HTTP 請求,也能直接渲染視圖進行測試。 view() 方法接收視圖名稱與可選的資料陣列,回傳 Illuminate\Testing\TestView 實例。
TestView 類別提供的斷言方法: 要以字串取得已渲染視圖內容,可將 TestView 實例轉為字串。
要將驗證錯誤傳入視圖,可用 withViewErrors()。

元件測試

以 blade() 渲染原始 Blade 樣板字串。
以 component() 渲染 Blade 元件,回傳 Illuminate\Testing\TestComponent 實例。

回應斷言一覽

Illuminate\Testing\TestResponse 類別的主要斷言方法:

HTTP 狀態

重新導向

內容

JSON

視圖

驗證

實踐 TDD 的要點

HTTP 測試與 TDD(測試驅動開發)非常契合。留意以下要點會更有效。
HTTP 測試放在 tests/Feature/ 目錄。從應用程式外部視角先定義行為(請求→回應),能讓待實作功能清晰。
需使用資料庫的測試請採用 RefreshDatabase trait。每測試後重置資料庫,可避免測試間資料干擾。維持測試獨立性,能構築不受執行順序影響的穩定測試套件。
使用如 User::factory()->create() 等模型工廠可簡化測試資料建立。定義工廠 state 讓具備特定狀態的模型建立更容易,測試可讀性亦提升。
每個測試方法盡量只驗證一件事,測試失敗時原因更好定位。留意「Arrange(準備)→ Act(執行)→ Assert(驗證)」的 AAA 模式,測試會更易讀。
需認證的路由請務必同時測「已認證」與「未認證」情境,可儘早發現安全問題。

相關頁面

測試入門

瞭解 Laravel 測試的基本寫法與 php artisan test 的使用。
最後修改於 2026年8月2日