laravel-tdd

name	laravel-tdd
description	Laravel testing strategies with PHPUnit, Pest, model factories, HTTP tests, Sanctum authentication testing, mocking, and coverage. Use when writing Laravel tests with PHPUnit or Pest, or driving a Laravel feature test-first.
metadata	{"origin":"ECC"}

Laravel Testing with TDD

Test-driven development for Laravel applications using PHPUnit, Pest, Laravel factories, and testing helpers.

When to Activate

• Writing new Laravel applications or features
• Implementing API endpoints with Sanctum or Passport authentication
• Testing Eloquent models, relationships, scopes, and accessors
• Setting up testing infrastructure for Laravel projects
• Writing feature tests for HTTP controllers and form requests
• Mocking external services (queues, mail, notifications, HTTP)

TDD Workflow for Laravel

Red-Green-Refactor Cycle

// Step 1: RED — Write a failing test
public function test_a_product_can_be_created(): void
{
    $product = Product::factory()->create(['name' => 'Test Product']);
    $this->assertDatabaseHas('products', ['name' => 'Test Product']);
}

// Step 2: GREEN — Write the migration, model, and factory
// Step 3: REFACTOR — Improve while keeping tests green

Setup

PHPUnit Configuration

<?xml version="1.0" encoding="UTF-8"?>
<phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
         bootstrap="vendor/autoload.php"
         colors="true">
    <testsuites>
        <testsuite name="Unit">
            <directory suffix="Test.php">tests/Unit</directory>
        </testsuite>
        <testsuite name="Feature">
            <directory suffix="Test.php">tests/Feature</directory>
        </testsuite>
    </testsuites>
    <php>
        <env name="APP_ENV" value="testing"/>
        <env name="BCRYPT_ROUNDS" value="4"/>
        <env name= =/>
        
        
        
        
        
    

Base TestCase Setup

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;

abstract class TestCase extends BaseTestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        // Call $this->withoutExceptionHandling() only in tests that
        // test non-HTTP exceptions; it suppresses assertStatus() etc.
    }

    // Helper: Authenticate and return user
    protected function actingAsUser(): mixed
    {
        $user = \App\Models\User::factory()->create();
        $this->actingAs($user);
        return $user;
    }

    protected function actingAsAdmin(): mixed
    {
        $admin = \App\Models\User::factory()->admin()->create();
        ->();
         ;
    }
}

Model Factories

// database/factories/UserFactory.php
class UserFactory extends Factory
{
    protected static ?string $password = null;

    public function definition(): array
    {
        return [
            'name' => fake()->name(),
            'email' => fake()->unique()->safeEmail(),
            'email_verified_at' => now(),
            'password' => static::$password ??= Hash::make('password'),
            'remember_token' => Str::random(10),
            'role' => 'user',
        ];
    }

    public function admin(): static
    {
        return $this->state(fn (array $attributes) => ['role' => 'admin']);
    }

     {
         ->(fn ( ) => [ => ]);
    }
}


{
     {
         [
             => ()->()->(, ),
             =>  ::([]),
             => ()->(),
             => ()->(, ),
             => ()->(, ),
             => ,
             => ::(),
        ];
    }

     {
         ->(fn ( ) => [ => ]);
    }
}

Using Factories

$user = User::factory()->create();
$admin = User::factory()->admin()->create();
$product = Product::factory()->create(['user_id' => $user->id]);
$products = Product::factory()->count(10)->create();
$draft = Product::factory()->make(); // Not persisted

// With relationships
$user = User::factory()->has(Product::factory()->count(3))->create();

// Sequences
User::factory()->count(3)->sequence(
    ['role' => 'admin'], ['role' => 'editor'], ['role' => 'user'],
)->create();

Model Testing

namespace Tests\Unit\Models;

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

class UserTest extends TestCase
{
    use RefreshDatabase;

    public function test_it_hides_sensitive_attributes(): void
    {
        $user = User::factory()->create();
        $this->assertArrayNotHasKey('password', $user->toArray());
    }

    public function test_admin_scope_returns_only_admins(): void
    {
        User::factory()->admin()->create();
        User::factory()->()->();

        ->(, ::()->());
    }
}

