Agent skill

laravel-tdd

使用 PHPUnit 和 Pest、工厂、数据库测试、模拟以及覆盖率目标进行 Laravel 的测试驱动开发。

View SKILL.md on GitHub Repository
Stars 132,726
Forks 19,206

Install this agent skill to your Project

npx add-skill https://github.com/affaan-m/everything-claude-code/tree/main/docs/zh-CN/skills/laravel-tdd

SKILL.md

Laravel TDD 工作流

使用 PHPUnit 和 Pest 为 Laravel 应用程序进行测试驱动开发，覆盖率（单元 + 功能）达到 80% 以上。

使用时机

  • Laravel 中的新功能或端点
  • 错误修复或重构
  • 测试 Eloquent 模型、策略、作业和通知
  • 除非项目已标准化使用 PHPUnit，否则新测试首选 Pest

工作原理

红-绿-重构循环

  1. 编写一个失败的测试
  2. 实施最小更改以通过测试
  3. 在保持测试通过的同时进行重构

测试层级

  • 单元：纯 PHP 类、值对象、服务
  • 功能：HTTP 端点、身份验证、验证、策略
  • 集成：数据库 + 队列 + 外部边界

根据范围选择层级：

  • 对纯业务逻辑和服务使用单元测试。
  • 对 HTTP、身份验证、验证和响应结构使用功能测试。
  • 当需要验证数据库/队列/外部服务组合时使用集成测试。

数据库策略

  • 对于大多数功能/集成测试使用 RefreshDatabase（每次测试运行运行一次迁移，然后在支持时将每个测试包装在事务中；内存数据库可能每次测试重新迁移）
  • 当模式已迁移且仅需要每次测试回滚时使用 DatabaseTransactions
  • 当每次测试都需要完整迁移/刷新且可以承担其开销时使用 DatabaseMigrations

将 RefreshDatabase 作为触及数据库的测试的默认选择：对于支持事务的数据库，它每次测试运行运行一次迁移（通过静态标志）并将每个测试包装在事务中；对于 :memory: SQLite 或不支持事务的连接，它在每次测试前进行迁移。当模式已迁移且仅需要每次测试回滚时使用 DatabaseTransactions。

测试框架选择

  • 新测试默认使用 Pest（当可用时）。
  • 仅在项目已标准化使用它或需要 PHPUnit 特定工具时使用 PHPUnit。

示例

PHPUnit 示例

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

final class ProjectControllerTest extends TestCase
{
    use RefreshDatabase;

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

        $response = $this->actingAs($user)->postJson('/api/projects', [
            'name' => 'New Project',
        ]);

        $response->assertCreated();
        $this->assertDatabaseHas('projects', ['name' => 'New Project']);
    }
}

功能测试示例（HTTP 层）

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

final class ProjectIndexTest extends TestCase
{
    use RefreshDatabase;

    public function test_projects_index_returns_paginated_results(): void
    {
        $user = User::factory()->create();
        Project::factory()->count(3)->for($user)->create();

        $response = $this->actingAs($user)->getJson('/api/projects');

        $response->assertOk();
        $response->assertJsonStructure(['success', 'data', 'error', 'meta']);
    }
}

Pest 示例

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

use function Pest\Laravel\actingAs;
use function Pest\Laravel\assertDatabaseHas;

uses(RefreshDatabase::class);

test('owner can create project', function () {
    $user = User::factory()->create();

    $response = actingAs($user)->postJson('/api/projects', [
        'name' => 'New Project',
    ]);

    $response->assertCreated();
    assertDatabaseHas('projects', ['name' => 'New Project']);
});

Pest 功能测试示例（HTTP 层）

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

use function Pest\Laravel\actingAs;

uses(RefreshDatabase::class);

test('projects index returns paginated results', function () {
    $user = User::factory()->create();
    Project::factory()->count(3)->for($user)->create();

    $response = actingAs($user)->getJson('/api/projects');

    $response->assertOk();
    $response->assertJsonStructure(['success', 'data', 'error', 'meta']);
});

工厂和状态

  • 使用工厂生成测试数据
  • 为边缘情况定义状态（已归档、管理员、试用）
php
$user = User::factory()->state(['role' => 'admin'])->create();

