Skip to main content

簡介

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

建立請求

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

自訂請求標頭

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

Session 與認證

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

除錯回應

若想在測試中檢視回應內容,可用 dumpdumpHeadersdumpSession
若要中止執行,可用 ddddHeadersddBodyddJsonddSession

例外測試

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

JSON API 的測試

Laravel 提供多種 JSON API 測試輔助方法。 jsongetJsonpostJsonputJsonpatchJsondeleteJsonoptionsJson 皆可送出 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() 檢查屬性型別。
也可以用 | 指定多個型別,其中之一符合即算通過。
可用的型別有 stringintegerdoublebooleanarraynull

認證測試

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

使用者註冊流程測試範例

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

Session 測試

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

Session 斷言一覽

檔案上傳的測試

Illuminate\Http\UploadedFilefake() 產生虛擬檔案或圖片。 搭配 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日