From 19b425f21dfa3474141d715157021f4dab24a80b Mon Sep 17 00:00:00 2001
From: Tavo Nieves J <ganieves@outlook.com>
Date: Sat, 19 Jun 2021 23:41:48 -0500
Subject: [PATCH 1/3] Added assertions for Symfony Mime component

---
 src/Codeception/Module/Symfony.php            |  2 +
 .../Module/Symfony/MimeAssertionsTrait.php    | 72 +++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 src/Codeception/Module/Symfony/MimeAssertionsTrait.php

diff --git a/src/Codeception/Module/Symfony.php b/src/Codeception/Module/Symfony.php
index c7305bb0..c5e3baeb 100644
--- a/src/Codeception/Module/Symfony.php
+++ b/src/Codeception/Module/Symfony.php
@@ -16,6 +16,7 @@
 use Codeception\Module\Symfony\EventsAssertionsTrait;
 use Codeception\Module\Symfony\FormAssertionsTrait;
 use Codeception\Module\Symfony\MailerAssertionsTrait;
+use Codeception\Module\Symfony\MimeAssertionsTrait;
 use Codeception\Module\Symfony\ParameterAssertionsTrait;
 use Codeception\Module\Symfony\RouterAssertionsTrait;
 use Codeception\Module\Symfony\SecurityAssertionsTrait;
@@ -134,6 +135,7 @@ class Symfony extends Framework implements DoctrineProvider, PartedModule
     use EventsAssertionsTrait;
     use FormAssertionsTrait;
     use MailerAssertionsTrait;
+    use MimeAssertionsTrait;
     use ParameterAssertionsTrait;
     use RouterAssertionsTrait;
     use SecurityAssertionsTrait;
diff --git a/src/Codeception/Module/Symfony/MimeAssertionsTrait.php b/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
new file mode 100644
index 00000000..ea80e34a
--- /dev/null
+++ b/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
@@ -0,0 +1,72 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Codeception\Module\Symfony;
+
+use PHPUnit\Framework\Constraint\LogicalNot;
+use Symfony\Component\Mime\Email;
+use Symfony\Component\Mime\Test\Constraint as MimeConstraint;
+
+trait MimeAssertionsTrait
+{
+    public function assertEmailAddressContains(string $headerName, string $expectedValue, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new MimeConstraint\EmailAddressContains($headerName, $expectedValue));
+    }
+
+    public function assertEmailAttachmentCount(int $count, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new MimeConstraint\EmailAttachmentCount($count));
+    }
+
+    public function assertEmailHasHeader(string $headerName, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new MimeConstraint\EmailHasHeader($headerName));
+    }
+
+    public function assertEmailHeaderNotSame(string $headerName, string $expectedValue, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailHeaderSame($headerName, $expectedValue)));
+    }
+
+    public function assertEmailHeaderSame(string $headerName, string $expectedValue, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new MimeConstraint\EmailHeaderSame($headerName, $expectedValue));
+    }
+
+    public function assertEmailHtmlBodyContains(string $text, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new MimeConstraint\EmailHtmlBodyContains($text));
+    }
+
+    public function assertEmailHtmlBodyNotContains(string $text, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailHtmlBodyContains($text)));
+    }
+
+    public function assertEmailNotHasHeader(string $headerName, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailHasHeader($headerName)));
+    }
+
+    public function assertEmailTextBodyContains(string $text, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new MimeConstraint\EmailTextBodyContains($text));
+    }
+
+    public function assertEmailTextBodyNotContains(string $text, Email $email = null): void
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailTextBodyContains($text)));
+    }
+}
\ No newline at end of file

From 86893ccdb60bd90789dca032b6b3b1c5a9398ef5 Mon Sep 17 00:00:00 2001
From: Tavo Nieves J <ganieves@outlook.com>
Date: Mon, 5 Jul 2021 15:51:00 -0500
Subject: [PATCH 2/3] Added docs

---
 .../Module/Symfony/MimeAssertionsTrait.php    | 125 ++++++++++++++++--
 1 file changed, 115 insertions(+), 10 deletions(-)

