Laravel Testing with PHPUnit: Advanced Techniques, Mocks & Production Pitfalls

<?php

// Pure unit test — extends PHPUnit directly, zero Laravel overhead
// Use this for: domain logic, value objects, utility classes
namespace Tests\Unit;

use PHPUnit\Framework\TestCase;
use App\Domain\Pricing\OrderCalculator;
use App\Domain\Pricing\DiscountRule;

class OrderCalculatorTest extends TestCase
{
    private OrderCalculator $calculator;

    protected function setUp(): void
    {
        parent::setUp();
        // No app()->make() here — we new up the class directly.
        // This forces good design: if you can't new it up, it has too many dependencies.
        $this->calculator = new OrderCalculator();
    }

    /** @test */
    public function it_applies_percentage_discount_before_tax(): void
    {
        // Arrange: build a 20% discount rule
        $discountRule = new DiscountRule(type: 'percentage', value: 20.0);

        // Act: calculate a $100 order with 10% tax
        $result = $this->calculator->calculate(
            subtotalCents: 10000,  // $100.00 in cents — always store money as integers
            taxRatePercent: 10.0,
            discountRule: $discountRule
        );

        // Assert: discount reduces subtotal FIRST, then tax is applied on discounted amount
        // $100 - 20% = $80, then $80 * 1.10 = $88.00
        $this->assertSame(8800, $result->totalCents);   // $88.00
        $this->assertSame(2000, $result->discountCents); // $20.00 saved
        $this->assertSame(800,  $result->taxCents);      // tax on $80, not $100
    }

    /** @test */
    public function it_throws_when_discount_exceeds_subtotal(): void
    {
        $discountRule = new DiscountRule(type: 'fixed', value: 15000); // $150 off a $100 order

        // Expect a domain exception — don't let business rule violations become silent null returns
        $this->expectException(\App\Domain\Pricing\InvalidDiscountException::class);
        $this->expectExceptionMessage('Discount cannot exceed order subtotal');

        $this->calculator->calculate(
            subtotalCents: 10000,
            taxRatePercent: 10.0,
            discountRule: $discountRule
        );
    }
}

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
use App\Models\User;
use App\Models\Subscription;
use App\Models\Plan;
use Laravel\Sanctum\Sanctum;

// RefreshDatabase chosen here because we test a migration-dependent JSON column
// For simpler CRUD tests, swap this for DatabaseTransactions for a speed boost
class SubscriptionFeatureTest extends TestCase
{
    use RefreshDatabase;

    private Plan $premiumPlan;

    protected function setUp(): void
    {
        parent::setUp();
        // Seed only the data EVERY test in this class needs.
        // Don't call $this->seed() blindly — it runs ALL seeders and slows everything down.
        $this->premiumPlan = Plan::factory()->premium()->create();
    }

    /** @test */
    public function active_subscriber_can_access_premium_content(): void
    {
        $subscriber = User::factory()
            ->withActiveSubscription($this->premiumPlan)
            ->create();

        Sanctum::actingAs($subscriber);

        $response = $this->getJson('/api/content/premium-report');

        $response
            ->assertOk()
            ->assertJsonStructure([
                'data' => ['report_id', 'title', 'content', 'published_at']
            ])
            ->assertJsonPath('data.report_id', fn($id) => is_int($id) && $id > 0);
    }

    /** @test */
    public function suspended_subscriber_receives_payment_required_response(): void
    {
        $suspendedUser = User::factory()
            ->withActiveSubscription($this->premiumPlan)
            ->suspended()
            ->create();

        Sanctum::actingAs($suspendedUser);

        $response = $this->getJson('/api/content/premium-report');

        $response
            ->assertStatus(402)
            ->assertJsonPath('error.code', 'SUBSCRIPTION_SUSPENDED')
            ->assertJsonMissing(['data']);
    }

    /** @test */
    public function subscription_expiry_date_is_stored_as_utc(): void
    {
        $user = User::factory()->create();
        $expiresAt = now('America/New_York')->addMonth();

        $subscription = Subscription::factory()->create([
            'user_id'    => $user->id,
            'plan_id'    => $this->premiumPlan->id,
            'expires_at' => $expiresAt,
        ]);

        $subscription->refresh();

        $this->assertSame(
            $expiresAt->utc()->toDateTimeString(),
            $subscription->expires_at->utc()->toDateTimeString()
        );
    }
}

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Http;
use App\Models\User;
use App\Models\Product;
use App\Jobs\ProcessPayment;
use App\Jobs\ReserveInventory;
use App\Mail\OrderConfirmation;

