Laravel Tdd
Laravel testing strategies with PHPUnit, Pest, model factories, HTTP tests, Sanctum authentication testing, mocking, and coverage. Use when writing Laravel tests with PHPUnit or Pest, or driving a Laravel feature test-first.
Get the complete skill folder, including its scripts and reference files.
·
When to use this skill
Use Laravel Tdd when an AI agent needs a reusable SKILL.md workflow for this job: Laravel testing strategies with PHPUnit, Pest, model factories, HTTP tests, Sanctum authentication testing, mocking, and coverage. Use when writing Laravel tests with PHPUnit or Pest, or driving a Laravel feature test-first.
When not to use it
Skip Laravel Tdd when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.
How to install
Where will you use it?
mkdir -p ~/.claude/skills/laravel-tdd # Save SKILL.md to ~/.claude/skills/laravel-tdd/SKILL.md
- Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/laravel-tdd/SKILL.md. For a shared project, commit the folder at .claude/skills/laravel-tdd/ instead.
- Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
- For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.
Full install guide for Claude, Cursor, and Codex →
Try a starter prompt
After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.
Use the Laravel Tdd skill for this task: Use Laravel Tdd when this documented workflow matches the task. Confirm any required inputs or files before making changes.
What supports this recommendation?
70/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.
- Documentation
- 77/100
- Practical detail
- 68/100
- Source evidence
- 63/100
- Source signals
- 70/100
Model compatibility evidence
- claudeuntested
No model-specific signal or recorded compatibility test was found.
- chatgptuntested
No model-specific signal or recorded compatibility test was found.
- geminiuntested
No model-specific signal or recorded compatibility test was found.
- copilotuntested
No model-specific signal or recorded compatibility test was found.
- llamauntested
No model-specific signal or recorded compatibility test was found.
- perplexityuntested
No model-specific signal or recorded compatibility test was found.
- mistraluntested
No model-specific signal or recorded compatibility test was found.
- grokuntested
No model-specific signal or recorded compatibility test was found.
Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.
What this skill does
# Laravel Testing with TDD
Test-driven development for Laravel applications using PHPUnit, Pest, Laravel factories, and testing helpers.
## When to Activate
- Writing new Laravel applications or features - Implementing API endpoints with Sanctum or Passport authentication - Testing Eloquent models, relationships, scopes, and accessors - Setting up testing infrastructure for Laravel projects - Writing feature tests for HTTP controllers and form requests - Mocking external services (queues, mail, notifications, HTTP)
## TDD Workflow for Laravel
### Red-Green-Refactor Cycle
```php // Step 1: RED — Write a failing test public function test_a_product_can_be_created(): void { $product = Product::factory()->create(['name' => 'Test Product']); $this->assertDatabaseHas('products', ['name' => 'Test Product']); }
// Step 2: GREEN — Write the migration, model, and factory // Step 3: REFACTOR — Improve while keeping tests green ```
## Setup
### PHPUnit Configuration
```xml <?xml version="1.0" encoding="UTF-8"?> <phpunit xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd" bootstrap="vendor/autoload.php" colors="true"> <testsuites> <testsuite name="Unit"> <directory suffix="Test.php">tests/Unit</directory> </testsuite> <testsuite name="Feature"> <directory suffix="Test.php">tests/Feature</directory> </testsuite> </testsuites> <php> <env name="APP_ENV" value="testing"/> <env name="BCRYPT_ROUNDS" value="4"/> <env name="CACHE_STORE" value="array"/> <env name="DB_CONNECTION" value="sqlite"/> <env name="DB_DATABASE" value=":memory:"/> <env name="MAIL_MAILER" value="array"/> <env name="QUEUE_CONNECTION" value="sync"/> <env name="SESSION_DRIVER" value="array"/> </php> </phpunit> ```
### Base TestCase Setup
```php namespace Tests;
use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
abstract class TestCase extends BaseTestCase { protected function setUp(): void { parent::setUp(); // Call $this->withoutExceptionHandling() only in tests that // test non-HTTP exceptions; it suppresses assertStatus() etc. }
// Helper: Authenticate and return user protected function actingAsUser(): mixed { $user = \App\Models\User::factory()->create(); $this->actingAs($user); return $user; }
protected function actingAsAdmin(): mixed { $admin = \App\Models\User::factory()->admin()->create(); $this->actingAs($admin); return $admin; } } ```
## Model Factories
```php // database/factories/UserFactory.php class UserFactory extends Factory { protected static ?string $password = null;
public function definition(): array { return [ 'name' => fake()->name(), 'email' => fake()->unique()->safeEmail(), 'email_verified_at' => now(), 'password' => static::$password ??= Hash::make('password'), 'remember_token' => Str::random(10), 'role' => 'user', ]; }
public function admin(): static { return $this->state(fn (array $attributes) => ['role' => 'admin']); }
public function unverified(): static { return $this->state(fn (array $attributes) => ['email_verified_at' => null]); } }
// database/factories/ProductFactory.php class ProductFactory extends Factory { public function definition(): array { return [ 'name' => fake()->unique()->words(3, true), 'slug' => fn (array $attrs) => Str::slug($attrs['name']), 'description' => fake()->paragraph(), 'price' => fake()->numberBetween(100, 100000), 'stock' => fake()->numberBetween(0, 100), 'is_active' => true, 'user_id' => UserFactory::new(), ]; }
public function outOfStock(): static { return $this->state(fn (array $attributes) => ['stock' => 0]); } } ```
### Using Factories
```php $user = User::factory()->create(); $admin = User::factory()->admin()->create(); $product = Product::factory()->create(['user_id' => $user->id]); $products = Product::factory()->count(10)->create(); $draft = Product::factory()->make(); // Not persisted
// With relationships $user = User::factory()->has(Product::factory()->count(3))->create();
// Sequences User::factory()->count(3)->sequence( ['role' => 'admin'], ['role' => 'editor'], ['role' => 'user'], )->create(); ```
## Model Testing
```php namespace Tests\Unit\Models;
use App\Models\User; use App\Models\Product; use Illuminate\Foundation\Testing\RefreshDatabase; use Tests\TestCase;
class UserTest extends TestCase { use RefreshDatabase;
public function test_it_hides_sensitive_attributes(): void { $user = User::factory()->create(); $this->assertArrayNotHasKey('password', $user->toArray()); }
public function test_admin_scope_returns_only_admins(): void { User::factory()->admin()->create(); User::factory()->count(3)->create();
$this->assertCount(1, User::admin()->get()); } }
class ProductTest extends TestCase { use RefreshDatabase;
public function test_active_scope_filters_correctly(): void { Product::factory()->count(3)->create(['is_active' => true]); Product::factory()->count(2)->create(['is_active' => false]);
$this->assertCount(3, Product::active()->get()); }
public function test_it_belongs_to_a_user(): void { $user = User::factory()->create(); $product = Product::factory()->create(['user_id' => $user->id]);
$this->assertTrue($product->user->is($user)); } } ```
## Feature / HTTP Testing
```php namespace Tests\Feature\Http\Controllers;
use App\Models\Product; use App\Models\User; use Illuminate\Foundation\Testing\RefreshDatabase; use Tests\TestCase;
class ProductControllerTest extends TestCase { use RefreshDatabase;
public function test_guests_are_redirected_to_login(): void { $this->get(route('products.create'))->assertRedirect(route('login')); }
public function test_it_stores_a_new_product(): void { $user = User::factory()->create(); $this->actingAs($user);
$response = $this->post(route('products.store'), [ 'name' => 'New Product', 'description' => 'Description', 'price' => 2999, 'stock' => 10, ]);
$response->assertRedirect(route('products.index')); $this->assertDatabaseHas('products', [ 'name' => 'New Product', 'user_id' => $user->id, ]); }
public function test_it_validates_required_fields(): void { $this->actingAs(User::factory()->create()); $this->post(route('products.store'), []) ->assertSessionHasErrors(['name', 'price']); }
public function test_users_cannot_modify_others_products(): void { $owner = User::factory()->create(); $attacker = User::factory()->create(); $product = Product::factory()->create(['user_id' => $owner->id]);
$this->actingAs($attacker) ->delete(route('products.destroy', $product)) ->assertForbidden(); } } ```
## JSON API Testing
```php namespace Tests\Feature\Http\Controllers\Api;
use App\Models\Product; use App\Models\User; use Illuminate\Foundation\Testing\RefreshDatabase; use Tests\TestCase;
class ProductApiTest extends TestCase { use RefreshDatabase;
public function test_unauthenticated_requests_are_rejected(): void { $this->getJson('/api/products')->assertUnauthorized(); }
public function test_it_lists_paginated_products(): void { $user = User::factory()->create(); Product::factory()->count(5)->create(['user_id' => $user->id]);
$response = $this->actingAs($user)->getJson('/api/products');
$response->assertOk(); $response->assertJsonCount(5, 'data'); $response->assertJsonStructure([ 'data' => [['id', 'name', 'price']], 'meta' => ['current_page', 'last_page', 'total'], ]); }
public function test_it_creates_a_product(): void { $user = User::factory()->create();
$response = $this->actingAs($user)->postJson('/api/products', [ 'name' => 'API Product', 'price' => 4999, ]);
$response->assertCreated(); $response->assertJsonPath('data.name', 'API Product'); }
public function test_users_cannot_delete_others_products(): void { $owner = User::factory()->create(); $attacker = User::factory()->create(); $product = Product::factory()->create(['user_id' => $owner->id]);
$this->actingAs($attacker) ->deleteJson("/api/products/{$product->id}") ->assertForbidden(); } } ```
## Sanctum API Auth Testing
```php namespace Tests\Feature\Http\Controllers\Api;
use App\Models\User; use Illuminate\Foundation\Testing\RefreshDatabase; use Illuminate\Support\Facades\Hash; use Tests\TestCase;
class AuthControllerTest extends TestCase { use RefreshDatabase;
public function test_users_can_register(): void { $response = $this->postJson('/api/register', [ 'name' => 'Test User', 'email' => '[email protected]', 'password' => 'Password123!', 'password_confirmation' => 'Password123!', ]);
$response->assertCreated(); $response->assertJsonStructure(['data' => ['user', 'token']]); }
public function test_users_can_login(): void { User::factory()->create([ 'email' => '[email protected]', 'password' => Hash::make('Password123!'), ]);
$response = $this->postJson('/api/login', [ 'email' => '[email protected]', 'password' => 'Password123!', ]);
$response->assertOk(); $response->assertJsonStructure(['data' => ['token']]); }
public function test_users_cannot_login_with_wrong_password(): void { User::factory()->create(['email' => '[email protected]']);
$this->postJson('/api/login', [ 'email' => '[email protected]', 'password' => 'wrong', ])->assertUnprocessable(); }
public function test_token_bearer_authenticates_requests(): void { $user = User::factory()->create(); $token = $user->createToken('test')->plainTextToken;
$this->withToken($token) ->getJson('/api/user') ->assertOk() ->assertJsonPath('data.email', $user->email); } } ```
## Mocking and Fakes
### HTTP Fake
```php use Illuminate\Support\Facades\Http;
public function test_it_handles_successful_payment(): void { Http::fake([ 'api.stripe.com/*' => Http::response(['id' => 'pi_123', 'status' => 'succeeded'], 200), ]);
$result = (new PaymentService())->charge(2999); $this->assertTrue($result->success); }
public function test_it_handles_gateway_failure(): void { Http::fake([ 'api.stripe.com/*' => Http::response(['error' => 'card_declined'], 402), ]);
$this->expectException(PaymentFailedException::class); (new PaymentService())->charge(2999); }
public function test_it_retries_on_timeout(): void { Http::fake([ 'api.stripe.com/*' => Http::sequence() ->pushStatus(408) ->pushStatus(200), ]);
$this->assertTrue((new PaymentService())->charge(2999)->success); } ```
### Mail Fake
```php Mail::fake();
$order->sendConfirmation();
Mail::assertSent(OrderConfirmation::class, function ($mail) use ($order) { return $mail->hasTo($order->user->email); }); ```
### Notification Fake
```php Notification::fake();
$user->notify(new WelcomeUser());
Notification::assertSentTo($user, WelcomeUser::class); ```
### Queue Fake
```php Queue::fake();
ProcessImage::dispatch($product);
Queue::assertPushed(ProcessImage::class, function ($job) use ($product) { return $job->product->id === $product->id; }); ```
### Storage Fake
```php Storage::fake('public');
$file = UploadedFile::fake()->image('photo.jpg', 200, 200);
$response = $this->actingAs($user)->post('/avatar', [ 'avatar' => $file, ]);
$response->assertSessionHasNoErrors(); Storage::disk('public')->assertExists('avatars/' . $file->hashName()); ```
### Event Fake
```php Event::fake();
$order->markAsShipped();
Event::assertDispatched(OrderShipped::class, function ($event) use ($order) { return $event->order->id === $order->id; }); ```
## Artisan Command Tests
```php public function test_it_sends_newsletters(): void { Mail::fake(); User::factory()->count(5)->create(['subscribed' => true]);
$this->artisan('newsletter:send') ->expectsOutput('Sending newsletter to 5 subscribers...') ->assertExitCode(0);
Mail::assertSent(NewsletterMail::class, 5); }
public function test_it_handles_no_subscribers(): void { $this->artisan('newsletter:send') ->expectsOutput('No subscribers found.') ->assertExitCode(0); } ```
## Authorization Tests
```php public function test_users_can_update_own_posts(): void { $user = User::factory()->create(); $post = Post::factory()->create(['user_id' => $user->id]);
$this->actingAs($user) ->put(route('posts.update', $post), ['title' => 'Updated']) ->assertRedirect(); }
public function test_users_cannot_update_others_posts(): void { $post = Post::factory()->create(); $this->actingAs(User::factory()->create()) ->put(route('posts.update', $post), ['title' => 'Hacked']) ->assertForbidden(); }
public function test_gate_before_grants_super_admin_full_access(): void { $super = User::factory()->create(['role' => 'super-admin']); $post = Post::factory()->create();
$this->actingAs($super) ->delete(route('posts.destroy', $post)) ->assertRedirect();
$this->assertSoftDeleted($post); } ```
## Pest Feature Tests
```php <?php
use App\Models\Product; use App\Models\User;
uses(\Illuminate\Foundation\Testing\RefreshDatabase::class);
beforeEach(function () { $this->user = User::factory()->create(); $this->actingAs($this->user); });
it('lists products', function () { Product::factory()->count(3)->create(['user_id' => $this->user->id]);
$this->get(route('products.index')) ->assertOk() ->assertViewHas('products'); });
it('creates a product with valid data', function () { $this->post(route('products.store'), [ 'name' => 'Test Product', 'price' => 1999, ])->assertRedirect();
$this->assertDatabaseHas('products', ['name' => 'Test Product']); });
it('fails validation without required fields', function () { $this->post(route('products.store'), []) ->assertSessionHasErrors(['name', 'price']); });
it('authorizes updates', function () { $other = User::factory()->create(); $product = Product::factory()->create(['user_id' => $other->id]);
$this->put(route('products.update', $product), ['name' => 'Hacked']) ->assertForbidden(); }); ```
## Coverage
```bash # PHPUnit (use clover output for CI threshold checks) vendor/bin/phpunit --coverage-html coverage --coverage-clover clover.xml
# Pest (built-in threshold support) vendor/bin/pest --coverage --min=80 ```
### Coverage Goals
| Component | Target | |-----------|--------| | Models | 95%+ | | Actions/Services | 90%+ | | Form Requests | 90%+ | | Controllers | 85%+ | | Policies | 95%+ | | Overall | 80%+ |
## Testing Best Practices
### DO
- Use factories over manual `create()` calls - One logical assertion per test - Descriptive names: `test_guests_cannot_create_products` - Test edge cases and authorization boundaries - Mock external services with `Http::fake()`, `Mail::fake()` - Use `RefreshDatabase` for clean state
### DON'T
- Don't test Laravel internals (trust the framework) - Don't make tests dependent on each other - Don't over-mock — mock only service boundaries - Don't test private methods — test through the public interface - Don't couple tests to HTML structure
## Quick Reference
| Pattern | Usage | |---------|-------| | `RefreshDatabase` | Reset database between tests | | `$this->actingAs($user)` | Authenticate as user | | `$this->withToken($token)` | Bearer token auth for APIs | | `Model::factory()->create()` | Create model with factory | | `Model::factory()->count(5)->create()` | Create multiple records | | `Http::fake([...])` | Mock HTTP calls | | `Mail::fake()` | Trap sent mail | | `Notification::fake()` | Trap sent notifications | | `Queue::fake()` | Trap queued jobs | | `Event::fake()` | Trap dispatched events | | `Storage::fake('public')` | Trap file operations | | `assertDatabaseHas` | Assert DB row exists | | `assertSoftDeleted` | Assert soft-delete | | `assertSessionHasErrors` | Assert validation errors | | `assertForbidden` | Assert 403 status |
## Related Skills
- `laravel-patterns` — Laravel architecture, Eloquent, routing, and API patterns - `laravel-security` — Laravel authentication, authorization, and secure coding - `tdd-workflow` — The repo-wide RED -> GREEN -> REFACTOR loop - `backend-patterns` — General backend API and database patterns
Intended uses
- Use Laravel Tdd when this documented workflow matches the task.
Implementation notes
- Review the source instructions and adapt inputs before running the workflow.
Try it, then tell us how it went
A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.