Laravel Tdd

1---2name: laravel-tdd3description: Test-driven development for Laravel with PHPUnit and Pest, factories, database testing, fakes, and coverage targets.4origin: ECC5---6 7# Laravel TDD Workflow8 9Test-driven development for Laravel applications using PHPUnit and Pest with 80%+ coverage (unit + feature).10 11## When to Use12 13- New features or endpoints in Laravel14- Bug fixes or refactors15- Testing Eloquent models, policies, jobs, and notifications16- Prefer Pest for new tests unless the project already standardizes on PHPUnit17 18## How It Works19 20### Red-Green-Refactor Cycle21 221) Write a failing test232) Implement the minimal change to pass243) Refactor while keeping tests green25 26### Test Layers27 28- **Unit**: pure PHP classes, value objects, services29- **Feature**: HTTP endpoints, auth, validation, policies30- **Integration**: database + queue + external boundaries31 32Choose layers based on scope:33 34- Use **Unit** tests for pure business logic and services.35- Use **Feature** tests for HTTP, auth, validation, and response shape.36- Use **Integration** tests when validating DB/queues/external services together.37 38### Database Strategy39 40- `RefreshDatabase` for most feature/integration tests (runs migrations once per test run, then wraps each test in a transaction when supported; in-memory databases may re-migrate per test)41- `DatabaseTransactions` when the schema is already migrated and you only need per-test rollback42- `DatabaseMigrations` when you need a full migrate/fresh for every test and can afford the cost43 44Use `RefreshDatabase` as the default for tests that touch the database: for databases with transaction support, it runs migrations once per test run (via a static flag) and wraps each test in a transaction; for `:memory:` SQLite or connections without transactions, it migrates before each test. Use `DatabaseTransactions` when the schema is already migrated and you only need per-test rollbacks.45 46### Testing Framework Choice47 48- Default to **Pest** for new tests when available.49- Use **PHPUnit** only if the project already standardizes on it or requires PHPUnit-specific tooling.50 51## Examples52 53### PHPUnit Example54 55```php56use App\Models\User;57use Illuminate\Foundation\Testing\RefreshDatabase;58use Tests\TestCase;59 60final class ProjectControllerTest extends TestCase61{62    use RefreshDatabase;63 64    public function test_owner_can_create_project(): void65    {66        $user = User::factory()->create();67 68        $response = $this->actingAs($user)->postJson('/api/projects', [69            'name' => 'New Project',70        ]);71 72        $response->assertCreated();73        $this->assertDatabaseHas('projects', ['name' => 'New Project']);74    }75}76```77 78### Feature Test Example (HTTP Layer)79 80```php81use App\Models\Project;82use App\Models\User;83use Illuminate\Foundation\Testing\RefreshDatabase;84use Tests\TestCase;85 86final class ProjectIndexTest extends TestCase87{88    use RefreshDatabase;89 90    public function test_projects_index_returns_paginated_results(): void91    {92        $user = User::factory()->create();93        Project::factory()->count(3)->for($user)->create();94 95        $response = $this->actingAs($user)->getJson('/api/projects');96 97        $response->assertOk();98        $response->assertJsonStructure(['success', 'data', 'error', 'meta']);99    }100}101```102 103### Pest Example104 105```php106use App\Models\User;107use Illuminate\Foundation\Testing\RefreshDatabase;108 109use function Pest\Laravel\actingAs;110use function Pest\Laravel\assertDatabaseHas;111 112uses(RefreshDatabase::class);113 114test('owner can create project', function () {115    $user = User::factory()->create();116 117    $response = actingAs($user)->postJson('/api/projects', [118        'name' => 'New Project',119    ]);120 121    $response->assertCreated();122    assertDatabaseHas('projects', ['name' => 'New Project']);123});124```125 126### Feature Test Pest Example (HTTP Layer)127 128```php129use App\Models\Project;130use App\Models\User;131use Illuminate\Foundation\Testing\RefreshDatabase;132 133use function Pest\Laravel\actingAs;134 135uses(RefreshDatabase::class);136 137test('projects index returns paginated results', function () {138    $user = User::factory()->create();139    Project::factory()->count(3)->for($user)->create();140 141    $response = actingAs($user)->getJson('/api/projects');142 143    $response->assertOk();144    $response->assertJsonStructure(['success', 'data', 'error', 'meta']);145});146```147 148### Factories and States149 150- Use factories for test data151- Define states for edge cases (archived, admin, trial)152 153```php154$user = User::factory()->state(['role' => 'admin'])->create();155```156 157### Database Testing158 159- Use `RefreshDatabase` for clean state160- Keep tests isolated and deterministic161- Prefer `assertDatabaseHas` over manual queries162 163### Persistence Test Example164 165```php166use App\Models\Project;167use Illuminate\Foundation\Testing\RefreshDatabase;168use Tests\TestCase;169 170final class ProjectRepositoryTest extends TestCase171{172    use RefreshDatabase;173 174    public function test_project_can_be_retrieved_by_slug(): void175    {176        $project = Project::factory()->create(['slug' => 'alpha']);177 178        $found = Project::query()->where('slug', 'alpha')->firstOrFail();179 180        $this->assertSame($project->id, $found->id);181    }182}183```184 185### Fakes for Side Effects186 187- `Bus::fake()` for jobs188- `Queue::fake()` for queued work189- `Mail::fake()` and `Notification::fake()` for notifications190- `Event::fake()` for domain events191 192```php193use Illuminate\Support\Facades\Queue;194 195Queue::fake();196 197dispatch(new SendOrderConfirmation($order->id));198 199Queue::assertPushed(SendOrderConfirmation::class);200```201 202```php203use Illuminate\Support\Facades\Notification;204 205Notification::fake();206 207$user->notify(new InvoiceReady($invoice));208 209Notification::assertSentTo($user, InvoiceReady::class);210```211 212### Auth Testing (Sanctum)213 214```php215use Laravel\Sanctum\Sanctum;216 217Sanctum::actingAs($user);218 219$response = $this->getJson('/api/projects');220$response->assertOk();221```222 223### HTTP and External Services224 225- Use `Http::fake()` to isolate external APIs226- Assert outbound payloads with `Http::assertSent()`227 228### Coverage Targets229 230- Enforce 80%+ coverage for unit + feature tests231- Use `pcov` or `XDEBUG_MODE=coverage` in CI232 233### Test Commands234 235- `php artisan test`236- `vendor/bin/phpunit`237- `vendor/bin/pest`238 239### Test Configuration240 241- Use `phpunit.xml` to set `DB_CONNECTION=sqlite` and `DB_DATABASE=:memory:` for fast tests242- Keep separate env for tests to avoid touching dev/prod data243 244### Authorization Tests245 246```php247use Illuminate\Support\Facades\Gate;248 249$this->assertTrue(Gate::forUser($user)->allows('update', $project));250$this->assertFalse(Gate::forUser($otherUser)->allows('update', $project));251```252 253### Inertia Feature Tests254 255When using Inertia.js, assert on the component name and props with the Inertia testing helpers.256 257```php258use App\Models\User;259use Inertia\Testing\AssertableInertia;260use Illuminate\Foundation\Testing\RefreshDatabase;261use Tests\TestCase;262 263final class DashboardInertiaTest extends TestCase264{265    use RefreshDatabase;266 267    public function test_dashboard_inertia_props(): void268    {269        $user = User::factory()->create();270 271        $response = $this->actingAs($user)->get('/dashboard');272 273        $response->assertOk();274        $response->assertInertia(fn (AssertableInertia $page) => $page275            ->component('Dashboard')276            ->where('user.id', $user->id)277            ->has('projects')278        );279    }280}281```282 283Prefer `assertInertia` over raw JSON assertions to keep tests aligned with Inertia responses.