{
     ;

     {
        ::()->()->([ => ]);
        ::()->()->([ => ]);

        ->(, ::()->());
    }

     {
         = ::()->();
         = ::()->([ => ->id]);

        ->(->user->());
    }
}

Feature / HTTP Testing

namespace Tests\Feature\Http\Controllers;

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

class ProductControllerTest extends TestCase
{
    use RefreshDatabase;

    public function test_guests_are_redirected_to_login(): void
    {
        $this->get(route('products.create'))->assertRedirect(route('login'));
    }

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

         = ->((), [
             => ,
             => ,
             => ,
             => ,
        ]);

        ->(());
        ->(, [
             => ,
             => ->id,
        ]);
    }

     {
        ->(::()->());
        ->((), [])
            ->([, ]);
    }

     {
         = ::()->();
         = ::()->();
         = ::()->([ => ->id]);

        ->()
            ->((, ))
            ->();
    }
}

JSON API Testing

namespace Tests\Feature\Http\Controllers\Api;

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

class ProductApiTest extends TestCase
{
    use RefreshDatabase;

    public function test_unauthenticated_requests_are_rejected(): void
    {
        $this->getJson('/api/products')->assertUnauthorized();
    }

    public function test_it_lists_paginated_products(): void
    {
        $user = User::factory()->create();
        Product::factory()->count(5)->create([ => ->id]);

         = ->()->();

        ->();
        ->(, );
        ->([
             => [[, , ]],
             => [, , ],
        ]);
    }

     {
         = ::()->();

         = ->()->(, [
             => ,
             => ,
        ]);

        ->();
        ->(, );
    }

     {
         = ::()->();
         = ::()->();
         = ::()->([ => ->id]);

        ->()
            ->()
            ->();
    }
}

Sanctum API Auth Testing

namespace Tests\Feature\Http\Controllers\Api;

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Hash;
use Tests\TestCase;

class AuthControllerTest extends TestCase
{
    use RefreshDatabase;

    public function test_users_can_register(): void
    {
        $response = $this->postJson('/api/register', [
            'name' => 'Test User',
            'email' => '[e-mail]',
            'password' => 'Password123!',
            'password_confirmation' => 'Password123!',
        ]);

        $response->assertCreated();
        $response->assertJsonStructure(['data' => [, ]]);
    }

     {
        ::()->([
             => ,
             => ::(),
        ]);

         = ->(, [
             => ,
             => ,
        ]);

        ->();
        ->([ => []]);
    }

     {
        ::()->([ => ]);

        ->(, [
             => ,
             => ,
        ])->();
    }

     {
         = ::()->();
         = ->()->plainTextToken;

        ->()
            ->()
            ->()
            ->(, ->email);
    }
}

Mocking and Fakes

HTTP Fake

use Illuminate\Support\Facades\Http;

public function test_it_handles_successful_payment(): void
{
    Http::fake([
        'api.stripe.com/*' => Http::response(['id' => 'pi_123', 'status' => 'succeeded'], 200),
    ]);

    $result = (new PaymentService())->charge(2999);
    $this->assertTrue($result->success);
}

public function test_it_handles_gateway_failure(): void
{
    Http::fake([
        'api.stripe.com/*' => Http::response(['error' => 'card_declined'], 402),
    ]);

    $this->expectException(PaymentFailedException::class);
    (new PaymentService())->charge(2999);
}

 {
    ::([
         => ::()
            ->()
            ->(),
    ]);

    ->(( ())->()->success);
}

Mail Fake

Mail::fake();

$order->sendConfirmation();

Mail::assertSent(OrderConfirmation::class, function ($mail) use ($order) {
    return $mail->hasTo($order->user->email);
});

Notification Fake

Notification::fake();

$user->notify(new WelcomeUser());

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

Queue Fake

Queue::fake();

ProcessImage::dispatch($product);

Queue::assertPushed(ProcessImage::class, function ($job) use ($product) {
    return $job->product->id === $product->id;
});

Storage Fake

Storage::fake('public');

$file = UploadedFile::fake()->image('photo.jpg', 200, 200);

$response = $this->actingAs($user)->post('/avatar', [
    'avatar' => $file,
]);