class OrderPlacementTest extends TestCase
{
    use RefreshDatabase;

    /** @test */
    public function placing_an_order_dispatches_payment_and_inventory_jobs_in_correct_order(): void
    {
        // CRITICAL: Fake BEFORE the action — not after.
        Bus::fake();
        Mail::fake();

        Http::fake([
            'api.stripe.com/*' => Http::response([
                'id'     => 'pi_test_abc123',
                'status' => 'succeeded',
            ], 200),
        ]);

        $buyer  = User::factory()->withVerifiedEmail()->create();
        $laptop = Product::factory()->inStock(quantity: 5)->create(['price_cents' => 149999]);

        $response = $this->actingAs($buyer)->postJson('/api/orders', [
            'items' => [
                ['product_id' => $laptop->id, 'quantity' => 1],
            ],
            'payment_method' => 'pm_test_visa',
        ]);

        $response->assertCreated();

        Bus::assertDispatched(ProcessPayment::class, function (ProcessPayment $job) use ($buyer) {
            return $job->userId === $buyer->id && $job->paymentMethod === 'pm_test_visa';
        });

        Bus::assertDispatched(ReserveInventory::class, function (ReserveInventory $job) use ($laptop) {
            return $job->productId === $laptop->id && $job->quantity === 1;
        });

        Bus::assertDispatchedTimes(ProcessPayment::class, 1);
        Bus::assertDispatchedTimes(ReserveInventory::class, 1);

        Mail::assertQueued(OrderConfirmation::class, function (OrderConfirmation $mail) use ($buyer) {
            return $mail->hasTo($buyer->email);
        });

        Http::assertSent(function ($request) {
            return str_contains($request->url(), 'api.stripe.com')
                && $request->data()['payment_method'] === 'pm_test_visa';
        });
    }

    /** @test */
    public function order_placement_does_not_dispatch_jobs_when_stripe_returns_card_declined(): void
    {
        Bus::fake();
        Mail::fake();

        Http::fake([
            'api.stripe.com/*' => Http::response([
                'error' => ['code' => 'card_declined', 'message' => 'Your card was declined.']
            ], 402),
        ]);

        $buyer  = User::factory()->withVerifiedEmail()->create();
        $laptop = Product::factory()->inStock(quantity: 5)->create(['price_cents' => 149999]);

        $response = $this->actingAs($buyer)->postJson('/api/orders', [
            'items'          => [['product_id' => $laptop->id, 'quantity' => 1]],
            'payment_method' => 'pm_test_declined',
        ]);

        $response
            ->assertUnprocessable()
            ->assertJsonPath('error.code', 'CARD_DECLINED');

        Bus::assertNothingDispatched();
        Mail::assertNothingQueued();
    }
}

<?php

namespace Tests\Feature;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\Gate;
use App\Models\User;
use App\Models\Article;

class ArticlePolicyTest extends TestCase
{
    use RefreshDatabase;

    /** @test */
    public function author_can_update_their_own_article(): void
    {
        $author  = User::factory()->create();
        $article = Article::factory()->for($author, 'author')->create();

        $this->actingAs($author);

        $this->assertTrue(
            Gate::allows('update', $article),
            'The author should always be allowed to update their own article'
        );
    }

    /** @test */
    public function editor_role_can_update_any_article(): void
    {
        $editor  = User::factory()->withRole('editor')->create();
        $author  = User::factory()->create();
        $article = Article::factory()->for($author, 'author')->create();

        $this->actingAs($editor);

        $this->assertTrue(Gate::allows('update', $article));
    }

    /** @test */
    public function random_user_cannot_update_someone_elses_article(): void
    {
        $owner      = User::factory()->create();
        $interloper = User::factory()->create();
        $article    = Article::factory()->for($owner, 'author')->create();

        $this->actingAs($interloper);

        $this->assertFalse(Gate::allows('update', $article));

        $response = $this->patchJson("/api/articles/{$article->id}", [
            'title' => 'Hijacked Title',
        ]);

        $response->assertForbidden();
    }

