laravel-tdd

Laravel TDD

Red-green-refactor for Laravel, with the framework-specific parts that differ from a generic TDD loop: which database trait to reach for, which Facade::fake() to use for a given side effect, and how to assert an Inertia response instead of raw JSON.

For the generic RED-GREEN-REFACTOR cycle and the Prove-It bug-fix pattern, see skills/test-driven-development/. This skill covers what's specific to Laravel on top of that cycle.

Test layers

• Unit — pure PHP: value objects, calculators, services with no framework dependency.
• Feature — HTTP endpoints, auth, validation, policies, response shape.
• Integration — database + queue + external boundaries together.

Pick the layer by what you need to prove, not by habit: a validation rule belongs in a Feature test that hits the route (it proves the FormRequest is wired in), not a Unit test that instantiates the rule class directly.

Framework choice

Default to Pest for new test files when the project has it installed; use PHPUnit only if the project already standardizes on it. Don't mix styles within one test file.

// Pest
test('owner can create project', function () {
    $user = User::factory()->create();

    $response = actingAs($user)->postJson('/api/projects', ['name' => 'New Project']);

    $response->assertCreated();
    assertDatabaseHas('projects', ['name' => 'New Project']);
});

// PHPUnit — same behavior, class-based
final class ProjectControllerTest extends TestCase
{
    use RefreshDatabase;

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

        $response = $this->actingAs($user)->postJson('/api/projects', ['name' => 'New Project']);

        $response->assertCreated();
        $this->assertDatabaseHas('projects', ['name' => 'New Project']);
    }
}

Database trait: which one and why

• RefreshDatabase — the default for feature/integration tests. On a connection with transaction support it migrates once per test run (a static flag) and wraps each test in a rolled-back transaction; on :memory: SQLite (no cross-connection transaction visibility) it re-migrates before every test, which is slower.
• DatabaseTransactions — use when the schema is already migrated (e.g. a persistent test database) and you only need per-test rollback, skipping the migration-freshness check RefreshDatabase does.
• DatabaseMigrations — full migrate-and-drop every test. Reserve for tests that specifically verify migration behavior; it's the slowest option and unnecessary for ordinary feature tests.