Mail intercept

Writing tests can be hard. Should I mock? Perhaps I should spy? Or maybe there is a built in fake() for this?

Writing tests for mail can be even harder. Enter Laravel’s Mail Fake. Use that at the beginning of your test, do your heavy lifting, then run some assertions against the fake. It is extremely helpful to verify that mail gets sent out and peek at the mail to ensure it got sent to the right person. As a sidenote, a little known plus with faking mail is that it will disable mail from sending accidentally during tests. You never want to be the one who sent out a few hundred emails accidentally… but back to the subject at hand.

But faking mail can only take you so far. How do you test the email body contains the correct string? What about that custom header? Or even the subject? Those kinds of details need to be tested, but can’t be faked. Right Harry?

Say hello to Mail Intercept!

Mail Intercept for Laravel is a new way of testing mail by intercepting, not faking, email so we can dissect it, turn it upside down, and inspect everything.

Under the hood, it is quite simple in that it forces the mail driver to be an array pushing all those emails into memory. We then grab those emails and run assertions on them! That’s it, pretty simple really!

But we didn’t want to stop there. We wanted it to be really easy to run assertions against those emails to check for specific things. Here are the assertions available to you as of this writing:

$this->assertMailSentTo($to, $mail);
$this->assertMailNotSentTo($to, $mail);
$this->assertMailSentFrom($from, $mail);
$this->assertMailNotSentFrom($from, $mail);
$this->assertMailSubject($subject, $mail);
$this->assertMailNotSubject($subject, $mail);
$this->assertMailBodyContainsString($content, $mail);
$this->assertMailBodyNotContainsString($content, $mail);
$this->assertMailHasHeader($header, $mail);
$this->assertMailMissingHeader($header, $mail);
$this->assertMailHeaderIs($header, $value, $mail);
$this->assertMailHeaderIsNot($header, $value, $mail);

You will notice that each assertion accepts, as the last parameter, a $mail object. Where does that come from you might ask? Let’s look at a simple test to answer that question.

namespace Tests;
 
use App\Jobs\SomeJobThatSendsMail;
use Illuminate\Foundation\Testing\WithFaker;
use KirschbaumDevelopment\MailIntercept\WithMailInterceptor;
 
class MailTest extends TestCase
{
    use WithFaker;
    use WithMailInterceptor;
 
    public function testMail()
    {
        $this->interceptMail();
 
        $email = $this->faker->email;
 
        SomeJobThatSendsMail::dispatchNow($email);
 
        $interceptedMail = $this->interceptedMail()->first();
 
        $this->assertMailSentTo($email, $interceptedMail);
    }
}

The first thing to notice is the use of the WithMailInterceptor trait. This pulls in the ability to intercept and makes available our mail assertions.

Just like faking mail, we must call the $this->interceptMail() before mail gets sent.

After the mail is sent we need to retrieve the freshly sent mail. We grab these with $this->interceptedMail(). This will return a collection of sent mail. And since it is a collection, we can use the first() method to grab the only email we sent.

Now we can run all the assertions against that mail object. If instead we need to run assertions against multple emails, we can use the each() method to loop through them.

We’ve included a good starting point for assertions. However, if there aren’t enough for your liking, the mail object is an just an instance of Swift_Message with all of its available methods. Head over to the Swift Mailer Docs for all available methods.

Interested in using this test suite in your project now? Head over to Mail Intercept on Github, pull it into your project with Composer and start intercepting and testing mail with confidence!