laravel-tdd
Skill3 starsChanged 43 days agoMITView on GitHub
Test-driven development workflow for Laravel using PHPUnit and Pest, covering factories, database strategies, fakes, authorization, HTTP mocking and coverage targets. Use when writing or refactoring Laravel tests, adding endpoints or models, or fixing a bug test-first.
14 other projects use a version of this, 10 of them edited.
Adopted by
Most recently taken up by
- AndresArreguy/ecc-pi-porttheir own version, first seen Nov 16, 2026
- Rojios/everything-claude-codeedited, first seen Nov 8, 2026
- renepf/claude-skillstheir own version, first seen Oct 25, 2026
- davidanthonyn/claude-skillsedited, first seen Oct 20, 2026
- gongyijie85/dsh-ecctheir own version, first seen Oct 13, 2026
- MohamedEssam0-0/claude-skillsedited, first seen Oct 11, 2026
Other versions14 projects use a version of this.
Word for word · 0
None found.
Edited · 10
- loulanyue/awesome-claude-notes★ 27232% same
- Fmarzochi/EGC★ 6131% same
- PUPT-Quantum-Leap/capstone-nlcom-volunteer-management-system★ 432% same
- ronmkr/PromptBook★ 231% same
- junimnjw/everything-claude-code★ 132% same
- Rojios/everything-claude-code★ 132% same
- TironFox/everything-claude-code★ 132% same
- davidanthonyn/claude-skills★ 032% same
- MohamedEssam0-0/claude-skills★ 032% same
- PeterYang888/claude-skills★ 032% same
Wrote their own version · 4
- gongyijie85/dsh-ecc★ 8same name
- AndresArreguy/ecc-pi-port★ 1same name
- SamuelNDCE/claude-super-skill-library★ 1same name
- renepf/claude-skills★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository3 other files it gives its agents.
- agent-browserSkill
- vue-i18nSkill
- vuelidate-i18nSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
22 rules. 0 are common, 15 are distinctive, and 7 are very specific to this project.
0
Common
Most of the 14 edited versions we read keep these.
15
Distinctive
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Distinctive: line 12
Test-driven development for Laravel applications, targeting 80%+ combined unit and feature coverage.
- Distinctive: line 35
Reproduce: - Write a failing test that describes the expected behaviour.
- Distinctive: line 51
Default to Feature tests. Add Unit tests only where logic is genuinely isolated from the framework.
- Distinctive: line 55
Use Pest for new tests when the project already uses Pest.
- Distinctive: line 56
Use PHPUnit when the project is standardised on PHPUnit, or when PHPUnit-specific tooling is required.
- Very specific: line 57
Never mix both styles inside one test file.
- Distinctive: line 76
Keep a separate testing environment so dev and production data are never touched.
- Distinctive: line 80
Use factories for all test data.
- Distinctive: line 103
Prefer framework assertions over manual queries.
- Very specific: line 123
Use Bus::fake() for job classes.
- Very specific: line 192
Use pcov or XDEBUG_MODE=coverage in CI.
- Distinctive: line 200
Run the narrowest scope while iterating, then widen before finishing.
- Distinctive: line 212
Always write the failing test first.
- Distinctive: line 213
Every bug fix ships with a regression test that fails without the fix.
- Very specific: line 214
Use Model::query() in assertions, never the DB facade.
- Distinctive: line 215
Keep tests isolated and deterministic.
- Very specific: line 216
Never let a test depend on wall-clock time.
- Distinctive: line 217
Never commit real credentials or secrets into a test file.
- Distinctive: line 218
Run only the affected tests during development, then offer to run the full suite.
- Distinctive: line 219
Never delete an existing test to make a suite pass.
- Very specific: line 332
Prefer assertInertia over raw JSON assertions so tests track the Inertia response contract.
- Very specific: line 370
Pest and PHPUnit tests coexist: - Check phpunit.xml testsuites includes both tests/Unit and tests/Feature, and that pest.php binds TestCase …
“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Laravel TDD Workflow
Test-driven development for Laravel applications, targeting 80%+ combined unit and feature coverage.
Description
A red-green-refactor workflow for Laravel covering test layer selection, database strategy, model factories, side-effect faking, authorization assertions, external HTTP isolation and coverage enforcement. Examples are given in both PHPUnit and Pest.
When to use
- Building a new Laravel feature, endpoint, job, notification or policy
- Fixing a bug, when a regression test should be written before the fix
- Refactoring code that already has test coverage
- Testing Eloquent models, factories, events or queued work
Do not use when
- The user only asks to read or explain existing tests without changing them
- The change is documentation, comments or formatting only
- The task is a pure frontend concern with no server-side behaviour to assert
Workflow
Copy this checklist and mark each step as it completes.
- Reproduce - Write a failing test that describes the expected behaviour. Run it and confirm it fails for the right reason.
- Implement - Make the smallest change that turns the test green.
- Verify - Re-run the affected tests, then the surrounding suite.
- Refactor - Clean up while the tests stay green. Re-run after each change.
- Report - State which tests were added or updated and the command used to run them.
Instructions
Test layers
| Layer | Covers | Prefer for |
| Unit | Pure PHP classes, value objects, services | Business logic with no framework or DB dependency |
| Feature | HTTP endpoints, auth, validation, response shape | Anything reachable through a route |
| Integration | Database + queue + external boundaries together | Cross-cutting behaviour, jobs, webhooks |
Default to Feature tests. Add Unit tests only where logic is genuinely isolated from the framework.
Framework selection
- Use Pest for new tests when the project already uses Pest.
- Use PHPUnit when the project is standardised on PHPUnit, or when PHPUnit-specific tooling is required.
- Never mix both styles inside one test file. Follow the convention already present in
tests/.
Database strategy
| Trait | Behaviour | Use when |
RefreshDatabase | Migrates once per run, then wraps each test in a transaction. Re-migrates per test on :memory: SQLite or non-transactional connections. | Default for any test touching the database |
DatabaseTransactions | Rolls back after each test, no migration | Schema is already migrated and you only need per-test isolation |
DatabaseMigrations | Full migrate:fresh before every test | You need a guaranteed clean schema and can afford the cost |
Configure phpunit.xml for fast in-memory runs:
<php>
<env name="DB_CONNECTION" value="sqlite"/>
<env name="DB_DATABASE" value=":memory:"/>
</php>Keep a separate testing environment so dev and production data are never touched.
Factories and states
Use factories for all test data. Never insert rows by hand.
// Named state, defined once on the factory and reused
// database/factories/UserFactory.php
public function admin(): static
{
return $this->state(fn (array $attributes): array => ['role' => 'admin']);
}
$user = User::factory()->admin()->create();For a one-off override, pass attributes directly. Factory::state() also accepts a raw array or closure when an ad-hoc state is needed without defining a named one.
$user = User::factory()->create(['role' => 'admin']);Define named states for edge cases that recur across tests, such as archived, admin or trial.
Assertions
Prefer framework assertions over manual queries.
$this->assertDatabaseHas('projects', ['name' => 'New Project']);
$this->assertDatabaseMissing('projects', ['name' => 'Deleted']);
$this->assertSoftDeleted('projects', ['id' => $project->id]);Faking side effects
| Fake | Intercepts |
Bus::fake() | Jobs dispatched through the bus (dispatch(), Bus::dispatch()), including queued jobs |
Queue::fake() | Raw queue pushes (Queue::push(), Queue::later()) |
Event::fake() | Domain events and their listeners |
Mail::fake() | Mailables |
Notification::fake() | Notifications on every channel |
Storage::fake() | Filesystem disks |
Http::fake() | Outbound HTTP client requests |
Use Bus::fake() for job classes. Reach for Queue::fake() only when payloads are pushed directly onto a queue.
use Illuminate\Support\Facades\Queue;
Queue::fake();
dispatch(new SendOrderConfirmation($order->id));
Queue::assertPushed(SendOrderConfirmation::class);use Illuminate\Support\Facades\Notification;
Notification::fake();
$user->notify(new InvoiceReady($invoice));
Notification::assertSentTo($user, InvoiceReady::class);use Illuminate\Http\Client\Request;
use Illuminate\Support\Facades\Http;
Http::fake([
'api.provider.com/v1/prices*' => Http::response(['price' => 1250], 200),
]);
app(PriceGateway::class)->fetch('WHEAT');
Http::assertSent(fn (Request $request): bool => $request->url() === 'https://api.provider.com/v1/prices/WHEAT'
&& $request->hasHeader('Accept', 'application/json'));Authentication
// Session or token auth via the framework
$response = $this->actingAs($user)->getJson('/api/projects');
// Sanctum
use Laravel\Sanctum\Sanctum;
Sanctum::actingAs($user);
// Passport
use Laravel\Passport\Passport;
Passport::actingAs($user);Authorization
use Illuminate\Support\Facades\Gate;
$this->assertTrue(Gate::forUser($owner)->allows('update', $project));
$this->assertFalse(Gate::forUser($stranger)->allows('update', $project));Also assert the HTTP-level outcome, not only the policy. A 403 on the route is the behaviour users actually see.
$this->actingAs($stranger)->patchJson("/api/projects/{$project->id}")->assertForbidden();Coverage
- Enforce 80%+ combined unit and feature coverage.
- Use
pcovorXDEBUG_MODE=coveragein CI.
php artisan test --coverage --min=80Running tests
Run the narrowest scope while iterating, then widen before finishing.
php artisan test --filter=test_owner_can_create_project
php artisan test --filter=ProjectControllerTest
php artisan test
vendor/bin/phpunit
vendor/bin/pestRules
- Always write the failing test first. Do not write implementation before a test exercises it.
- Every bug fix ships with a regression test that fails without the fix.
- Use
Model::query()in assertions, never theDBfacade. - Keep tests isolated and deterministic. No shared mutable state between tests.
- Never let a test depend on wall-clock time. Use
$this->travelTo()or$this->freezeTime(). - Never commit real credentials or secrets into a test file. Use factories and fakes.
- Run only the affected tests during development, then offer to run the full suite.
- Never delete an existing test to make a suite pass.
Examples
PHPUnit feature test
declare(strict_types=1);
namespace Tests\Feature;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
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']);
}
public function test_name_is_required(): void
{
$user = User::factory()->create();
$response = $this->actingAs($user)->postJson('/api/projects', []);
$response->assertUnprocessable()->assertJsonValidationErrors(['name']);
$this->assertDatabaseCount('projects', 0);
}
}Pest feature test
<?php
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use function Pest\Laravel\actingAs;
use function Pest\Laravel\assertDatabaseHas;
uses(RefreshDatabase::class);
test('owner can create project', function (): void {
$user = User::factory()->create();
$response = actingAs($user)->postJson('/api/projects', [
'name' => 'New Project',
]);
$response->assertCreated();
assertDatabaseHas('projects', ['name' => 'New Project']);
});Persistence test
declare(strict_types=1);
namespace Tests\Feature;
use App\Models\Project;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Tests\TestCase;
final class ProjectRepositoryTest extends TestCase
{
use RefreshDatabase;
public function test_project_can_be_retrieved_by_slug(): void
{
$project = Project::factory()->create(['slug' => 'alpha']);
$found = Project::query()->where('slug', 'alpha')->firstOrFail();
$this->assertSame($project->id, $found->id);
}
}Paginated index test
public function test_projects_index_returns_paginated_results(): void
{
$user = User::factory()->create();
Project::factory()->count(3)->for($user)->create();
$response = $this->actingAs($user)->getJson('/api/projects');
$response->assertOk();
$response->assertJsonStructure(['data', 'links', 'meta']);
}Adjust the asserted envelope to the project's actual API Resource shape.
Inertia feature test
Prefer assertInertia over raw JSON assertions so tests track the Inertia response contract.
declare(strict_types=1);
namespace Tests\Feature;
use App\Models\User;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Inertia\Testing\AssertableInertia;
use Tests\TestCase;
final class DashboardInertiaTest extends TestCase
{
use RefreshDatabase;
public function test_dashboard_inertia_props(): void
{
$user = User::factory()->create();
$response = $this->actingAs($user)->get('/dashboard');
$response->assertOk();
$response->assertInertia(fn (AssertableInertia $page): AssertableInertia => $page
->component('Dashboard')
->where('user.id', $user->id)
->has('projects')
);
}
}Edge cases
- Test fails with "table not found" - The trait is missing or the migration is not in the default path. Confirm
RefreshDatabaseis on the test class andphp artisan migrateruns clean. - Test passes alone but fails in the suite - Shared state leaked between tests. Replace static properties and singletons with per-test setup, and add
RefreshDatabaseif it is absent. - Assertion on a faked job never fires -
Bus::fake()was called after the dispatch, or the job was dispatched through a path the fake does not intercept. Move the fake to the top of the test. - Coverage below threshold locally but not in CI - The driver differs. Install
pcovlocally or run withXDEBUG_MODE=coverage. - Pest and PHPUnit tests coexist - Check
phpunit.xmltestsuitesincludes bothtests/Unitandtests/Feature, and thatpest.phpbindsTestCaseviauses(Tests\TestCase::class)->in('Feature').
References
- Laravel testing documentation: https://laravel.com/docs/testing
- PHPUnit documentation: https://docs.phpunit.de
- Pest Laravel plugin: https://pestphp.com/docs/plugins/laravel
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

