Testing Mailable Content in Laravel 8

Tutorials

December 23rd, 2020

laravel-mailables.jpg

Laravel 8.18.0 added methods to test HTML and plain-text email bodies for mailables. These methods are documented, but I’d like to walk through a simple example to illustrate how useful these can be.

The documentation demonstrates the following methods you can use to test mailables:

1public function test_mailable_content()
2{
3 $user = User::factory()->create();
4 
5 $mailable = new InvoicePaid($user);
6 
7 $mailable->assertSeeInHtml($user->email);
8 $mailable->assertSeeInHtml('Invoice Paid');
9 
10 $mailable->assertSeeInText($user->email);
11 $mailable->assertSeeInText('Invoice Paid');
12}

As you can see, the mailable instances conveniently provide assertion methods you can use to ensure emails contain expected content. Let’s walk through a simple example that can help solidify this concept.

Getting Started

Let’s say you are building a simple email that sends a confirmation code to the user’s email to verify something before they are allowed to act. We will send an HTML version, but you can test plain-text versions of your email and refer to the above examples for the text assertions.

Let’s start with a new Laravel project using Laravel’s documented installation method for Laravel Sail:

1# I use ~/code/sandbox as path for playground projects
2cd ~/code/sandbox
3curl -s https://laravel.build/mailable-demo | bash

Once you have the project created, you can start the Laravel app server:

1vendor/bin/sail up -d

Creating the Mailable

We are ready to create the mailable we’ll be testing, along with the accompanying template. We’ll use the artisan console to create the class and create the template in our project:

1# Create the mailable
2sail artisan make:mail ConfirmationCode
3 
4# Create the template
5mkdir -p resources/views/emails
6echo 'Hello from HTML!' \
7 > resources/views/emails/confirmation-code.blade.php

Next, update the ConfirmationCode class to look as follows:

1<?php
2 
3namespace App\Mail;
4 
5use App\Models\User;
6use Illuminate\Bus\Queueable;
7use Illuminate\Mail\Mailable;
8use Illuminate\Queue\SerializesModels;
9 
10class ConfirmationCode extends Mailable
11{
12 use Queueable, SerializesModels;
13 
14 /**
15 * @var string
16 */
17 public $code;
18 
19 /**
20 * @var \App\Models\User
21 */
22 public $user;
23 
24 /**
25 * Create a new message instance.
26 *
27 * @param string $code
28 */
29 public function __construct(User $user, string $code)
30 {
31 $this->user = $user;
32 $this->code = $code;
33 }
34 
35 /**
36 * Build the message.
37 *
38 * @return $this
39 */
40 public function build()
41 {
42 return $this->view('emails.confirmation-code');
43 }
44}

We will use a simple string $code property for the mailable, but perhaps a real implementation might use a service responsible for generating random codes tied to a user.

Next, let’s use the provided tests/Feature/ExampleTest.php file to test our mailable:

1<?php
2 
3namespace Tests\Feature;
4 
5use App\Mail\ConfirmationCode;
6use App\Models\User;
7use Illuminate\Foundation\Testing\RefreshDatabase;
8use Tests\TestCase;
9 
10class ExampleTest extends TestCase
11{
12 use RefreshDatabase;
13 
14 /**
15 * A basic test example.
16 *
17 * @return void
18 */
19 public function testBasicTest()
20 {
21 $user = User::factory()->create();
22 $subject = new ConfirmationCode($user, '1234');
23 
24 $subject->assertSeeInHtml('Hello from HTML!');
25 }
26}

At this point your test should pass:

1vendor/bin/sail test tests/Feature
2 
3 PASS Tests\Feature\ExampleTest
4 ✓ basic test
5 
6 Tests: 1 passed
7 Time: 1.06s

Next, let’s adjust the test to expect the confirmation code:

1public function testBasicTest()
2{
3 $user = User::factory()->create();
4 $subject = new ConfirmationCode($user, '1234');
5 
6$subject->assertSeeInHtml('Hello ' . $user->name);
7$subject->assertSeeInHtml('Here is your confirmation code: <strong>1234</strong>');
8}

The test will fail now if you rerun it. Next, let’s update the template to include the user’s name and include the confirmation code:

1{{-- resources/emails/confirmation-code.blade.php --}}
2Hello {{ $user->name }}
3 
4Here is your confirmation code: <strong>{{ $code }}</strong>

At this point, your test will pass, and you can ensure that your mailable includes the necessary confirmation code!

In a real application, you’d likely generate the email code from a service and swap it out with a fake or a partial mock, but you can see how we can ensure the mailable template has the expected text. It is convenient that you can now test your mailables without additional work or packages directly! Be sure to check out the official Laravel Mail documentation to learn more about mailables.

Filed in:

Paul Redmond

Full stack web developer. Author of Lumen Programming Guide and Docker for PHP Developers.