[11.x] Introduces Exceptions facade

[nunomaduro]

This pull request introduces a new Exceptions facade to provide a consistent way to test exceptions in Laravel applications. Here is the list of methods that the Exceptions facade provides:

• assertReported
• assertReportedCount
• assertNotReported
• assertNothingReported
• throwOnReport
• throwFirstReported

All the examples below assume the following route:

Route::post('/generate-report', function () {
    return request()->throw
        ? throw new ServiceUnavailableException('Service is currently unavailable')
        : response()->json(['message' => 'Report generated successfully']); 
});

assertReported method

The assertReported method allows you to assert that an exception was reported:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake();
    
    $this->post('/generate-report', [
        'throw' => 'true',
    ])->assertStatus(503); // Service Unavailable
    
    Exceptions::assertReported(ServiceUnavailableException::class);
    
    // or
    Exceptions::assertReported(function (ServiceUnavailableException $exception) {
        return $exception->getMessage() === 'Service is currently unavailable';
    });
});

assertReportedCount method

The assertReportedCount method allows you to assert the number of exceptions reported:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake();
    
    $this->post('/generate-report', [
        'throw' => 'true',
    ])->assertStatus(503); // Service Unavailable
    
    Exceptions::assertReportedCount(1);
});

assertNotReported method

The assertNotReported method allows you to assert that an exception was not reported:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake();
    
    $this->post('/generate-report', [
        'throw' => 'false',
    ])->assertStatus(200);
    
    Exceptions::assertNotReported(ServiceUnavailableException::class);
    
    // or
    Exceptions::assertNotReported(function (ServiceUnavailableException $exception) {
        return $exception->getMessage() === 'Service is currently unavailable';
    });
});

assertNothingReported method

The assertNothingReported method allows you to assert that no exceptions were reported:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake();
    
    $this->post('/generate-report', [
        'throw' => 'false',
    ])->assertStatus(200);
    
    Exceptions::assertNothingReported();
});

Optionally, you may specify a list of exceptions you wish to capture:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake([AnotherException::class]);
   
    $this->post('/generate-report', [
        'throw' => 'true',
    ])->assertStatus(503); // Service Unavailable
    
    Exceptions::assertNothingReported();
});

throwOnReport method

The throwOnReport method allows you to throw any reported exceptions:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::throwOnReport();
    
    $this->post('/generate-report', [
        'throw' => 'true',
    ]); // throws ServiceUnavailableException
});

Optionally, you may specify a list of exceptions you wish to capture:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::throwOnReport([AnotherException::class]);
    
    $this->post('/generate-report', [
        'throw' => 'true',
    ])->assertStatus(503); // Service Unavailable
    
    // test passes...
});

throwFirstReported method

The throwFirstReported method allows you to throw the previous reported exceptions:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake();

    $this->post('/generate-report', [
        'throw' => 'true',
    ])->assertStatus(503);
    
    Exceptions::throwFirstReported(); // throws ServiceUnavailableException
});

Optionally, you may specify a list of exceptions you wish to capture:

use Illuminate\Support\Facades\Exceptions;

test('example', function () {
    Exceptions::fake([AnotherException::class]);
    
    $this->post('/generate-report', [
        'throw' => 'true',
    ])->assertStatus(503); // Service Unavailable
    
    Exceptions::throwFirstReported(); // throws nothing, nad test passes...
});

[timacdonald]

❤️