跳转到主要内容

简介

Laravel 提供了丰富的 API 用于模拟 HTTP 请求并对响应进行断言。 你无需实际启动 HTTP 服务器,就能在测试中重现应用的请求处理流程。
get() 方法会向应用发送一个 GET 请求,assertStatus() 用于校验返回的 HTTP 状态码。
测试运行期间 CSRF 中间件会被自动禁用,不需要在测试中显式关闭。

发起请求

在测试中,可以使用 getpostputpatchdelete 等方法发起请求。 这些方法并不会真正发起网络请求,而是在应用内部模拟。 返回值是 Illuminate\Testing\TestResponse 的实例,提供了大量的断言方法。
建议每个测试方法内基本上只发一次请求。在同一个测试中执行多个请求可能会出现意想不到的行为。

自定义请求头

使用 withHeaders() 可以自定义请求头。
在发起请求前,可以通过 withCookie()withCookies() 设置 Cookie 值。

会话与认证

withSession() 可以在请求前设置 Session 数据。
actingAs() 可以让你以已认证用户的身份发起请求。通常与模型工厂配合使用。
actingAs() 的第二个参数传入 guard 名,即可以该 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 路径断言

assertJsonPath() 可以校验指定路径下的值。
也可以传入闭包做更灵活的校验。

流式 JSON 测试

assertJson() 传入闭包后,可以用 AssertableJson 实例以链式风格编写断言。
etc() 表示允许除断言字段之外还存在其他属性。不加 etc() 时,一旦有未断言的额外属性测试就会失败。这可以避免无意中把敏感信息暴露在响应中。
要断言属性存在或不存在,使用 has()missing()
要一次性判断多个属性,使用 hasAll()missingAll()

JSON 集合断言

如果路由返回的是包含多个元素的 JSON,可以通过 has() 校验数量或元素内容。
要对每个元素都应用相同断言,使用 each()

JSON 类型断言

使用 whereType()whereAllType() 可以校验属性的类型。
| 可以指定多个类型,符合其中之一即通过。
可用类型有 stringintegerdoublebooleanarraynull

认证测试

通过 actingAs() 可以以已认证用户的身份发起请求。
若要以指定 guard 认证,可以传入第二个参数。

用户注册流程测试示例

下面是对真实注册接口的测试示例。

会话测试

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(测试驱动开发)非常搭配。留意以下要点会让 TDD 更高效。
HTTP 测试应放在 tests/Feature/ 目录下。先定义从应用外部看到的行为(请求 → 响应),可以让待实现的功能更清晰。
需要用到数据库的测试请使用 RefreshDatabase trait。每个测试后都会重置数据库,防止用例之间的数据干扰。测试的独立性可以让测试套件更稳定,不依赖执行顺序。
使用 User::factory()->create() 这类模型工厂能极大简化数据准备。为常用状态定义 factory state 还能提升测试可读性。
每个测试方法尽量只验证一件事。这样在失败时更容易定位原因。遵循 Arrange(准备)→ Act(执行)→ Assert(断言)的 AAA 结构会更清晰。
对需要认证的路由,务必同时编写“已认证”和“未认证”的测试,以尽早发现安全问题。

相关页面

测试入门

了解 Laravel 中编写测试的基础,以及 php artisan test 的使用。
最后修改于 2026年7月18日