Laravel Testing

Laravel Testing

Test strategy for a layered Laravel application: 20 rules across 5 sections. Examples use Pest; every rule applies equally to PHPUnit.

The organizing idea: each layer has one test style that fits it. Testing an Action against a real database, or a Query Class against a mock, produces a slow suite that breaks on refactors and misses real bugs.

When to Apply

• Writing tests for any layer defined by the laravel-patterns skill
• Deciding what to fake and what to run for real
• The suite is slow, flaky, or nobody runs it locally
• Reviewing a pull request's test coverage
• Setting testing conventions for a project

The Layer Table

Pick the Rule

Before You Write Code

• Every API named in these rules is verified against Laravel ^12.0 || ^13.0 and PHP ^8.3. If you need something these rules do not name, check the docs — never infer an API from its name.
• Version-gated APIs are marked inline ("Laravel 13 only"). Read the project's composer.json first; on Laravel 12 use the fallback the rule gives.
• Where the project already differs from a rule, follow the project. Name the rule you set aside and why, rather than half-converting the codebase.
• When two rules collide, the higher-impact section wins — sections are ordered by impact.
• One example is not the whole rule. Open rules/{slug}.md before adapting it to a case the example does not show.

Rule Sections by Priority

Quick Reference

1. Strategy by Layer (HIGH)

• strategy-layer-to-test-type — Match the test style to the layer
• strategy-test-your-rules-not-the-framework — Test your rules, not Eloquent
• strategy-if-testing-feels-silly — A pointless test means a pointless class
• strategy-pest-and-suite-speed — Keep the suite fast enough to run on every save

2. Fakes and Doubles (HIGH)

• fake-repository-anonymous-class — Fake a Repository with an anonymous class
• fake-framework-facades — Queue::fake(), Event::fake(), Http::fake() and friends
• fake-never-mock-eloquent — Never mock Eloquent or the query builder
• fake-time-and-randomness — Freeze time, seed randomness
• fake-http-prevent-stray-requests — Fake the HTTP client and forbid stray requests
• fake-assert-queued-not-sent — assertQueued() for anything ShouldQueue

3. Database Tests (HIGH)

• db-refresh-database-and-factories — RefreshDatabase plus factories, never shared fixtures
• db-assert-inclusion-and-exclusion — Assert what is excluded, not only what is included
• db-test-ordering-and-defaults — Cover ordering, defaults and the sort allow-list
• db-test-eager-loading — Lock the N+1 fix in place
• db-test-transactions-and-idempotency — Prove rollback and repeat-safety

4. Feature Tests (MEDIUM-HIGH)

• http-assert-authorization — Unauthenticated, unpermitted, and another tenant's record
• http-assert-payload-shape — Pin the contract, including keys that must not appear
• http-assert-side-effects-dispatched — Assert the jobs and events an endpoint queues

5. Value Object Tests (MEDIUM)

• vo-test-predicates-directly — Construct, call, assert — no database, no container
• vo-never-hand-a-builder — A test needing a Builder means the boundary is broken

Suite Configuration

// tests/Pest.php
uses(Tests\TestCase::class, RefreshDatabase::class)->in('Feature', 'Integration');
uses(Tests\TestCase::class)->in('Unit');   // no database

<!-- phpunit.xml -->
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>
<env name="QUEUE_CONNECTION" value="sync"/>
<env name="CACHE_STORE" value="array"/>
<env name="MAIL_MAILER" value="array"/>

// AppServiceProvider::boot() — makes N+1 and typos fail the suite
Model::shouldBeStrict(! $this->app->isProduction());

SQLite differs from MySQL and Postgres on JSON operators, full-text search, locking and strict-mode errors. Run the integration suite against the production engine in CI even when local runs use SQLite.

Reference Material

• references/test-templates.md — copy-paste starting points for each layer
• references/checklist.md — pre-merge self-check for test coverage

How to Use

Load in this order and stop when the answer is clear:

1. This file — the Quick Reference names every rule, and usually settles the question.
2. One rule file for the reasoning and both examples (~465 tokens each):

rules/fake-repository-anonymous-class.md
rules/db-assert-inclusion-and-exclusion.md

3. A references/ file only when a rule points at one.

AGENTS.md is every rule compiled into one document (~8k tokens), for agents that read the AGENTS.md convention. Do not load it when the individual rule files are reachable.

Related Skills

• laravel-engineering — decide which changed boundary needs proof and keep docs current
• laravel-patterns — the layers these tests are organized around
• laravel-eloquent — the query rules the database tests assert
• laravel-rest-api — the endpoints the feature tests cover
• laravel-async — testing idempotency, batches and cache invalidation