$response->assertSessionHasNoErrors();
Storage::disk('public')->assertExists('avatars/' . $file->hashName());

Event Fake

Event::fake();

$order->markAsShipped();

Event::assertDispatched(OrderShipped::class, function ($event) use ($order) {
    return $event->order->id === $order->id;
});

Artisan Command Tests

public function test_it_sends_newsletters(): void
{
    Mail::fake();
    User::factory()->count(5)->create(['subscribed' => true]);

    $this->artisan('newsletter:send')
        ->expectsOutput('Sending newsletter to 5 subscribers...')
        ->assertExitCode(0);

    Mail::assertSent(NewsletterMail::class, 5);
}

public function test_it_handles_no_subscribers(): void
{
    $this->artisan('newsletter:send')
        ->expectsOutput('No subscribers found.')
        ->assertExitCode(0);
}

Authorization Tests

public function test_users_can_update_own_posts(): void
{
    $user = User::factory()->create();
    $post = Post::factory()->create(['user_id' => $user->id]);

    $this->actingAs($user)
        ->put(route('posts.update', $post), ['title' => 'Updated'])
        ->assertRedirect();
}

public function test_users_cannot_update_others_posts(): void
{
    $post = Post::factory()->create();
    $this->actingAs(User::factory()->create())
        ->put(route('posts.update', $post), ['title' => 'Hacked'])
        ->assertForbidden();
}

public {
     = ::()->([ => ]);
     = ::()->();

    ->()
        ->((, ))
        ->();

    ->();
}

Pest Feature Tests

<?php

use App\Models\Product;
use App\Models\User;

uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);

beforeEach(function () {
    $this->user = User::factory()->create();
    $this->actingAs($this->user);
});

it('lists products', function () {
    Product::factory()->count(3)->create(['user_id' => $this->user->id]);

    $this->get(route('products.index'))
        ->assertOk()
        ->assertViewHas('products');
});

it('creates a product with valid data', function () {
    $this->post(route('products.store'), [
        'name' => 'Test Product', 'price' => 1999,
    ])->assertRedirect();

    ->(, [ => ]);
});

(, function () {
    ->((), [])
        ->([, ]);
});

(, function () {
     = ::()->();
     = ::()->([ => ->id]);

    ->((, ), [ => ])
        ->();
});

Coverage

# PHPUnit (use clover output for CI threshold checks)
vendor/bin/phpunit --coverage-html coverage --coverage-clover clover.xml

# Pest (built-in threshold support)
vendor/bin/pest --coverage --min=80

Coverage Goals

Component	Target
Models	95%+
Actions/Services	90%+
Form Requests	90%+
Controllers	85%+
Policies	95%+
Overall	80%+

Testing Best Practices

DO

• Use factories over manual create() calls
• One logical assertion per test
• Descriptive names: test_guests_cannot_create_products
• Test edge cases and authorization boundaries
• Mock external services with Http::fake(), Mail::fake()
• Use RefreshDatabase for clean state

DON'T

• Don't test Laravel internals (trust the framework)
• Don't make tests dependent on each other
• Don't over-mock — mock only service boundaries
• Don't test private methods — test through the public interface
• Don't couple tests to HTML structure

Quick Reference

Pattern	Usage
RefreshDatabase	Reset database between tests
$this->actingAs($user)	Authenticate as user
$this->withToken($token)	Bearer token auth for APIs
Model::factory()->create()	Create model with factory
Model::factory()->count(5)->create()	Create multiple records
Http::fake([...])	Mock HTTP calls
Mail::fake()	Trap sent mail
Notification::fake()	Trap sent notifications
Queue::fake()	Trap queued jobs
Event::fake()	Trap dispatched events
Storage::fake('public')	Trap file operations
assertDatabaseHas	Assert DB row exists
assertSoftDeleted	Assert soft-delete
assertSessionHasErrors	Assert validation errors
assertForbidden	Assert 403 status

Related Skills

• laravel-patterns — Laravel architecture, Eloquent, routing, and API patterns
• laravel-security — Laravel authentication, authorization, and secure coding
• tdd-workflow — The repo-wide RED -> GREEN -> REFACTOR loop
• backend-patterns — General backend API and database patterns