diff --git a/src/Codeception/Module/Symfony/MimeAssertionsTrait.php b/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
index ea80e34a..c203159d 100644
--- a/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
+++ b/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
@@ -10,63 +10,168 @@
 
 trait MimeAssertionsTrait
 {
+    /**
+     * Verify that an email contains addresses with a [header](https://datatracker.ietf.org/doc/html/rfc4021)
+     * `$headerName` and its expected value `$expectedValue`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailAddressContains();
+     * ```
+     */
     public function assertEmailAddressContains(string $headerName, string $expectedValue, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new MimeConstraint\EmailAddressContains($headerName, $expectedValue));
     }
 
+    /**
+     * Verify that an email has sent the specified number `$count` of attachments.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailAttachmentCount();
+     * ```
+     */
     public function assertEmailAttachmentCount(int $count, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new MimeConstraint\EmailAttachmentCount($count));
     }
 
+    /**
+     * Verify that an email has a [header](https://datatracker.ietf.org/doc/html/rfc4021) `$headerName`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailHasHeader();
+     * ```
+     */
     public function assertEmailHasHeader(string $headerName, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new MimeConstraint\EmailHasHeader($headerName));
     }
 
+    /**
+     * Verify that the [header](https://datatracker.ietf.org/doc/html/rfc4021)
+     * `$headerName` of an email is not the expected one `$expectedValue`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailHeaderNotSame();
+     * ```
+     */
     public function assertEmailHeaderNotSame(string $headerName, string $expectedValue, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailHeaderSame($headerName, $expectedValue)));
     }
 
+    /**
+     * Verify that the [header](https://datatracker.ietf.org/doc/html/rfc4021)
+     * `$headerName` of an email is the same as expected `$expectedValue`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailHeaderSame();
+     * ```
+     */
     public function assertEmailHeaderSame(string $headerName, string $expectedValue, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new MimeConstraint\EmailHeaderSame($headerName, $expectedValue));
     }
 
+    /**
+     * Verify that the HTML body of an email contains `$text`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailHtmlBodyContains();
+     * ```
+     */
     public function assertEmailHtmlBodyContains(string $text, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new MimeConstraint\EmailHtmlBodyContains($text));
     }
 
+    /**
+     * Verify that the HTML body of an email does not contain a text `$text`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailHtmlBodyNotContains();
+     * ```
+     */
     public function assertEmailHtmlBodyNotContains(string $text, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailHtmlBodyContains($text)));
     }
 
+    /**
+     * Verify that an email does not have a [header](https://datatracker.ietf.org/doc/html/rfc4021) `$headerName`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailNotHasHeader();
+     * ```
+     */
     public function assertEmailNotHasHeader(string $headerName, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailHasHeader($headerName)));
     }
 
+    /**
+     * Verify the text body of an email contains a `$text`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailTextBodyContains();
+     * ```
+     */
     public function assertEmailTextBodyContains(string $text, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new MimeConstraint\EmailTextBodyContains($text));
     }
 
+    /**
+     * Verify that the text body of an email does not contain a `$text`.
+     * If the Email object is not specified, the last email sent is used instead.
+     *
+     * ```php
+     * <?php
+     * $I->assertEmailTextBodyNotContains();
+     * ```
+     */
     public function assertEmailTextBodyNotContains(string $text, Email $email = null): void
     {
-        $email = $email ?: $this->grabLastSentEmail();
+        $email = $this->verifyEmailObject($email, __FUNCTION__);
         $this->assertThat($email, new LogicalNot(new MimeConstraint\EmailTextBodyContains($text)));
     }
+
+    /**
+     * Returns the last email sent if $email is null. If no email has been sent it fails.
+     */
+    private function verifyEmailObject(?Email $email, string $function): Email
+    {
+        $email = $email ?: $this->grabLastSentEmail();
+        $errorMsgFormat = "There is no email to verify. An Email object was not specified when invoking '%s' and the application has not sent one.";
+        return $email ?: $this->fail(
+            sprintf($errorMsgFormat, $function)
+        );
+    }
 }
\ No newline at end of file

