laravel-testing

用途

该技能是面向 Laravel 13 应用的测试编写指南，用于在编写或审查测试代码时提供统一规范。触发场景包括：为 Laravel 编写特性测试或单元测试、测试 HTTP 端点与 API 响应、创建工厂与测试数据、断言操作后的数据库状态、伪造 Mail/Queue/Notification/Event 门面、测试需要认证的路由与 API 令牌，以及使用 describe 块、数据集或测试类组织测试。

主要能力

技能包含 6 个类别、共 24 条规则，按优先级排列：

HTTP 与特性测试（CRITICAL，前缀 http-）：http-test-structure（使用工厂的 Arrange/Act/Assert 结构，含 Pest 与 PHPUnit 示例）、http-assert-response（assertStatus、assertJson、assertRedirect、assertJsonMissing）、http-assert-json-fluent（通过 AssertableJson 闭包的流式断言）、http-refresh-database（RefreshDatabase 与 DatabaseTransactions 的使用取舍）。
模型工厂（CRITICAL，前缀 factory-）：factory-define（使用类型化假数据与 PHP 8.3 语法定义工厂）、factory-states（为不同测试场景定义工厂状态）、factory-sequences（用 sequence() 为多条记录生成变化数据）、factory-relationships（has()、for()、recycle()、afterCreating()）。
数据库断言（HIGH，前缀 db-）：db-assert-has（assertDatabaseHas、assertModelExists 等存在性断言）、db-assert-missing（assertDatabaseMissing、assertModelMissing 等删除断言）、db-assert-soft-deletes（assertSoftDeleted、trashed() 工厂状态）。
服务伪造（HIGH，前缀 fake-）：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+）。
认证测试（HIGH，前缀 auth-）：auth-acting-as（actingAs() 用于会话/Web 认证测试）、auth-sanctum（Sanctum::actingAs() 用于 API 令牌认证）。
测试组织模式（MEDIUM，前缀 pest-）：pest-describe-it（Pest 的 describe()/it() 或 PHPUnit 的测试类组织）、pest-datasets（Pest 的 with() 数据集或 PHPUnit 的 #[DataProvider]）、pest-hooks（Pest 的 beforeEach/afterEach 或 PHPUnit 的 setUp/tearDown）。

使用方式

框架判定：在编写或审查测试代码前，先检测项目使用哪个测试框架。

步骤 1：检查 composer.json 的 require-dev。若存在 pestphp/pest 则使用 Pest 语法；若仅有 phpunit/phpunit（无 pest）则使用 PHPUnit 语法；若两者同时存在，Pest 优先（Pest 运行在 PHPUnit 之上）。
步骤 2：检查是否存在 tests/Pest.php。若存在，说明已配置 Pest，使用 Pest 语法。
步骤 3：若仍不明确，询问用户："I couldn't detect the testing framework. Does this project use Pest PHP or PHPUnit?"

语法对照（Pest 与 PHPUnit）：

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

核心断言在两个框架中相同：assertStatus、assertJson、assertJsonPath、assertDatabaseHas、assertModelExists、actingAs、Mail::fake()、Queue::fake()、Event::fake()、Notification::fake()、Storage::fake() 在 Pest 与 PHPUnit 中用法一致。

阅读方式：按需阅读单条规则文件获取详细说明与代码示例，每个规则文件包含 YAML frontmatter 元数据（标题、影响等级、标签）、为什么重要的简要说明、带解释的反面示例、Pest 与 PHPUnit 语法不同处的正面示例（两者均给出），以及 Laravel 13 特定上下文与参考。完整展开所有规则的指南见 AGENTS.md。

示例（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]);
    }
}

适用场景

Laravel 13 应用中的测试编写与审查，包括特性测试、单元测试、API 接口测试、数据库与模型断言、外部服务伪造、认证测试，以及测试代码的组织与结构优化。同时支持 Pest PHP 4 与 PHPUnit 12（Laravel 13 默认），并可兼容 PHPUnit 11、12、13。

限制

资料中未提供安装命令、包名依赖的安装方式、技能的具体分发形式或运行环境要求，暂未提供。规则文件的具体内容（除已列出的规则名称与部分 API 名称外）未完整给出，需参阅各规则文件与 AGENTS.md。

技能介绍

用途

主要能力

使用方式

适用场景

限制