Verifying Exception Reporting in Laravel with assertReported

Laravel simplifies testing exception flows through the Exceptions facade's assertReported method, providing a robust way to verify that exceptions are properly captured and reported in your applications.

Handling and reporting exceptions correctly is fundamental to building reliable applications, yet verifying this behavior in tests can be complex without proper tooling. Laravel's Exceptions facade solves this challenge with the assertReported method, enabling you to confirm specific exceptions are captured during test execution.

Here's the basic implementation:

use Illuminate\Support\Facades\Exceptions;
 
test('exception reporting works correctly', function () {
    Exceptions::fake();
 
    $this->post('/generate-document', [
        'force_error' => 'true',
    ])->assertStatus(503); // Service Unavailable
 
    Exceptions::assertReported(ServiceUnavailableException::class);
});

The assertReported method shines when testing complex endpoints where different exceptions might occur based on various conditions:

use Illuminate\Support\Facades\Exceptions;
use App\Exceptions\ValidationException;
use App\Exceptions\ResourceNotFoundException;
 
test('subscription creation handles multiple exception types', function () {
    Exceptions::fake();
 
    // Test validation exception
    $this->postJson('/api/subscriptions', [
        'email' => 'invalid-email',
    ])->assertStatus(422);
 
    Exceptions::assertReported(ValidationException::class);
 
    // Test resource not found
    $this->postJson('/api/subscriptions', [
        'plan_id' => 999,
    ])->assertStatus(404);
 
    Exceptions::assertReported(ResourceNotFoundException::class);
 
    // Verify specific exception details
    Exceptions::assertReported(function (ResourceNotFoundException $exception) {
        return $exception->getMessage() === 'Subscription plan not found' &&
               $exception->getCode() === 404;
    });
});

This method provides two distinct verification approaches. You can use class-based assertions to confirm an exception type was reported:

Exceptions::assertReported(ServiceUnavailableException::class);

Or employ callback-based assertions to validate specific exception properties:

Exceptions::assertReported(function (ServiceUnavailableException $exception) {
    return $exception->getMessage() === 'External API timeout';
});

The assertReported method becomes indispensable when testing critical workflows like payment systems, third-party integrations, or background jobs where proper exception reporting directly impacts your ability to monitor and debug production issues.