From ecc9fe9b5f864cd7059a830a86ac3807b84b145c Mon Sep 17 00:00:00 2001
From: Tavo Nieves J <ganieves@outlook.com>
Date: Tue, 6 Jul 2021 19:13:32 -0500
Subject: [PATCH 3/3] Added code examples

---
 .../Module/Symfony/MimeAssertionsTrait.php    | 20 +++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/Codeception/Module/Symfony/MimeAssertionsTrait.php b/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
index c203159d..9228602a 100644
--- a/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
+++ b/src/Codeception/Module/Symfony/MimeAssertionsTrait.php
@@ -17,7 +17,7 @@ trait MimeAssertionsTrait
      *
      * ```php
      * <?php
-     * $I->assertEmailAddressContains();
+     * $I->assertEmailAddressContains('To', 'jane_doe@example.com');
      * ```
      */
     public function assertEmailAddressContains(string $headerName, string $expectedValue, Email $email = null): void
@@ -32,7 +32,7 @@ public function assertEmailAddressContains(string $headerName, string $expectedV
      *
      * ```php
      * <?php
-     * $I->assertEmailAttachmentCount();
+     * $I->assertEmailAttachmentCount(1);
      * ```
      */
     public function assertEmailAttachmentCount(int $count, Email $email = null): void
@@ -47,7 +47,7 @@ public function assertEmailAttachmentCount(int $count, Email $email = null): voi
      *
      * ```php
      * <?php
-     * $I->assertEmailHasHeader();
+     * $I->assertEmailHasHeader('Bcc');
      * ```
      */
     public function assertEmailHasHeader(string $headerName, Email $email = null): void
@@ -63,7 +63,7 @@ public function assertEmailHasHeader(string $headerName, Email $email = null): v
      *
      * ```php
      * <?php
-     * $I->assertEmailHeaderNotSame();
+     * $I->assertEmailHeaderNotSame('To', 'john_doe@gmail.com');
      * ```
      */
     public function assertEmailHeaderNotSame(string $headerName, string $expectedValue, Email $email = null): void
@@ -79,7 +79,7 @@ public function assertEmailHeaderNotSame(string $headerName, string $expectedVal
      *
      * ```php
      * <?php
-     * $I->assertEmailHeaderSame();
+     * $I->assertEmailHeaderSame('To', 'jane_doe@gmail.com');
      * ```
      */
     public function assertEmailHeaderSame(string $headerName, string $expectedValue, Email $email = null): void
@@ -94,7 +94,7 @@ public function assertEmailHeaderSame(string $headerName, string $expectedValue,
      *
      * ```php
      * <?php
-     * $I->assertEmailHtmlBodyContains();
+     * $I->assertEmailHtmlBodyContains('Successful registration');
      * ```
      */
     public function assertEmailHtmlBodyContains(string $text, Email $email = null): void
@@ -109,7 +109,7 @@ public function assertEmailHtmlBodyContains(string $text, Email $email = null):
      *
      * ```php
      * <?php
-     * $I->assertEmailHtmlBodyNotContains();
+     * $I->assertEmailHtmlBodyNotContains('userpassword');
      * ```
      */
     public function assertEmailHtmlBodyNotContains(string $text, Email $email = null): void
@@ -124,7 +124,7 @@ public function assertEmailHtmlBodyNotContains(string $text, Email $email = null
      *
      * ```php
      * <?php
-     * $I->assertEmailNotHasHeader();
+     * $I->assertEmailNotHasHeader('Bcc');
      * ```
      */
     public function assertEmailNotHasHeader(string $headerName, Email $email = null): void
@@ -139,7 +139,7 @@ public function assertEmailNotHasHeader(string $headerName, Email $email = null)
      *
      * ```php
      * <?php
-     * $I->assertEmailTextBodyContains();
+     * $I->assertEmailTextBodyContains('Example text body');
      * ```
      */
     public function assertEmailTextBodyContains(string $text, Email $email = null): void
@@ -154,7 +154,7 @@ public function assertEmailTextBodyContains(string $text, Email $email = null):
      *
      * ```php
      * <?php
-     * $I->assertEmailTextBodyNotContains();
+     * $I->assertEmailTextBodyNotContains('My secret text body');
      * ```
      */
     public function assertEmailTextBodyNotContains(string $text, Email $email = null): void