Testing Laravel

Testing Laravel

Use PHPUnit with Laravel's testing helpers. Every test file starts with declare(strict_types=1).

Test Classification

• Feature tests (tests/Feature/): HTTP requests through the full stack — routes, controllers, middleware, validation, database. Use $this->getJson(), $this->postJson(), etc.
• Unit tests (tests/Unit/): Isolated logic — services, actions, value objects, helpers. No HTTP, minimal database.

Default to feature tests for anything touching routes, controllers, or models. Use unit tests for pure logic and action classes.

Critical Rules

• use RefreshDatabase trait in every test class that touches the database
• Model factories for all test data — use factories instead of raw DB::table() inserts
• One behavior per test method. Name with test_ prefix: test_user_can_update_own_profile
• Assert both response status AND side effects (DB state, dispatched jobs, sent notifications)
• actingAs($user) for auth — use this instead of manually setting sessions or tokens
• postJson() / getJson() for API endpoints — sets proper Accept headers and returns JSON assertions
• Fake facades BEFORE the action: Queue::fake() then act then Queue::assertPushed(...)
• assertDatabaseHas / assertDatabaseMissing to verify persistence — use these instead of re-querying
• Resolve action classes from the container with resolve() so DI works; use swap() to inject mocks
• Tests expose bugs, not the reverse: If a test uncovers broken or buggy behavior, highlight the issue and propose a fix to the source code. Never adjust the test to match incorrect behavior.

PHPUnit Essentials

<?php

declare(strict_types=1);

namespace Tests\Feature;

use App\Models\{User, Post};
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;

final class PostTest extends TestCase
{
    use RefreshDatabase;

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

        $response = $this->actingAs($user)
            ->postJson('/api/posts', ['title' => 'New Post', 'body' => 'Content']);

        $response->assertCreated()
            ->assertJson(['data' => ['title' => 'New Post']]);

        $this->assertDatabaseHas('posts', [
            'title' => 'New Post',
            'user_id' => $user->id,
        ]);
    }
}

Data providers for boundary/validation testing:

#[DataProvider('titleLengthProvider')]
public function test_validates_title_length(string $title, bool $valid): void
{
    $user = User::factory()->create();
    $response = $this->actingAs($user)
        ->postJson('/api/posts', ['title' => $title, 'body' => 'Content']);

    $valid ? $response->assertCreated() : $response->assertUnprocessable();
}

public static function titleLengthProvider(): array
{
    return [
        'too short' => ['AB', false],
        'minimum valid' => ['ABC', true],
        'maximum valid' => [str_repeat('A', 255), true],
        'too long' => [str_repeat('A', 256), false],
    ];
}

See feature testing patterns for auth, validation, API, console, and DB assertions.

See mocking and faking for facade fakes (Queue, Event, Notification, Mail, Storage, Http), action mocking with swap(), and Mockery.

See factories for states, relationships, sequences, and afterCreating hooks.

Running Tests

For large test suites, call PHPUnit directly to avoid artisan's memory overhead:

./vendor/bin/phpunit                              # all tests (direct, lower memory)
./vendor/bin/phpunit --filter=PostTest             # by name
./vendor/bin/phpunit --processes=auto              # parallel (PHPUnit 11+)
./vendor/bin/phpunit --coverage-text --min=80      # with coverage threshold

php artisan test                                   # small suites or quick runs
php -d memory_limit=1G artisan test                # if artisan needed on large suites