laravel-testing

Laravel 13 测试 — Pest PHP 4 和 PHPUnit 12

同时支持 Pest PHP 4 和 PHPUnit 12。 请参阅下文的框架检测。

PHPUnit 版本说明： Laravel 13 默认的 composer.json 中包含 phpunit/phpunit: ^12.5.12。本指南中的所有模式都兼容 PHPUnit 11、12 和 13。

Laravel 13 应用的全面测试指南。包含 6 个类别中的 24 条规则，帮助编写快速、易读且可靠的测试。同时支持 Pest PHP 4 和 PHPUnit 12（Laravel 13 默认）。

框架检测

编写或审查任何测试代码之前，请先检测项目使用的测试框架：

步骤 1 — 检查 composer.json

# Look for these in require-dev:
# "pestphp/pest" → Pest
# "phpunit/phpunit" (without pest) → PHPUnit

• 如果存在 pestphp/pest → 使用 Pest 语法
• 如果只存在 phpunit/phpunit → 使用 PHPUnit 语法
• 如果两者都存在 → 优先使用 Pest（Pest 基于 PHPUnit 运行）

步骤 2 — 检查是否存在 tests/Pest.php

• 如果存在 tests/Pest.php → 已配置 Pest，请使用 Pest 语法

步骤 3 — 如果仍无法确定，请询问用户

“我无法检测到测试框架。此项目使用 Pest PHP 还是 PHPUnit？”

---

语法参考

测试声明

	Pest	PHPUnit
测试函数	test('...', fn() => ...)	public function test_...(): void
易读名称	it('...', fn() => ...)	#[Test] public function it_...()
分组	describe('...', fn() => ...)	测试类名称／嵌套类
应用 Trait	uses(RefreshDatabase::class)	在类中使用 use RefreshDatabase;
每次测试前	beforeEach(fn() => ...)	protected function setUp(): void
每次测试后	afterEach(fn() => ...)	protected function tearDown(): void
参数化	->with([...])	#[DataProvider] 属性
全局设置	在 Pest.php 中使用 uses(...)->in('Feature')	基础 TestCase 类

核心断言（两个框架中完全相同）

assertStatus、assertJson、assertJsonPath、assertDatabaseHas、assertModelExists、actingAs、Mail::fake()、Queue::fake()、Event::fake()、Notification::fake()、Storage::fake() — 在 Pest 和 PHPUnit 中的用法完全相同。

---

适用场景

遇到以下情况时，请参考这些指南：

• 为 Laravel 编写功能测试或单元测试
• 测试 HTTP 端点和 API 响应
• 创建工厂和测试数据
• 断言操作后的数据库状态
• 模拟 Mail、Queue、Notification 或 Event 门面
• 测试经过身份验证的路由和 API 令牌
• 使用 describe 块、数据集或测试类组织测试

按优先级划分的规则类别

优先级	类别	影响	前缀
1	HTTP 和功能测试	严重	http-
2	模型工厂	严重	factory-
3	数据库断言	高	db-
4	模拟服务	高	fake-
5	身份验证测试	高	auth-
6	测试组织模式	中	pest-

快速参考

1. HTTP 和功能测试（严重）

• http-test-structure - 使用工厂的准备／执行／断言 — Pest 和 PHPUnit 示例
• http-assert-response - assertStatus、assertJson、assertRedirect、assertJsonMissing
• http-assert-json-fluent - 使用 AssertableJson 闭包进行流式 assertJson
• http-refresh-database - RefreshDatabase 与 DatabaseTransactions — 分别适用于哪些情况

2. 模型工厂（严重）

• factory-define - 使用带类型的模拟数据和 PHP 8.3 语法定义工厂
• factory-states - 使用工厂状态处理不同的测试场景
• factory-sequences - 使用 sequence() 为多条记录生成不同数据
• factory-relationships - has()、for()、recycle()、afterCreating()

3. 数据库断言（高）

• db-assert-has - 使用 assertDatabaseHas、assertModelExists 检查是否存在
• db-assert-missing - 使用 assertDatabaseMissing、assertModelMissing 检查删除情况
• db-assert-soft-deletes - 使用 assertSoftDeleted、trashed() 工厂状态

4. 伪造服务（高）

• fake-mail - Mail::fake()、assertSent 与 assertQueued、assertNothingSent
• fake-queue - Queue::fake()、assertPushed、assertPushedOn
• fake-notification - Notification::fake()、assertSentTo、assertCount
• fake-event - Event::fake()、assertDispatched、assertNotDispatched
• fake-storage - Storage::fake()、UploadedFile::fake()、assertExists
• fake-ai-agent - Agent::fake()、assertPrompted、preventStrayPrompts（Laravel 13+）
• fake-ai-media - Image::fake()、Audio::fake()、Transcription::fake()（Laravel 13+）
• fake-ai-data - Embeddings::fake()、Reranking::fake()、Files::fake()、Stores::fake()（Laravel 13+）

5. 身份验证测试（高）

• auth-acting-as - 使用 actingAs() 测试会话/Web 身份验证
• auth-sanctum - 使用 Sanctum::actingAs() 进行 API 令牌身份验证

6. 测试组织模式（中）

• pest-describe-it - describe()/it()（Pest）或测试类组织方式（PHPUnit）
• pest-datasets - with() 数据集（Pest）或 #[DataProvider]（PHPUnit）
• pest-hooks - beforeEach/afterEach（Pest）或 setUp/tearDown（PHPUnit）

基本模式

Pest

<?php

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;

uses(RefreshDatabase::class);

test('authenticated user can create a post', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])
        ->assertStatus(201)
        ->assertJsonPath('data.title', 'Hello World');

    $this->assertDatabaseHas('posts', ['title' => 'Hello World', 'user_id' => $user->id]);
});

PHPUnit

<?php

namespace Tests\Feature;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

class PostControllerTest extends TestCase
{
    use RefreshDatabase;

    public function test_authenticated_user_can_create_a_post(): void
    {
        $user = User::factory()->create();

        $this->actingAs($user)
            ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])
            ->assertStatus(201)
            ->assertJsonPath('data.title', 'Hello World');

        $this->assertDatabaseHas('posts', ['title' => 'Hello World', 'user_id' => $user->id]);
    }
}

使用方法

阅读各规则文件，了解详细说明和代码示例。

每个规则文件包含：

• 带有元数据（标题、影响、标签）的 YAML frontmatter
• 简要说明其重要性
• 反例及说明
• 同时提供 Pest 和 PHPUnit 示例的正例（语法不同时）
• Laravel 13 特定背景信息和参考资料

完整汇编文档

如需查看包含所有完整规则的指南：AGENTS.md