Laravel 13 Testing — Pest PHP 4 & PHPUnit 12

Supports both Pest PHP 4 and PHPUnit 12. See Framework Detection below.

PHPUnit version note: Laravel 13 ships with

phpunit/phpunit: ^12.5.12

in its default

composer.json

. All patterns in this skill are compatible with PHPUnit 11, 12, and 13.

Framework Detection

Step 1 — Check composer.json

# Look for these in require-dev:
# "pestphp/pest" → Pest
# "phpunit/phpunit" (without pest) → PHPUnit

• If

  pestphp/pest

  is present → use Pest syntax
• If only

  phpunit/phpunit

  is present → use PHPUnit syntax
• If both are present → Pest takes priority (Pest runs on top of PHPUnit)

Step 2 — Check for tests/Pest.php

• If

  tests/Pest.php

  exists → Pest is configured, use Pest syntax

Step 3 — If still unclear, ask the user

"I couldn't detect the testing framework. Does this project use Pest PHP or PHPUnit?"

Syntax Reference

Test Declaration

test('...', fn() => ...)

public function test_...(): void

it('...', fn() => ...)

#[Test] public function it_...()

describe('...', fn() => ...)

uses(RefreshDatabase::class)

use RefreshDatabase;

beforeEach(fn() => ...)

protected function setUp(): void

afterEach(fn() => ...)

protected function tearDown(): void

->with([...])

#[DataProvider]

uses(...)->in('Feature')

Pest.php

TestCase

Core assertions (identical in both frameworks)

assertStatus

assertJson

assertJsonPath

assertDatabaseHas

assertModelExists

actingAs

Mail::fake()

Queue::fake()

Event::fake()

Notification::fake()

Storage::fake()

When to Apply

• Writing feature or unit tests for Laravel
• Testing HTTP endpoints and API responses
• Creating factories and test data
• Asserting database state after operations
• Faking Mail, Queue, Notification, or Event facades
• Testing authenticated routes and API tokens
• Organising tests with describe blocks, datasets, or test classes

Rule Categories by Priority

http-

factory-

db-

fake-

auth-

pest-

Quick Reference

1. HTTP & Feature Tests (CRITICAL)

• http-test-structure

  - Arrange/Act/Assert with factories — Pest + PHPUnit examples

• http-assert-response

  - assertStatus, assertJson, assertRedirect, assertJsonMissing

• http-assert-json-fluent

  - Fluent assertJson with AssertableJson closure

• http-refresh-database

  - RefreshDatabase vs DatabaseTransactions — when to use each

2. Model Factories (CRITICAL)

• factory-define

  - Define factories with typed fake data and PHP 8.3 syntax

• factory-states

  - Factory states for distinct test scenarios

• factory-sequences

  - sequence() for varied data across multiple records

• factory-relationships

  - has(), for(), recycle(), afterCreating()

3. Database Assertions (HIGH)

• db-assert-has

  - assertDatabaseHas, assertModelExists for presence checks

• db-assert-missing

  - assertDatabaseMissing, assertModelMissing for deletion

• db-assert-soft-deletes

  - assertSoftDeleted, trashed() factory state

4. Faking Services (HIGH)

• fake-mail

  - Mail::fake(), assertSent vs assertQueued, assertNothingSent

• fake-queue

  - Queue::fake(), assertPushed, assertPushedOn

• fake-notification

  - Notification::fake(), assertSentTo, assertCount

• fake-event

  - Event::fake(), assertDispatched, assertNotDispatched

• fake-storage

  - Storage::fake(), UploadedFile::fake(), assertExists

• fake-ai-agent

  - Agent::fake(), assertPrompted, preventStrayPrompts (Laravel 13+)

• fake-ai-media

  - Image::fake(), Audio::fake(), Transcription::fake() (Laravel 13+)

• fake-ai-data

  - Embeddings::fake(), Reranking::fake(), Files::fake(), Stores::fake() (Laravel 13+)

5. Authentication Testing (HIGH)

• auth-acting-as

  - actingAs() for session/web authenticated tests

• auth-sanctum

  - Sanctum::actingAs() for API token authentication

6. Test Organisation Patterns (MEDIUM)

• pest-describe-it

  - describe()/it() (Pest) or test class organisation (PHPUnit)

• pest-datasets

  - with() datasets (Pest) or #[DataProvider] (PHPUnit)

• pest-hooks

  - beforeEach/afterEach (Pest) or setUp/tearDown (PHPUnit)

Essential Patterns

Pest

<?php

use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;

uses(RefreshDatabase::class);

test('authenticated user can create a post', function () {
    $user = User::factory()->create();

    $this->actingAs($user)
        ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])
        ->assertStatus(201)
        ->assertJsonPath('data.title', 'Hello World');

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

PHPUnit

<?php

namespace Tests\Feature;

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

class PostControllerTest extends TestCase
{
    use RefreshDatabase;

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

        $this->actingAs($user)
            ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])
            ->assertStatus(201)
            ->assertJsonPath('data.title', 'Hello World');

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

How to Use

• YAML frontmatter with metadata (title, impact, tags)
• Brief explanation of why it matters
• Bad Example with explanation
• Good Example with both Pest and PHPUnit where syntax differs
• Laravel 13 specific context and references

Full Compiled Document

AGENTS.md