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,
        ]);
    }
}