Put fake documentation on the actual pages (#8565)

* move fake documentation into the actual documentation

* additional info

* Update events.md

* Update queues.md

Author: taylorotwell

events.md

@@ -15,6 +15,9 @@
 - [Event Subscribers](#event-subscribers)
     - [Writing Event Subscribers](#writing-event-subscribers)
     - [Registering Event Subscribers](#registering-event-subscribers)
+- [Testing](#testing)
+    - [Faking A Subset Of Events](#faking-a-subset-of-events)
+    - [Scoped Events Fakes](#scoped-event-fakes)
 
 <a name="introduction"></a>
 ## Introduction
@@ -519,7 +522,7 @@ To dispatch an event, you may call the static `dispatch` method on the event. Th
     OrderShipped::dispatchUnless($condition, $order);
 
 > **Note**  
-> When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's [built-in testing helpers](/docs/{{version}}/mocking#event-fake) makes it a cinch.
+> When testing, it can be helpful to assert that certain events were dispatched without actually triggering their listeners. Laravel's [built-in testing helpers](#testing) makes it a cinch.
 
 <a name="event-subscribers"></a>
 ## Event Subscribers
@@ -634,3 +637,122 @@ After writing the subscriber, you are ready to register it with the event dispat
             UserEventSubscriber::class,
         ];
     }
+
+<a name="testing"></a>
+## Testing
+
+When testing code that dispatches events, you may wish to instruct Laravel to not actually execute the event's listeners, since the listener's code can be tested directly and separately of the code that dispatches the corresponding event. Of course, to test the listener itself, you may instantiate a listener instance and invoke the `handle` method directly in your test.
+
+Using the `Event` facade's `fake` method, you may prevent listeners from executing, execute the code under test, and then assert which events were dispatched by your application using the `assertDispatched`, `assertNotDispatched`, and `assertNothingDispatched` methods:
+
+    <?php
+
+    namespace Tests\Feature;
+
+    use App\Events\OrderFailedToShip;
+    use App\Events\OrderShipped;
+    use Illuminate\Support\Facades\Event;
+    use Tests\TestCase;
+
+    class ExampleTest extends TestCase
+    {
+        /**
+         * Test order shipping.
+         */
+        public function test_orders_can_be_shipped(): void
+        {
+            Event::fake();
+
+            // Perform order shipping...
+
+            // Assert that an event was dispatched...
+            Event::assertDispatched(OrderShipped::class);
+
+            // Assert an event was dispatched twice...
+            Event::assertDispatched(OrderShipped::class, 2);
+
+            // Assert an event was not dispatched...
+            Event::assertNotDispatched(OrderFailedToShip::class);
+
+            // Assert that no events were dispatched...
+            Event::assertNothingDispatched();
+        }
+    }
+
+You may pass a closure to the `assertDispatched` or `assertNotDispatched` methods in order to assert that an event was dispatched that passes a given "truth test". If at least one event was dispatched that passes the given truth test then the assertion will be successful:
+
+    Event::assertDispatched(function (OrderShipped $event) use ($order) {
+        return $event->order->id === $order->id;
+    });
+
+If you would simply like to assert that an event listener is listening to a given event, you may use the `assertListening` method:
+
+    Event::assertListening(
+        OrderShipped::class,
+        SendShipmentNotification::class
+    );
+
+> **Warning**
+> After calling `Event::fake()`, no event listeners will be executed. So, if your tests use model factories that rely on events, such as creating a UUID during a model's `creating` event, you should call `Event::fake()` **after** using your factories.
+
+<a name="faking-a-subset-of-events"></a>
+### Faking A Subset Of Events
+
+If you only want to fake event listeners for a specific set of events, you may pass them to the `fake` or `fakeFor` method:
+
+    /**
+     * Test order process.
+     */
+    public function test_orders_can_be_processed(): void
+    {
+        Event::fake([
+            OrderCreated::class,
+        ]);
+
+        $order = Order::factory()->create();
+
+        Event::assertDispatched(OrderCreated::class);
+
+        // Other events are dispatched as normal...
+        $order->update([...]);
+    }
+
+You may fake all events except for a set of specified events using the `except` method:
+
+    Event::fake()->except([
+        OrderCreated::class,
+    ]);
+
+<a name="scoped-event-fakes"></a>
+### Scoped Event Fakes
+
+If you only want to fake event listeners for a portion of your test, you may use the `fakeFor` method:
+
+    <?php
+
+    namespace Tests\Feature;
+
+    use App\Events\OrderCreated;
+    use App\Models\Order;
+    use Illuminate\Support\Facades\Event;
+    use Tests\TestCase;
+
+    class ExampleTest extends TestCase
+    {
+        /**
+         * Test order process.
+         */
+        public function test_orders_can_be_processed(): void
+        {
+            $order = Event::fakeFor(function () {
+                $order = Order::factory()->create();
+
+                Event::assertDispatched(OrderCreated::class);
+
+                return $order;
+            });
+
+            // Events are dispatched as normal and observers will run ...
+            $order->update([...]);
+        }
+    }

filesystem.md

@@ -21,6 +21,7 @@
     - [File Visibility](#file-visibility)
 - [Deleting Files](#deleting-files)
 - [Directories](#directories)
+- [Testing](#testing)
 - [Custom Filesystems](#custom-filesystems)
 
 <a name="introduction"></a>
@@ -608,6 +609,48 @@ Finally, the `deleteDirectory` method may be used to remove a directory and all
 
     Storage::deleteDirectory($directory);
 
+<a name="testing"></a>
+## Testing
+
+The `Storage` facade's `fake` method allows you to easily generate a fake disk that, combined with the file generation utilities of the `Illuminate\Http\UploadedFile` class, greatly simplifies the testing of file uploads. For example:
+
+    <?php
+
+    namespace Tests\Feature;
+
+    use Illuminate\Http\UploadedFile;
+    use Illuminate\Support\Facades\Storage;
+    use Tests\TestCase;
+
+    class ExampleTest extends TestCase
+    {
+        public function test_albums_can_be_uploaded(): void
+        {
+            Storage::fake('photos');
+
+            $response = $this->json('POST', '/photos', [
+                UploadedFile::fake()->image('photo1.jpg'),
+                UploadedFile::fake()->image('photo2.jpg')
+            ]);
+
+            // Assert one or more files were stored...
+            Storage::disk('photos')->assertExists('photo1.jpg');
+            Storage::disk('photos')->assertExists(['photo1.jpg', 'photo2.jpg']);
+
+            // Assert one or more files were not stored...
+            Storage::disk('photos')->assertMissing('missing.jpg');
+            Storage::disk('photos')->assertMissing(['missing.jpg', 'non-existing.jpg']);
+
+            // Assert that a given directory is empty...
+            Storage::disk('photos')->assertDirectoryEmpty('/wallpapers');
+        }
+    }
+
+By default, the `fake` method will delete all files in its temporary directory. If you would like to keep these files, you may use the "persistentFake" method instead. For more information on testing file uploads, you may consult the [HTTP testing documentation's information on file uploads](/docs/{{version}}/http-tests#testing-file-uploads).
+
+> **Warning**
+> The `image` method requires the [GD extension](https://www.php.net/manual/en/book.image.php).
+
 <a name="custom-filesystems"></a>
 ## Custom Filesystems
 

mail.md

@@ -24,7 +24,9 @@
 - [Rendering Mailables](#rendering-mailables)
     - [Previewing Mailables In The Browser](#previewing-mailables-in-the-browser)
 - [Localizing Mailables](#localizing-mailables)
-- [Testing Mailables](#testing-mailables)
+- [Testing](#testing-mailables)
+    - [Testing Mailable Content](#testing-mailable-content)
+    - [Testing Mailable Sending](#testing-mailable-sending)
 - [Mail & Local Development](#mail-and-local-development)
 - [Events](#events)
 - [Custom Transports](#custom-transports)
@@ -929,7 +931,10 @@ Once you have implemented the interface, Laravel will automatically use the pref
     Mail::to($request->user())->send(new OrderShipped($order));
 
 <a name="testing-mailables"></a>
-## Testing Mailables
+## Testing
+
+<a name="testing-mailable-content"></a>
+### Testing Mailable Content
 
 Laravel provides a variety of methods for inspecting your mailable's structure. In addition, Laravel provides several convenient methods for testing that your mailable contains the content that you expect. These methods are: `assertSeeInHtml`, `assertDontSeeInHtml`, `assertSeeInOrderInHtml`, `assertSeeInText`, `assertDontSeeInText`, `assertSeeInOrderInText`, `assertHasAttachment`, `assertHasAttachedData`, `assertHasAttachmentFromStorage`, and `assertHasAttachmentFromStorageDisk`.
 
@@ -968,9 +973,98 @@ As you might expect, the "HTML" assertions assert that the HTML version of your
     }
 
 <a name="testing-mailable-sending"></a>
-#### Testing Mailable Sending
+### Testing Mailable Sending
+
+We suggest testing the content of your mailables separately from your tests that assert that a given mailable was "sent" to a specific user. Typically, the content of mailables it not relevant to the code you are testing, and it is sufficient to simply assert that Laravel was instructed to send a given mailable.
+
+You may use the `Mail` facade's `fake` method to prevent mail from being sent. After calling the `Mail` facade's `fake` method, you may then assert that mailables were instructed to be sent to users and even inspect the data the mailables received:
+
+    <?php
+
+    namespace Tests\Feature;
+
+    use App\Mail\OrderShipped;
+    use Illuminate\Support\Facades\Mail;
+    use Tests\TestCase;
+
+    class ExampleTest extends TestCase
+    {
+        public function test_orders_can_be_shipped(): void
+        {
+            Mail::fake();
+
+            // Perform order shipping...
+
+            // Assert that no mailables were sent...
+            Mail::assertNothingSent();
+
+            // Assert that a mailable was sent...
+            Mail::assertSent(OrderShipped::class);
+
+            // Assert a mailable was sent twice...
+            Mail::assertSent(OrderShipped::class, 2);
+
+            // Assert a mailable was not sent...
+            Mail::assertNotSent(AnotherMailable::class);
+        }
+    }
+
+If you are queueing mailables for delivery in the background, you should use the `assertQueued` method instead of `assertSent`:
+
+    Mail::assertQueued(OrderShipped::class);
+
+    Mail::assertNotQueued(OrderShipped::class);
+
+    Mail::assertNothingQueued();
+
+You may pass a closure to the `assertSent`, `assertNotSent`, `assertQueued`, or `assertNotQueued` methods in order to assert that a mailable was sent that passes a given "truth test". If at least one mailable was sent that passes the given truth test then the assertion will be successful:
 
-We suggest testing the content of your mailables separately from your tests that assert that a given mailable was "sent" to a specific user. To learn how to test that mailables were sent, check out our documentation on the [Mail fake](/docs/{{version}}/mocking#mail-fake).
+    Mail::assertSent(function (OrderShipped $mail) use ($order) {
+        return $mail->order->id === $order->id;
+    });
+
+When calling the `Mail` facade's assertion methods, the mailable instance accepted by the provided closure exposes helpful methods for examining the mailable:
+
+    Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($user) {
+        return $mail->hasTo($user->email) &&
+               $mail->hasCc('...') &&
+               $mail->hasBcc('...') &&
+               $mail->hasReplyTo('...') &&
+               $mail->hasFrom('...') &&
+               $mail->hasSubject('...');
+    });
+
+The mailable instance also includes several helpful methods for examining the attachments on a mailable:
+
+    use Illuminate\Mail\Mailables\Attachment;
+
+    Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
+        return $mail->hasAttachment(
+            Attachment::fromPath('/path/to/file')
+                    ->as('name.pdf')
+                    ->withMime('application/pdf')
+        );
+    });
+
+    Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) {
+        return $mail->hasAttachment(
+            Attachment::fromStorageDisk('s3', '/path/to/file')
+        );
+    });
+
+    Mail::assertSent(OrderShipped::class, function (OrderShipped $mail) use ($pdfData) {
+        return $mail->hasAttachment(
+            Attachment::fromData(fn () => $pdfData, 'name.pdf')
+        );
+    });
+
+You may have noticed that there are two methods for asserting that mail was not sent: `assertNotSent` and `assertNotQueued`. Sometimes you may wish to assert that no mail was sent **or** queued. To accomplish this, you may use the `assertNothingOutgoing` and `assertNotOutgoing` methods:
+
+    Mail::assertNothingOutgoing();
+
+    Mail::assertNotOutgoing(function (OrderShipped $mail) use ($order) {
+        return $mail->order->id === $order->id;
+    });
 
 <a name="mail-and-local-development"></a>
 ## Mail & Local Development