Pulling in the orginal assertions & building test around them

Author: jimmypuckett

composer.json

@@ -17,7 +17,8 @@
     ],
     "require": {
         "php": ">=5.5.0",
-        "illuminate/support": "~5.1.10|5.2.*"
+        "illuminate/support": "~5.1.10|5.2.*",
+        "swiftmailer/swiftmailer": "~5.1"
     },
     "require-dev": {
         "mockery/mockery": "~0.9.1",

readme.md

@@ -27,3 +27,45 @@ Install Garbage Man:
 
 ## Using
 
+You mixin the assertions with the ```Spinen\MailAssertions\MailTracking``` trait.  You get the following assertions...
+
+* seeEmailContains
+* seeEmailEquals
+* seeEmailFrom
+* seeEmailSubject
+* seeEmailTo
+* seeEmailWasNotSent
+* seeEmailWasSent
+* seeEmailsSent
+
+NOTE: If there was more than 1 email sent, then the assertions look at the last email.
+
+## Example
+
+```php
+<?php
+use Illuminate\Foundation\Testing\WithoutMiddleware;
+use Illuminate\Foundation\Testing\DatabaseMigrations;
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+use Spinen\MailAssertions\MailTracking;
+
+class ExampleTest extends TestCase
+{
+    use MailTracking;
+    
+    /**
+     * A basic functional test example.
+     *
+     * @return void
+     */
+    public function testBasicExample()
+    {
+        $this->visit('/route-that-sends-an-email')
+             ->seeEmailWasSent()
+             ->seeEmailSubject('Hello World')
+             ->seeEmailTo('foo@bar.com')
+             ->seeEmailEquals('Click here to buy this jewelry.')
+             ->seeEmailContains('Click here');
+    }
+}
+```

src/.gitkeep

@@ -0,0 +1,42 @@
+<?php
+
+namespace Spinen\MailAssertions;
+
+use PHPUnit_Framework_TestCase;
+use Swift_Events_EventListener;
+use Swift_Events_SendEvent;
+
+/**
+ * Class MailRecorder
+ *
+ * @package Spinen\MailAssertions
+ */
+class MailRecorder implements Swift_Events_EventListener
+{
+    /**
+     * @var PHPUnit_Framework_TestCase
+     */
+    protected $test;
+
+    /**
+     * MailRecorder constructor.
+     *
+     * @param PHPUnit_Framework_TestCase $test
+     */
+    public function __construct(PHPUnit_Framework_TestCase $test)
+    {
+        $this->test = $test;
+    }
+
+    /**
+     * Called by Laravel before email is given to the transporter.
+     *
+     * Passes the email to the test, so that assertions can be ran against the messages.
+     *
+     * @param Swift_Events_SendEvent $event
+     */
+    public function beforeSendPerformed(Swift_Events_SendEvent $event)
+    {
+        $this->test->recordMail($event->getMessage());
+    }
+}

src/MailRecorder.php

@@ -0,0 +1,204 @@
+<?php
+
+namespace Spinen\MailAssertions;
+
+use Illuminate\Support\Facades\Mail;
+use PHPUnit_Framework_TestCase;
+use Swift_Message;
+
+/**
+ * Class MailTracking
+ *
+ * Trait to mixin to your test to allow for custom assertions when using PHPUnit with Laravel.
+ *
+ * This originally started out as a copy & paste from a video series that Jeffery Way did on laracasts.com.  If you do
+ * not have an account on Laracasts, you should get one.  It is an amazing resource to learn from.  We used that
+ * example & converted it to a package so that it would be easy to install.  We have also expanded on initial
+ * assertions.
+ *
+ * I WANT IT CLEAR THAT THIS WOULD NOT HAVE HAPPENED WITHOUT THE INITIAL WORK OF JEFFERY WAY.  WE ARE NOT CLAIMING TO
+ * BE THE CREATORS OF THE CONCEPT.
+ *
+ * @package Spinen\MailAssertions
+ * @see     https://gist.github.com/JeffreyWay/b501c53d958b07b8a332
+ * @tutorial https://laracasts.com/series/phpunit-testing-in-laravel/episodes/12
+ */
+trait MailTracking
+{
+    /**
+     * Delivered emails.
+     *
+     * @var array
+     */
+    protected $emails = [];
+
+    /**
+     * Register a listener for new emails.
+     *
+     * Called my PHPUnit before each test it run.  It registers the MailRecorder "plugin" with Swift, so that we can
+     * get a copy of each email that is sent during that test.
+     *
+     * @before
+     */
+    public function setUpMailTracking()
+    {
+        Mail::getSwiftMailer()
+            ->registerPlugin(new MailRecorder($this));
+    }
+
+    /**
+     * Retrieve the appropriate swift message.
+     *
+     * @param Swift_Message $message
+     *
+     * @return Swift_Message
+     */
+    protected function getEmail(Swift_Message $message = null)
+    {
+        $this->seeEmailWasSent();
+
+        return $message ?: $this->lastEmail();
+    }
+
+    /**
+     * Retrieve the mostly recently sent swift message.
+     */
+    protected function lastEmail()
+    {
+        return end($this->emails);
+    }
+
+    /**
+     * Store a new swift message.
+     *
+     * Collection of emails that were received by the MailRecorder plugin during a test.
+     *
+     * @param Swift_Message $email
+     */
+    public function recordMail(Swift_Message $email)
+    {
+        $this->emails[] = $email;
+    }
+
+    /**
+     * Assert that the last email's body contains the given text.
+     *
+     * @param string        $excerpt
+     * @param Swift_Message $message
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailContains($excerpt, Swift_Message $message = null)
+    {
+        $this->assertContains($excerpt, $this->getEmail($message)
+                                             ->getBody(), "No email containing the provided body was found.");
+
+        return $this;
+    }
+
+    /**
+     * Assert that the last email's body equals the given text.
+     *
+     * @param string        $body
+     * @param Swift_Message $message
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailEquals($body, Swift_Message $message = null)
+    {
+        $this->assertEquals($body, $this->getEmail($message)
+                                        ->getBody(), "No email with the provided body was sent.");
+
+        return $this;
+    }
+
+    /**
+     * Assert that the last email was delivered by the given address.
+     *
+     * @param string        $sender
+     * @param Swift_Message $message
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailFrom($sender, Swift_Message $message = null)
+    {
+        // TODO: Allow from to be an array to check email & name
+        $this->assertArrayHasKey($sender, (array)$this->getEmail($message)
+                                                      ->getFrom(), "No email was sent from $sender.");
+
+        return $this;
+    }
+
+    /**
+     * Assert that the given number of emails were sent.
+     *
+     * @param integer $count
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailsSent($count)
+    {
+        $emailsSent = count($this->emails);
+
+        $this->assertCount($count, $this->emails, "Expected $count emails to have been sent, but $emailsSent were.");
+
+        return $this;
+    }
+
+    /**
+     * Assert that the last email's subject matches the given string.
+     *
+     * @param string        $subject
+     * @param Swift_Message $message
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailSubject($subject, Swift_Message $message = null)
+    {
+        // TODO: Consider a subject contains like the message contains
+        $this->assertEquals($subject, $this->getEmail($message)
+                                           ->getSubject(), "No email with a subject of $subject was found.");
+
+        return $this;
+    }
+
+    /**
+     * Assert that the last email was sent to the given recipient.
+     *
+     * @param string        $recipient
+     * @param Swift_Message $message
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailTo($recipient, Swift_Message $message = null)
+    {
+        $this->assertArrayHasKey($recipient, (array)$this->getEmail($message)
+                                                         ->getTo(), "No email was sent to $recipient.");
+
+        return $this;
+    }
+
+    /**
+     * Assert that no emails were sent.
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailWasNotSent()
+    {
+        $this->assertEmpty($this->emails, 'Did not expect any emails to have been sent.');
+
+        return $this;
+    }
+
+    /**
+     * Assert that at least one email was sent.
+     *
+     * @return PHPUnit_Framework_TestCase $this
+     */
+    protected function seeEmailWasSent()
+    {
+        $this->assertNotEmpty($this->emails, 'No emails have been sent.');
+
+        return $this;
+    }
+}

src/MailTracking.php

@@ -0,0 +1,72 @@
+<?php
+
+namespace Spinen\MailAssertions;
+
+use Mockery;
+use PHPUnit_Framework_TestCase;
+use StdClass;
+use Swift_Events_SendEvent;
+
+/**
+ * Class MailRecorderTest
+ *
+ * @package Spinen\MailAssertions
+ */
+class MailRecorderTest extends TestCase
+{
+    /**
+     * @test
+     * @group unit
+     */
+    public function it_can_be_constructed()
+    {
+        $mail_recorder = new MailRecorder($this);
+
+        $this->assertInstanceOf(MailRecorder::class, $mail_recorder);
+    }
+
+    /**
+     * @test
+     * @group unit
+     * @expectedException PHPUnit_Framework_Error
+     */
+    public function it_cannot_be_constructed_without_a_PHPUnit_Framework_TestCase()
+    {
+        new MailRecorder();
+    }
+
+    /**
+     * @test
+     * @group unit
+     * @expectedException PHPUnit_Framework_Error
+     */
+    public function it_cannot_be_constructed_with_class_other_than_a_PHPUnit_Framework_TestCase()
+    {
+        new MailRecorder(new StdClass());
+    }
+
+    /**
+     * @test
+     * @group
+     */
+    public function it_records_the_message_on_the_test_by_calling_recordMail()
+    {
+        $test_mock = Mockery::mock(PHPUnit_Framework_TestCase::class);
+
+        $test_mock->shouldReceive('recordMail')
+                  ->once()
+                  ->with('message')
+                  ->andReturnNull();
+
+        $swift_message_event_mock = Mockery::mock(Swift_Events_SendEvent::class);
+
+        $swift_message_event_mock->shouldReceive('getMessage')
+                                 ->once()
+                                 ->withNoArgs()
+                                 ->andReturn('message');
+
+        $mail_recorder = new MailRecorder($test_mock);
+
+        $this->assertNull($mail_recorder->beforeSendPerformed($swift_message_event_mock));
+    }
+}