laravel-testing

涵盖 Laravel 13 测试，使用 Pest 5 / PHPUnit 13（PHP 8.3 上使用 Pest 4 / PHPUnit 12）：功能测试（HTTP、全栈）、单元测试（隔离的类）和架构测试；Pest 语法（it/test/describe）、数据集；HTTP 测试（请求、JSON 断言、身份验证/actingAs、状态码/重定向断言）；数据库测试（RefreshDatabase、工厂、数据库断言）；模拟（服务、间谍、Mail/Queue/Event fake、Http::fake、时间旅行）；控制台/Artisan 命令测试；以及基于 PHPUnit 属性的数据填充（#[Seed]、#[Seeder]）。

Laravel 测试

Agent 工作流（必需）

在进行任何实现之前，并行启动 3 个 Agent，每个调用一次 Agent，并指定一个 name：

1. fuse-ai-pilot:explore-codebase - 分析现有测试模式
2. fuse-ai-pilot:research-expert - 通过 Context7 验证 Pest/PHPUnit 文档
3. mcp__context7__query-docs - 检查断言和模拟模式

实现后，运行 fuse-ai-pilot:sniper 进行验证。

---

概览

类型	用途	位置
功能	HTTP、全栈	tests/Feature/
单元	隔离的类	tests/Unit/
架构	代码架构	tests/Arch.php

---

决策指南：测试类型

What to test?
├── HTTP endpoint → Feature test
├── Service/Policy logic → Unit test
├── Code structure → Arch test
├── External API → Mock with Http::fake()
├── Mail/Queue/Event → Use Fakes
└── Database state → assertDatabaseHas()

---

决策指南：测试策略

Coverage strategy?
├── Feature tests (70%) → Critical flows
├── Unit tests (25%) → Business logic
├── E2E tests (5%) → User journeys
└── Arch tests → Structural rules

---

关键规则

1. 使用 RefreshDatabase 实现数据库隔离
2. 使用工厂创建测试数据（绝不直接插入）
3. 模拟外部服务 - 绝不调用真实 API
4. 测试边界情况 - 空值、null、边界条件
5. 并行运行 - 使用 pest --parallel 提速

---

参考指南

Pest 基础

主题	参考	适用场景
Pest 语法	pest-basics.md	it()、test()、describe()
数据集	pest-datasets.md	数据提供器、钩子
架构	pest-arch.md	arch() 测试

HTTP 测试

主题	参考	适用场景
请求	http-requests.md	GET、POST、请求头
JSON API	http-json.md	API 断言
身份验证	http-auth.md	actingAs、守卫
断言	http-assertions.md	状态码、重定向

数据库测试

主题	参考	适用场景
基础	database-basics.md	RefreshDatabase
工厂	database-factories.md	工厂模式
断言	database-assertions.md	数据库断言

模拟

主题	参考	适用场景
服务	mocking-services.md	模拟、间谍
伪造	mocking-fakes.md	Mail、Queue、Event
HTTP 和时间	mocking-http.md	Http::fake、时间旅行

其他

主题	参考	适用场景
控制台	console-tests.md	Artisan 测试
故障排除	troubleshooting.md	常见错误

模板

模板	使用场景
FeatureTest.php.md	HTTP 功能测试
UnitTest.php.md	服务单元测试
ArchTest.php.md	架构测试
ApiTest.php.md	REST API 测试
PestConfig.php.md	Pest 配置

---

快速参考

// Feature test
it('creates a post', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->postJson('/api/posts', ['title' => 'Test'])
        ->assertCreated()
        ->assertJsonPath('data.title', 'Test');

    $this->assertDatabaseHas('posts', ['title' => 'Test']);
});

// With dataset
it('validates emails', function (string $email, bool $valid) {
    // test logic
})->with([
    ['[email protected]', true],
    ['invalid', false],
]);

// Mock facade
Mail::fake();
// ... action ...
Mail::assertSent(OrderShipped::class);

---

命令

# Run all tests
php artisan test

# Pest directly
./vendor/bin/pest

# Parallel execution
./vendor/bin/pest --parallel

# Filter by name
./vendor/bin/pest --filter "user can"

# Coverage
./vendor/bin/pest --coverage --min=80

# Profile slow tests
./vendor/bin/pest --profile

---

最佳实践

DO

• 使用 RefreshDatabase 特征
• 遵循 AAA 模式（Arrange-Act-Assert）
• 为测试取描述性名称
• 每个测试只测一件事
• 使用工厂创建数据

DON'T

• 创建测试依赖项
• 调用真实的外部 API
• 使用生产数据库
• 跳过边界情况

---

Laravel 13 说明

PHPUnit 12/13 + Pest 4/5

Laravel 13 骨架自带 PHPUnit 12（^12.5）；该框架也支持 PHPUnit 13。Pest 5（当前版本，需要 PHP 8.4+ 和 PHPUnit 13，此外还需要 pestphp/pest-plugin-laravel ^5.0，其要求 Laravel ^13.23）——如果应用仍运行 PHP 8.3，请继续使用 Pest 4（PHPUnit 12）。PHP 属性取代了文档块注释。

use PHPUnit\Framework\Attributes\Test;
use Illuminate\Foundation\Testing\Attributes\Seed;
use Illuminate\Foundation\Testing\Attributes\Seeder;

#[Seed]                          // runs DatabaseSeeder
#[Seeder(UserSeeder::class)]     // runs a targeted seeder
final class UserTest extends TestCase
{
    #[Test]
    public function it_creates_user(): void { /* ... */ }
}

Str 工厂重置

Laravel 13 会在测试拆卸时重置自定义 Str 工厂（UUID / ULID / 随机字符串）。依赖工厂在多个方法间保持状态的测试，必须在每个测试或设置钩子中设置工厂。

#[UnitTest]（L13）

在测试方法上使用 Illuminate\Foundation\Testing\Attributes\UnitTest，可跳过该测试的应用启动过程。

从 Pest 3 迁移到 4

• 将 pestphp/pest 和所有 Pest 插件升级到 ^4.0（PHP 8.3+、PHPUnit 12）
• 快照名称已更改：运行 ./vendor/bin/pest --update-snapshots
• pest-plugin-watch 和 pest-plugin-faker 已归档

从 Pest 4 迁移到 5

• 需要 PHP 8.4+；将 pestphp/pest 和所有 Pest 插件升级到 ^5.0（基于 PHPUnit 13）
• 5 中新增：--tia（测试影响分析，仅限本地）、一方 PHPStan/Rector 插件、Agent 和 Evals 插件、时间均衡分片