Laravel TDD Workflow

Test-driven development for Laravel applications using PHPUnit and Pest with 80%+ coverage (unit + feature).

When to Use

• New features or endpoints in Laravel
• Bug fixes or refactors
• Testing Eloquent models, policies, jobs, and notifications
• Prefer Pest for new tests unless the project already standardizes on PHPUnit

How It Works

Red-Green-Refactor Cycle

1. Write a failing test
2. Implement the minimal change to pass
3. Refactor while keeping tests green

Test Layers

• Unit: pure PHP classes, value objects, services
• Feature: HTTP endpoints, auth, validation, policies
• Integration: database + queue + external boundaries

Choose layers based on scope:

• Use Unit tests for pure business logic and services.
• Use Feature tests for HTTP, auth, validation, and response shape.
• Use Integration tests when validating DB/queues/external services together.

Database Strategy

• 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)
• DatabaseTransactions when the schema is already migrated and you only need per-test rollback
• DatabaseMigrations when you need a full migrate/fresh for every test and can afford the cost

Use 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.

Testing Framework Choice

• Default to Pest for new tests when available.
• Use PHPUnit only if the project already standardizes on it or requires PHPUnit-specific tooling.

Examples

PHPUnit Example

php
1use App\Models\User;
2use Illuminate\Foundation\Testing\RefreshDatabase;
3use Tests\TestCase;
4
5final class ProjectControllerTest extends TestCase
6{
7    use RefreshDatabase;
8
9    public function test_owner_can_create_project(): void
10    {
11        $user = User::factory()->create();
12
13        $response = $this->actingAs($user)->postJson('/api/projects', [
14            'name' => 'New Project',
15        ]);
16
17        $response->assertCreated();
18        $this->assertDatabaseHas('projects', ['name' => 'New Project']);
19    }
20}

Feature Test Example (HTTP Layer)

php
1use App\Models\Project;
2use App\Models\User;
3use Illuminate\Foundation\Testing\RefreshDatabase;
4use Tests\TestCase;
5
6final class ProjectIndexTest extends TestCase
7{
8    use RefreshDatabase;
9
10    public function test_projects_index_returns_paginated_results(): void
11    {
12        $user = User::factory()->create();
13        Project::factory()->count(3)->for($user)->create();
14
15        $response = $this->actingAs($user)->getJson('/api/projects');
16
17        $response->assertOk();
18        $response->assertJsonStructure(['success', 'data', 'error', 'meta']);
19    }
20}

Pest Example

php
1use App\Models\User;
2use Illuminate\Foundation\Testing\RefreshDatabase;
3
4use function Pest\Laravel\actingAs;
5use function Pest\Laravel\assertDatabaseHas;
6
7uses(RefreshDatabase::class);
8
9test('owner can create project', function () {
10    $user = User::factory()->create();
11
12    $response = actingAs($user)->postJson('/api/projects', [
13        'name' => 'New Project',
14    ]);
15
16    $response->assertCreated();
17    assertDatabaseHas('projects', ['name' => 'New Project']);
18});

Feature Test Pest Example (HTTP Layer)

php
1use App\Models\Project;
2use App\Models\User;
3use Illuminate\Foundation\Testing\RefreshDatabase;
4
5use function Pest\Laravel\actingAs;
6
7uses(RefreshDatabase::class);
8
9test('projects index returns paginated results', function () {
10    $user = User::factory()->create();
11    Project::factory()->count(3)->for($user)->create();
12
13    $response = actingAs($user)->getJson('/api/projects');
14
15    $response->assertOk();
16    $response->assertJsonStructure(['success', 'data', 'error', 'meta']);
17});

Factories and States

• Use factories for test data
• Define states for edge cases (archived, admin, trial)

php
1$user = User::factory()->state(['role' => 'admin'])->create();

Database Testing

• Use RefreshDatabase for clean state
• Keep tests isolated and deterministic
• Prefer assertDatabaseHas over manual queries

Persistence Test Example

php
1use App\Models\Project;
2use Illuminate\Foundation\Testing\RefreshDatabase;
3use Tests\TestCase;
4
5final class ProjectRepositoryTest extends TestCase
6{
7    use RefreshDatabase;
8
9    public function test_project_can_be_retrieved_by_slug(): void
10    {
11        $project = Project::factory()->create(['slug' => 'alpha']);
12
13        $found = Project::query()->where('slug', 'alpha')->firstOrFail();
14
15        $this->assertSame($project->id, $found->id);
16    }
17}

Fakes for Side Effects

• Bus::fake() for jobs
• Queue::fake() for queued work
• Mail::fake() and Notification::fake() for notifications
• Event::fake() for domain events

php
1use Illuminate\Support\Facades\Queue;
2
3Queue::fake();
4
5dispatch(new SendOrderConfirmation($order->id));
6
7Queue::assertPushed(SendOrderConfirmation::class);

php
1use Illuminate\Support\Facades\Notification;
2
3Notification::fake();
4
5$user->notify(new InvoiceReady($invoice));
6
7Notification::assertSentTo($user, InvoiceReady::class);

Auth Testing (Sanctum)

php
1use Laravel\Sanctum\Sanctum;
2
3Sanctum::actingAs($user);
4
5$response = $this->getJson('/api/projects');
6$response->assertOk();

HTTP and External Services

• Use Http::fake() to isolate external APIs
• Assert outbound payloads with Http::assertSent()

Coverage Targets

• Enforce 80%+ coverage for unit + feature tests
• Use pcov or XDEBUG_MODE=coverage in CI

Test Commands

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

Test Configuration

• Use phpunit.xml to set DB_CONNECTION=sqlite and DB_DATABASE=:memory: for fast tests
• Keep separate env for tests to avoid touching dev/prod data

Authorization Tests

php
1use Illuminate\Support\Facades\Gate;
2
3$this->assertTrue(Gate::forUser($user)->allows('update', $project));
4$this->assertFalse(Gate::forUser($otherUser)->allows('update', $project));

Inertia Feature Tests

When using Inertia.js, assert on the component name and props with the Inertia testing helpers.

php
1use App\Models\User;
2use Inertia\Testing\AssertableInertia;
3use Illuminate\Foundation\Testing\RefreshDatabase;
4use Tests\TestCase;
5
6final class DashboardInertiaTest extends TestCase
7{
8    use RefreshDatabase;
9
10    public function test_dashboard_inertia_props(): void
11    {
12        $user = User::factory()->create();
13
14        $response = $this->actingAs($user)->get('/dashboard');
15
16        $response->assertOk();
17        $response->assertInertia(fn (AssertableInertia $page) => $page
18            ->component('Dashboard')
19            ->where('user.id', $user->id)
20            ->has('projects')
21        );
22    }
23}

Prefer assertInertia over raw JSON assertions to keep tests aligned with Inertia responses.