    /** @test */
    public function it_does_not_leak_article_existence_to_unauthorized_users(): void
    {
        $owner = User::factory()->create();
        $draftArticle = Article::factory()->for($owner, 'author')->draft()->create();

        $visitor = User::factory()->create();
        $this->actingAs($visitor);

        $this->getJson("/api/articles/{$draftArticle->id}")->assertNotFound();
    }
}

namespace Tests\Feature;

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

class ExpireSubscriptionsCommandTest extends TestCase
{
    use RefreshDatabase;

    /** @test */
    public function expire_subscriptions_command_marks_overdue_subscriptions_as_expired(): void
    {
        $expiredOne   = Subscription::factory()->expiredYesterday()->create();
        $expiredTwo   = Subscription::factory()->expiredLastWeek()->create();
        $activeOne    = Subscription::factory()->expiresNextMonth()->create();

        $this->artisan('subscriptions:expire')
             ->expectsOutput('Processing expired subscriptions...')
             ->expectsOutput('2 subscription(s) marked as expired.')
             ->assertExitCode(0);

        $this->assertDatabaseHas('subscriptions', [
            'id'     => $expiredOne->id,
            'status' => 'expired',
        ]);
        $this->assertDatabaseHas('subscriptions', [
            'id'     => $expiredTwo->id,
            'status' => 'expired',
        ]);

        $this->assertDatabaseHas('subscriptions', [
            'id'     => $activeOne->id,
            'status' => 'active',
        ]);
    }
}

<?php

namespace Tests;

use Illuminate\Foundation\Testing\TestCase as BaseTestCase;
use Illuminate\Support\Facades\Bus;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Event;
use Illuminate\Support\Facades\Http;
use Illuminate\Support\Facades\ParallelTesting;

class TestCase extends BaseTestCase
{
    use CreatesApplication;

    protected function setUp(): void
    {
        parent::setUp();

        // Default: fake all side-effects in every feature test.
        // Individual tests can override by calling ->withoutFakes().
        Bus::fake();
        Mail::fake();
        Event::fake();
        Http::fake();
    }

    protected function tearDown(): void
    {
        // Flush all fakes between tests to prevent pollution.
        // Without this, a fake registered in test A bleeds into test B.
        Bus::fake()->flush();
        Mail::fake()->flush();
        Event::fake()->flush();
        Http::fake()->flush();

        parent::tearDown();
    }
}

<?php

namespace Tests\Unit;

use Tests\TestCase;
use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Support\Facades\DB;
use App\Models\Order;
use App\Models\OrderItem;
use App\Models\Product;
use App\Models\User;

class OrderRelationshipTest extends TestCase
{
    use RefreshDatabase;

    /** @test */
    public function order_has_many_items(): void
    {
        $order = Order::factory()->create();

        $items = OrderItem::factory()->count(3)->for($order)->create();

        // Assert the relationship returns all items
        $this->assertCount(3, $order->items);
        $this->assertTrue($order->items->contains($items->first()));
    }

    /** @test */
    public function order_belongs_to_user(): void
    {
        $user  = User::factory()->create();
        $order = Order::factory()->for($user)->create();

        $this->assertInstanceOf(User::class, $order->user);
        $this->assertEquals($user->id, $order->user->id);
    }

    /** @test */
    public function orders_scope_filters_by_status(): void
    {
        Order::factory()->count(3)->completed()->create();
        Order::factory()->count(2)->pending()->create();

        // Test the local scope directly
        $completed = Order::completed()->get();
        $pending   = Order::pending()->get();

        $this->assertCount(3, $completed);
        $this->assertCount(2, $pending);
        $this->assertTrue($completed->every(fn($o) => $o->status === 'completed'));
    }

    /** @test */
    public function eager_loading_prevents_n_plus_one_queries(): void
    {
        $order = Order::factory()->create();
        OrderItem::factory()->count(5)->for($order)->create();

        // Reset the query log
        DB::enableQueryLog();

        // Without eager loading: 1 query for orders + 5 queries for items = 6 queries
        // With eager loading: 1 query for orders + 1 query for items = 2 queries
        $orders = Order::with('items')->get();

        // Trigger relationship access to populate the query log
        $orders->each(fn($o) => $o->items->count());

        $queryLog = DB::getQueryLog();

        // Assert no more than 2 queries (orders + items)
        $this->assertLessThanOrEqual(2, count($queryLog),
            sprintf('Expected 2 queries but got %d — N+1 detected', count($queryLog))
        );

        DB::disableQueryLog();
    }
}