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.
Comprehensive testing guide for Laravel 13 applications. Contains 24 rules across 6 categories for writing fast, readable, and reliable tests. Supports both Pest PHP 4 and PHPUnit 12 (Laravel 13 default).
Framework Detection
Before writing or reviewing any test code, detect which testing framework the project uses:
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
|
Pest |
PHPUnit |
| Test function |
test('...', fn() => ...) |
public function test_...(): void |
| Readable name |
it('...', fn() => ...) |
#[Test] public function it_...() |
| Grouping |
describe('...', fn() => ...) |
Test class name / nested classes |
| Trait application |
uses(RefreshDatabase::class) |
use RefreshDatabase; inside class |
| Before each |
beforeEach(fn() => ...) |
protected function setUp(): void |
| After each |
afterEach(fn() => ...) |
protected function tearDown(): void |
| Parameterised |
->with([...]) |
#[DataProvider] attribute |
| Global setup |
uses(...)->in('Feature') in Pest.php |
Base TestCase class |
Core assertions (identical in both frameworks)
assertStatus, assertJson, assertJsonPath, assertDatabaseHas, assertModelExists, actingAs, Mail::fake(), Queue::fake(), Event::fake(), Notification::fake(), Storage::fake() — all work the same in Pest and PHPUnit.
When to Apply
Reference these guidelines when:
- 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
| Priority |
Category |
Impact |
Prefix |
| 1 |
HTTP & Feature Tests |
CRITICAL |
http- |
| 2 |
Model Factories |
CRITICAL |
factory- |
| 3 |
Database Assertions |
HIGH |
db- |
| 4 |
Faking Services |
HIGH |
fake- |
| 5 |
Authentication Testing |
HIGH |
auth- |
| 6 |
Test Organisation Patterns |
MEDIUM |
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
Read individual rule files for detailed explanations and code examples.
Each rule file contains:
- 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
For the complete guide with all rules expanded: AGENTS.md
1---2name: laravel-testing3description: Laravel 13 testing with Pest PHP 4 or PHPUnit 12. Use when writing feature tests, unit tests, or any test code in a Laravel application. Triggers on tasks involving HTTP tests, model factories, database assertions, mocking facades, authentication testing, or test organisation patterns.4license: MIT5metadata:6 source: https://skillmd.com/skills/asyrafhussin/laravel-testing7 author: Laravel Community8 version: "1.1.0"9 laravelVersion: "13.x"10 phpVersion: "8.3+"11 pestVersion: "4.x"12 phpunitVersion: "12.x"13---1415# Laravel 13 Testing — Pest PHP 4 & PHPUnit 121617> **Supports both Pest PHP 4 and PHPUnit 12.** See Framework Detection below.18>19> **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.2021Comprehensive testing guide for Laravel 13 applications. Contains 24 rules across 6 categories for writing fast, readable, and reliable tests. Supports both **Pest PHP 4** and **PHPUnit 12** (Laravel 13 default).2223## Framework Detection2425**Before writing or reviewing any test code, detect which testing framework the project uses:**2627### Step 1 — Check composer.json2829```bash30# Look for these in require-dev:31# "pestphp/pest" → Pest32# "phpunit/phpunit" (without pest) → PHPUnit33```3435- If `pestphp/pest` is present → **use Pest syntax**36- If only `phpunit/phpunit` is present → **use PHPUnit syntax**37- If both are present → **Pest takes priority** (Pest runs on top of PHPUnit)3839### Step 2 — Check for tests/Pest.php4041- If `tests/Pest.php` exists → **Pest is configured**, use Pest syntax4243### Step 3 — If still unclear, ask the user4445> "I couldn't detect the testing framework. Does this project use **Pest PHP** or **PHPUnit**?"4647---4849## Syntax Reference5051### Test Declaration5253| | Pest | PHPUnit |54|--|------|---------|55| Test function | `test('...', fn() => ...)` | `public function test_...(): void` |56| Readable name | `it('...', fn() => ...)` | `#[Test] public function it_...()` |57| Grouping | `describe('...', fn() => ...)` | Test class name / nested classes |58| Trait application | `uses(RefreshDatabase::class)` | `use RefreshDatabase;` inside class |59| Before each | `beforeEach(fn() => ...)` | `protected function setUp(): void` |60| After each | `afterEach(fn() => ...)` | `protected function tearDown(): void` |61| Parameterised | `->with([...])` | `#[DataProvider]` attribute |62| Global setup | `uses(...)->in('Feature')` in `Pest.php` | Base `TestCase` class |6364### Core assertions (identical in both frameworks)6566`assertStatus`, `assertJson`, `assertJsonPath`, `assertDatabaseHas`, `assertModelExists`, `actingAs`, `Mail::fake()`, `Queue::fake()`, `Event::fake()`, `Notification::fake()`, `Storage::fake()` — all work the same in Pest and PHPUnit.6768---6970## When to Apply7172Reference these guidelines when:73- Writing feature or unit tests for Laravel74- Testing HTTP endpoints and API responses75- Creating factories and test data76- Asserting database state after operations77- Faking Mail, Queue, Notification, or Event facades78- Testing authenticated routes and API tokens79- Organising tests with describe blocks, datasets, or test classes8081## Rule Categories by Priority8283| Priority | Category | Impact | Prefix |84|----------|----------|--------|--------|85| 1 | HTTP & Feature Tests | CRITICAL | `http-` |86| 2 | Model Factories | CRITICAL | `factory-` |87| 3 | Database Assertions | HIGH | `db-` |88| 4 | Faking Services | HIGH | `fake-` |89| 5 | Authentication Testing | HIGH | `auth-` |90| 6 | Test Organisation Patterns | MEDIUM | `pest-` |9192## Quick Reference9394### 1. HTTP & Feature Tests (CRITICAL)9596- `http-test-structure` - Arrange/Act/Assert with factories — Pest + PHPUnit examples97- `http-assert-response` - assertStatus, assertJson, assertRedirect, assertJsonMissing98- `http-assert-json-fluent` - Fluent assertJson with AssertableJson closure99- `http-refresh-database` - RefreshDatabase vs DatabaseTransactions — when to use each100101### 2. Model Factories (CRITICAL)102103- `factory-define` - Define factories with typed fake data and PHP 8.3 syntax104- `factory-states` - Factory states for distinct test scenarios105- `factory-sequences` - sequence() for varied data across multiple records106- `factory-relationships` - has(), for(), recycle(), afterCreating()107108### 3. Database Assertions (HIGH)109110- `db-assert-has` - assertDatabaseHas, assertModelExists for presence checks111- `db-assert-missing` - assertDatabaseMissing, assertModelMissing for deletion112- `db-assert-soft-deletes` - assertSoftDeleted, trashed() factory state113114### 4. Faking Services (HIGH)115116- `fake-mail` - Mail::fake(), assertSent vs assertQueued, assertNothingSent117- `fake-queue` - Queue::fake(), assertPushed, assertPushedOn118- `fake-notification` - Notification::fake(), assertSentTo, assertCount119- `fake-event` - Event::fake(), assertDispatched, assertNotDispatched120- `fake-storage` - Storage::fake(), UploadedFile::fake(), assertExists121- `fake-ai-agent` - Agent::fake(), assertPrompted, preventStrayPrompts (Laravel 13+)122- `fake-ai-media` - Image::fake(), Audio::fake(), Transcription::fake() (Laravel 13+)123- `fake-ai-data` - Embeddings::fake(), Reranking::fake(), Files::fake(), Stores::fake() (Laravel 13+)124125### 5. Authentication Testing (HIGH)126127- `auth-acting-as` - actingAs() for session/web authenticated tests128- `auth-sanctum` - Sanctum::actingAs() for API token authentication129130### 6. Test Organisation Patterns (MEDIUM)131132- `pest-describe-it` - describe()/it() (Pest) or test class organisation (PHPUnit)133- `pest-datasets` - with() datasets (Pest) or #[DataProvider] (PHPUnit)134- `pest-hooks` - beforeEach/afterEach (Pest) or setUp/tearDown (PHPUnit)135136## Essential Patterns137138### Pest139140```php141<?php142143use App\Models\User;144use Illuminate\Foundation\Testing\RefreshDatabase;145146uses(RefreshDatabase::class);147148test('authenticated user can create a post', function () {149 $user = User::factory()->create();150151 $this->actingAs($user)152 ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])153 ->assertStatus(201)154 ->assertJsonPath('data.title', 'Hello World');155156 $this->assertDatabaseHas('posts', ['title' => 'Hello World', 'user_id' => $user->id]);157});158```159160### PHPUnit161162```php163<?php164165namespace Tests\Feature;166167use App\Models\User;168use Illuminate\Foundation\Testing\RefreshDatabase;169use Tests\TestCase;170171class PostControllerTest extends TestCase172{173 use RefreshDatabase;174175 public function test_authenticated_user_can_create_a_post(): void176 {177 $user = User::factory()->create();178179 $this->actingAs($user)180 ->postJson('/api/posts', ['title' => 'Hello World', 'body' => 'Content.'])181 ->assertStatus(201)182 ->assertJsonPath('data.title', 'Hello World');183184 $this->assertDatabaseHas('posts', ['title' => 'Hello World', 'user_id' => $user->id]);185 }186}187```188189## How to Use190191Read individual rule files for detailed explanations and code examples.192193Each rule file contains:194- YAML frontmatter with metadata (title, impact, tags)195- Brief explanation of why it matters196- Bad Example with explanation197- Good Example with both Pest and PHPUnit where syntax differs198- Laravel 13 specific context and references199200## Full Compiled Document201202For the complete guide with all rules expanded: `AGENTS.md`