数据库测试

  • 使用 RefreshDatabase 保持干净状态
  • 保持测试隔离和确定性
  • 优先使用 assertDatabaseHas 而非手动查询

持久性测试示例

php
use App\Models\Project;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

final class ProjectRepositoryTest extends TestCase
{
    use RefreshDatabase;

    public function test_project_can_be_retrieved_by_slug(): void
    {
        $project = Project::factory()->create(['slug' => 'alpha']);

        $found = Project::query()->where('slug', 'alpha')->firstOrFail();

        $this->assertSame($project->id, $found->id);
    }
}

副作用模拟

  • 作业使用 Bus::fake()
  • 队列工作使用 Queue::fake()
  • 通知使用 Mail::fake() 和 Notification::fake()
  • 领域事件使用 Event::fake()
php
use Illuminate\Support\Facades\Queue;

Queue::fake();

dispatch(new SendOrderConfirmation($order->id));

Queue::assertPushed(SendOrderConfirmation::class);
php
use Illuminate\Support\Facades\Notification;

Notification::fake();

$user->notify(new InvoiceReady($invoice));

Notification::assertSentTo($user, InvoiceReady::class);

身份验证测试（Sanctum）

php
use Laravel\Sanctum\Sanctum;

Sanctum::actingAs($user);

$response = $this->getJson('/api/projects');
$response->assertOk();

HTTP 和外部服务

  • 使用 Http::fake() 隔离外部 API
  • 使用 Http::assertSent() 断言出站负载

覆盖率目标

  • 对单元 + 功能测试强制执行 80% 以上的覆盖率
  • 在 CI 中使用 pcov 或 XDEBUG_MODE=coverage

测试命令

  • php artisan test
  • vendor/bin/phpunit
  • vendor/bin/pest

测试配置

  • 使用 phpunit.xml 设置 DB_CONNECTION=sqlite 和 DB_DATABASE=:memory: 以进行快速测试
  • 为测试保持独立的环境，以避免触及开发/生产数据

授权测试

php
use Illuminate\Support\Facades\Gate;

$this->assertTrue(Gate::forUser($user)->allows('update', $project));
$this->assertFalse(Gate::forUser($otherUser)->allows('update', $project));

Inertia 功能测试

使用 Inertia.js 时，使用 Inertia 测试辅助函数来断言组件名称和属性。

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

final class DashboardInertiaTest extends TestCase
{
    use RefreshDatabase;

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

        $response = $this->actingAs($user)->get('/dashboard');

        $response->assertOk();
        $response->assertInertia(fn (AssertableInertia $page) => $page
            ->component('Dashboard')
            ->where('user.id', $user->id)
            ->has('projects')
        );
    }
}

优先使用 assertInertia 而非原始 JSON 断言，以保持测试与 Inertia 响应一致。

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

affaan-m/everything-claude-code

python-testing

Python testing best practices using pytest including fixtures, parametrization, mocking, coverage analysis, async testing, and test organization. Use when writing or improving Python tests.

132,726 19,206
Explore
affaan-m/everything-claude-code

golang-patterns

Go-specific design patterns and best practices including functional options, small interfaces, dependency injection, concurrency patterns, error handling, and package organization. Use when working with Go code to apply idiomatic Go patterns.

132,726 19,206
Explore
affaan-m/everything-claude-code

e2e-testing

Playwright E2E testing patterns, Page Object Model, configuration, CI/CD integration, artifact management, and flaky test strategies.

132,726 19,206
Explore
affaan-m/everything-claude-code

agentic-engineering

Operate as an agentic engineer using eval-first execution, decomposition, and cost-aware model routing. Use when AI agents perform most implementation work and humans enforce quality and risk controls.

132,726 19,206
Explore
affaan-m/everything-claude-code

api-design

REST API design patterns including resource naming, status codes, pagination, filtering, error responses, versioning, and rate limiting for production APIs.

132,726 19,206
Explore
affaan-m/everything-claude-code

python-patterns

Python-specific design patterns and best practices including protocols, dataclasses, context managers, decorators, async/await, type hints, and package organization. Use when working with Python code to apply Pythonic patterns.

132,726 19,206
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results