feat: add html assertions

README.md

@@ -52,7 +52,17 @@ class MyTest extends KernelTestCase // or WebTestCase
                 ->assertTextContains('some text')
                 ->assertHtmlContains('some text')
                 ->assertContains('some text') // asserts text and html both contain a value
-                ->assertHasFile('file.txt', 'text/plain', 'Hello there!')
+
+                // html assertions (requires zenstruck/assert-html)
+                ->assertHtml()
+                    ->contains('some text')
+                    ->containsIn('h1', 'some title')
+                ->back() // go back to the TestEmail
+
+                // attachment assertions
+                ->assertHasFile('file.txt') // that file.txt is attached
+                ->assertHasFile('file.txt', 'text/plain') // that file.txt is attached with content type "text/plain"
+                ->assertHasFile('file.txt', 'text/plain', 'Hello there!') // that file.txt is attached with content type "text/plain" and content is "Hello there!"
 
                 // tag/meta data assertions (https://symfony.com/doc/current/mailer.html#adding-tags-and-metadata-to-emails)
                 ->assertHasTag('password-reset')
@@ -70,8 +80,12 @@ class MyTest extends KernelTestCase // or WebTestCase
 }
 ```
 
-**NOTE**: Emails are persisted between kernel reboots within each test. You can reset the
-collected emails with `$this->mailer()->reset()`.
+> **Note**: Emails are persisted between kernel reboots within each test. You can reset the
+> collected emails with `$this->mailer()->reset()`.
+
+> **Note**: `assertHtml()` requires [`zenstruck/assert-html`](https://github.com/zenstruck/assert-html).
+> Install with `composer require --dev zenstruck/assert-html`. [View documentation for all
+> available assertions](https://github.com/zenstruck/assert#html-expectations).
 
 ### SentEmails Collection
 

composer.json

@@ -25,6 +25,7 @@
         "symfony/phpunit-bridge": "^6.0",
         "symfony/var-dumper": "^5.4|^6.0",
         "symfony/yaml": "^5.4|^6.0",
+        "zenstruck/assert-html": "^0.2.1",
         "zenstruck/browser": "^1.0"
     },
     "config": {

src/Expectation/HtmlExpectation.php

@@ -0,0 +1,31 @@
+<?php
+
+/*
+ * This file is part of the zenstruck/mailer-test package.
+ *
+ * (c) Kevin Bond <kevinbond@gmail.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Zenstruck\Mailer\Test\Expectation;
+
+use Zenstruck\Assert\HtmlExpectation as BaseHtmlExpectation;
+use Zenstruck\Mailer\Test\TestEmail;
+
+/**
+ * @author Kevin Bond <kevinbond@gmail.com>
+ */
+final class HtmlExpectation extends BaseHtmlExpectation
+{
+    public function __construct(string $html, private TestEmail $email)
+    {
+        parent::__construct($html);
+    }
+
+    public function back(): TestEmail
+    {
+        return $this->email;
+    }
+}

src/TestEmail.php

@@ -17,8 +17,10 @@
 use Symfony\Component\Mime\Email;
 use Symfony\Component\Mime\Header\ParameterizedHeader;
 use Zenstruck\Assert;
+use Zenstruck\Assert\HtmlExpectation as BaseHtmlException;
 use Zenstruck\Callback;
 use Zenstruck\Callback\Parameter;
+use Zenstruck\Mailer\Test\Expectation\HtmlExpectation;
 
 /**
  * @mixin Email
@@ -300,6 +302,17 @@ final public function assertHasMetadata(string $expectedKey, ?string $expectedVa
         return $this;
     }
 
+    public function assertHtml(): HtmlExpectation
+    {
+        if (!\class_exists(BaseHtmlException::class)) {
+            throw new \LogicException('zenstruck/assert-html is required to use the HTML assertions (composer require --dev zenstruck/assert-html).');
+        }
+
+        Assert::that($this->email->getHtmlBody())->isNotEmpty('No [text/html] part found.');
+
+        return new HtmlExpectation((string) $this->email->getHtmlBody(), $this);
+    }
+
     /**
      * @return static
      */

tests/Fixture/Email1.php

@@ -34,7 +34,7 @@ public function __construct()
             ->attachFromPath(__DIR__.'/files/attachment.txt')
             ->attachFromPath(__DIR__.'/files/attachment.txt', 'name with space.txt')
             ->subject('email subject')
-            ->html('html body')
+            ->html('<h1>title</h1><div>html body</div>')
             ->text('text body')
         ;
 

tests/InteractsWithMailerTest.php

@@ -94,6 +94,10 @@ public function can_assert_email_sent(string $environment): void
                     ->assertSubjectContains('sub')
                     ->assertHtmlContains('html body')
                     ->assertTextContains('text body')
+                    ->assertHtml()
+                        ->contains('html body')
+                        ->containsIn('h1', 'title')
+                    ->back()
                     ->assertContains('body')
                     ->assertHasFile('attachment.txt')
                     ->assertHasFile('attachment.txt', 'text/plain')