Oh Dear is the all-in-one monitoring tool for your entire website. We monitor uptime, SSL certificates, broken links, scheduled tasks and more. You'll get a notifications for us when something's wrong. All that paired with a developer friendly API and kick-ass documentation. O, and you'll also be able to create a public status page under a minute. Start monitoring using our free trial now.

Improving assertions on Laravel fakes

Original – by Freek Van der Herten – 4 minute read

Laravel has some cool fakes that can help you with testing your code. In this short blog post, I'd like to show you a little tip on how to get better feedback when a test that contains such a fake fails.

How to use a fake

Let's start with an example of a fake. You can skip to the next section if you've already worked with fakes.

Imagine your application sends a mail. You want to test if that mail is being sent correctly. The first step would be to set up the fake. Laravel makes this incredibly easy. Here's what you need to do:

use Illuminate\Support\Facades\Mail;

// inside a PHPUnit test class

/** @test */
public function this_is_your_test() 

That fake method will swap the real mailer (that Laravel already set up) in the IoC container by a fake one. That fake one will not send the mail.

With this in place, you can test if a mail has been sent. You have to pass your mailable class to assertSent.

use Illuminate\Support\Facades\Mail;

/** @test */
public function this_is_your_test() 

Improving assertions on fakes

That assertSent method accepts a callable as a second argument. That callable will receive the mailable. In that callable, you can use methods like hasTo, hasCc to assert that the mailable is configured correctly. The docs contain the following example:

 // Assert a message was sent to the given users...
 Mail::assertSent(OrderShipped::class, function ($mail) use ($user) {
     return $mail->hasTo($user->email) &&
            $mail->hasCc('...') &&

Now, the test only passes when that callable returns true. Nice!

But what if for some reason that callable doesn't return false? The failed test will output a message, not unlike this one:

The expected [OrderShipped::class] mailable was not sent. 

The problem here is that it's not clear if the to, cc or bcc is not correct. Let's improve that.

Probably you're using testing the mails inside of a PHPUnit test. Instead of just having one return statement in the callable, let's use PHPUnit assertions.

Mail::assertSent(OrderShipped::class, function ($mail) use ($user) {

   return true;

Sure, it's a bit more code to type. But with these assertions in place, a failing test will now also report the line number of the failed assertion, so you immediately know if either to, cc or bcc didn't contain the expected addresses.

You could opt to pass a custom message as a second argument to assertTrue. That message will be displayed when the assertion fails.

Mail::assertSent(OrderShipped::class, function ($mail) use ($user) {
   $this->assertTrue($mail->hasTo($user->email), 'Unexpected to');
   $this->assertTrue($mail->hasCc('...'), 'Unexpected cc');
   $this->assertTrue($mail->hasBcc('...'), 'Unexpected bcc');

   return true;

In conclusion

Laravel's fakes are fantastic. In this post, we've only used the mail specific one. But there are also fakes available for events, notifications, queues, ... Most of the assert methods on these fakes accept a callable as a second argument. Here's a real life refactor from returning a boolean to using assertions.

You can make a failing test much more readable buy not just returning a boolean in the callables you pass, but to use PHPUnit assertion methods inside of them.

Have fun testing!

Stay up to date with all things Laravel, PHP, and JavaScript.

You can follow me on these platforms:

On all these platforms, regularly share programming tips, and what I myself have learned in ongoing projects.

Every month I send out a newsletter containing lots of interesting stuff for the modern PHP developer.

Expect quick tips & tricks, interesting tutorials, opinions and packages. Because I work with Laravel every day there is an emphasis on that framework.

Rest assured that I will only use your email address to send you the newsletter and will not use it for any other purposes.


What are your thoughts on "Improving assertions on Laravel fakes"?

Comments powered by Laravel Comments
Want to join the conversation? Log in or create an account to post a comment.