[FEATURE REQUEST] WP Mail Module

[TimothyBJacobs]

Is your feature request related to a problem? Please describe. I want to be able to assert that an email has been sent and interact with the sent emails.

Describe the solution you'd like A WPMail that can see email messages, subjects, and click on links.

Alternatives considered Setting up some of the existing more general purpose mail modules codeception provides.

Additional context I like how simple it is to use a custom module instead of having to worry about setting up an SMTP server of some kind.

I've developed a helper module for the that we use internally. Do you think this would be valuable to have in wp-browser? If so, I can clean it up and add a PR.

<?php

namespace Helper;

use Codeception\Exception\ModuleConfigException;
use Codeception\Lib\Interfaces\DependsOnModule;
use Codeception\Lib\Interfaces\Web;
use Codeception\Module;
use Codeception\TestInterface;
use tad\WPBrowser\Filesystem\Utils;

class WPMail extends Module implements DependsOnModule {

    protected $requiredFields = [ 'wpRootFolder' ];

    /**
     * @var array
     */
    protected $config = [
        'mu-plugins' => '/wp-content/mu-plugins',
        'uploads'    => '/wp-content/uploads',
    ];

    protected $prettyName = 'WPMail';

    /** @var Web */
    protected $web;

    protected $pluginFile;
    protected $dataFile;

    public function _initialize() {
        $this->ensureWpRootFolder();
        $this->ensureOptionalPaths();

        $this->pluginFile = $this->config['mu-plugins'] . 'wp-mail.php';
        $this->dataFile   = $this->config['uploads'] . 'wp-mail-codeception.json';
    }

    public function _beforeSuite( $settings = [] ) {
        copy( codecept_data_dir( 'mu-plugins/wp-mail.php' ), $this->pluginFile );
    }

    public function _afterSuite() {
        if ( file_exists( $this->pluginFile ) ) {
            unlink( $this->pluginFile );
        }
    }

    public function _before( TestInterface $test ) {
        $this->ensureOptionalPaths( false );

        if ( file_exists( $this->dataFile ) ) {
            unlink( $this->dataFile );
        }
    }

    public function _inject( Web $web ) {
        $this->web = $web;
    }

    public function _depends() {
        return [ Web::class => 'Browser required' ];
    }

    /**
     * @When I click :link in the last email
     *
     * @param string $link
     * @param string $context
     */
    public function clickInLastEmailMessage( $link, $context = '' ) {
        $helper = new HtmlMatcherHelper( $this->web, $this->getLatestEmail()['message'] );
        $helper->click( $link, $context );
    }

    /**
     * @Then I see :subject in the last email subject
     *
     * @param string $subject
     */
    public function seeInLastEmailSubject( $subject ) {
        $email = $this->getLatestEmail();

        $this->assertStringContainsString( $subject, $email['subject'] );
    }

    /**
     * @Then I see :contents in the last email message
     *
     * @param string $message
     */
    public function seeInLastEmailMessage( $message ) {
        $email = $this->getLatestEmail();

        $helper = new HtmlMatcherHelper( $this->web, $email['message'] );
        $helper->see( $message );
    }

    /**
     * Checks the WordPress root folder exists and is a WordPress root folder.
     *
     * @throws \Codeception\Exception\ModuleConfigException if the WordPress root folder does not exist
     *                                                      or is not a valid WordPress root folder.
     */
    protected function ensureWpRootFolder() {
        $wpRoot = $this->config['wpRootFolder'];

        if ( ! is_dir( $wpRoot ) ) {
            $wpRoot = codecept_root_dir( Utils::unleadslashit( $wpRoot ) );
        }

        $message = "[{$wpRoot}] is not a valid WordPress root folder.\n\nThe WordPress root folder is the one that "
                   . "contains the 'wp-load.php' file.";

        if ( ! ( is_dir( $wpRoot ) && is_readable( $wpRoot ) && is_writable( $wpRoot ) ) ) {
            throw new ModuleConfigException( __CLASS__, $message );
        }

        if ( ! file_exists( $wpRoot . '/wp-load.php' ) ) {
            throw new ModuleConfigException( __CLASS__, $message );
        }

        $this->config['wpRootFolder'] = Utils::untrailslashit( $wpRoot ) . DIRECTORY_SEPARATOR;
    }

    /**
     * Sets and checks that the optional paths, if set, are actually valid.
     *
     * @param bool $check Whether to check the paths for existence or not.
     *
     * @throws \Codeception\Exception\ModuleConfigException If one of the paths does not exist.
     */
    protected function ensureOptionalPaths( $check = true ) {
        $optionalPaths = [
            'mu-plugins' => [
                'mustExist' => true,
                'default'   => '/wp-content/mu-plugins',
            ],
            'uploads'    => [
                'mustExist' => true,
                'default'   => '/wp-content/uploads',
            ],
        ];

        $wpRoot = Utils::untrailslashit( $this->config['wpRootFolder'] );

        foreach ( $optionalPaths as $configKey => $info ) {
            if ( empty( $this->config[ $configKey ] ) ) {
                $path = $info['default'];
            } else {
                $path = $this->config[ $configKey ];
            }
            if ( ! is_dir( $path ) || ( $configKey === 'mu-plugins' && ! is_dir( dirname( $path ) ) ) ) {
                $path         = Utils::unleadslashit( str_replace( $wpRoot, '', $path ) );
                $absolutePath = $wpRoot . DIRECTORY_SEPARATOR . $path;
            } else {
                $absolutePath = $path;
            }

            if ( $check ) {
                $mustExistAndIsNotDir = $info['mustExist'] && ! is_dir( $absolutePath );

                if ( $mustExistAndIsNotDir ) {
                    if ( ! mkdir( $absolutePath, 0777, true ) && ! is_dir( $absolutePath ) ) {
                        throw new ModuleConfigException(
                            __CLASS__,
                            "The {$configKey} config path [{$path}] does not exist."
                        );
                    }
                }
            }

            $this->config[ $configKey ] = Utils::untrailslashit( $absolutePath ) . DIRECTORY_SEPARATOR;
        }
    }

    /**
     * Get the latest email sent.
     *
     * @return array
     */
    protected function getLatestEmail() {
        foreach ( array_reverse( $this->getEmails() ) as $email ) {
            return $email;
        }

        $this->fail( 'No email found.' );
    }

    /**
     * Get a list of all the emails sent during the test.
     *
     * @return array
     */
    protected function getEmails() {
        $file   = $this->dataFile;
        $emails = [];

        if ( file_exists( $file ) && ( $contents = file_get_contents( $file ) ) && $json = json_decode( $contents, true ) ) {
            $emails = $json;
        }

        $this->debugSection( 'Emails', "\n" . json_encode( $emails, JSON_PRETTY_PRINT ) );

        return $emails;
    }

    protected function debugSection( $title, $message ) {
        parent::debugSection( $this->prettyName . ' ' . $title, $message );
    }
}

<?php
/*
 * Plugin Name: WP Mail Codeception Helper
 */

function wp_mail( $to, $subject, $message, $headers = '', $attachments = array() ) {

    $file = wp_upload_dir()['basedir'] . '/wp-mail-codeception.json';

    if ( ! file_exists( $file ) ) {
        touch( $file );
    }

    $json     = [];
    $contents = file_get_contents( $file );

    if ( $contents && $decoded = json_decode( $contents, true ) ) {
        $json = $decoded;
    }

    $json[] = compact( 'to', 'subject', 'message', 'headers', 'attachments' );

    file_put_contents( $file, json_encode( $json ) );

    return true;
}

<?php

namespace Helper;

use Codeception\Exception\ElementNotFound;
use Codeception\Exception\MalformedLocatorException;
use Codeception\Exception\ModuleException;
use Codeception\Exception\TestRuntimeException;
use Codeception\Lib\Interfaces\Web;
use Codeception\PHPUnit\Constraint\Crawler as CrawlerConstraint;
use Codeception\PHPUnit\Constraint\CrawlerNot as CrawlerNotConstraint;
use Codeception\PHPUnit\Constraint\Page as PageConstraint;
use Codeception\Util\Locator;
use Codeception\Util\Shared\Asserts;
use Symfony\Component\DomCrawler\Crawler;
use Symfony\Component\DomCrawler\Link;

class HtmlMatcherHelper {

    use Asserts;

    /** @var Web */
    private $web;

    /** @var string */
    protected $html;

    /** @var string */
    protected $baseUrl;

    /** @var Crawler */
    protected $crawler;

    /**
     * HtmlMatcherHelper constructor.
     *
     * @param Web    $web
     * @param string $html
     * @param string $baseUrl
     */
    public function __construct( Web $web, $html, $baseUrl = 'http://email/' ) {
        $this->web     = $web;
        $this->html    = $html;
        $this->baseUrl = $baseUrl;
        $this->crawler = new Crawler( $this->html, $this->baseUrl );
    }

    /**
     * @return Crawler
     * @throws ModuleException
     */
    private function getCrawler() {
        if ( ! $this->crawler ) {
            throw new ModuleException( $this, 'Crawler is null. Perhaps you forgot to call "amOnPage"?' );
        }

        return $this->crawler;
    }

    public function click( $link, $context = null ) {
        if ( $context ) {
            $this->crawler = $this->match( $context );
        }

        if ( is_array( $link ) ) {
            $this->clickByLocator( $link );

            return;
        }

        $anchor = $this->strictMatch( [ 'link' => $link ] );

        if ( ! count( $anchor ) ) {
            $anchor = $this->getCrawler()->selectLink( $link );
        }

        if ( count( $anchor ) ) {
            $this->openHrefFromDomNode( $anchor->getNode( 0 ) );

            return;
        }

        try {
            $this->clickByLocator( $link );
        } catch ( MalformedLocatorException $e ) {
            throw new ElementNotFound( "name=$link", "'$link' is invalid CSS and XPath selector and Link or Button" );
        }
    }

    /**
     * @param $link
     *
     * @return bool
     */
    protected function clickByLocator( $link ) {
        $nodes = $this->match( $link );
        if ( ! $nodes->count() ) {
            throw new ElementNotFound( $link, 'Link or Button by name or CSS or XPath' );
        }

        foreach ( $nodes as $node ) {
            $tag = $node->tagName;

            if ( $tag === 'a' ) {
                $this->openHrefFromDomNode( $node );

                return true;
            }
        }
    }

    private function openHrefFromDomNode( \DOMNode $node ) {
        $link = new Link( $node, $this->getBaseUrl() );
        $this->web->amOnPage( preg_replace( '/#.*/', '', $link->getUri() ) );
    }

    private function getBaseUrl() {
        return $this->baseUrl;
    }

    public function see( $text, $selector = null ) {
        if ( ! $selector ) {
            $this->assertPageContains( $text );

            return;
        }

        $nodes = $this->match( $selector );
        $this->assertDomContains( $nodes, $this->stringifySelector( $selector ), $text );
    }

    public function dontSee( $text, $selector = null ) {
        if ( ! $selector ) {
            $this->assertPageNotContains( $text );

            return;
        }

        $nodes = $this->match( $selector );
        $this->assertDomNotContains( $nodes, $this->stringifySelector( $selector ), $text );
    }

    public function seeInSource( $raw ) {
        $this->assertPageSourceContains( $raw );
    }

    public function dontSeeInSource( $raw ) {
        $this->assertPageSourceNotContains( $raw );
    }

    public function seeLink( $text, $url = null ) {
        $crawler = $this->getCrawler()->selectLink( $text );
        if ( $crawler->count() === 0 ) {
            $this->fail( "No links containing text '$text' were found in page " . $this->_getCurrentUri() );
        }
        if ( $url ) {
            $crawler = $crawler->filterXPath( sprintf( './/a[substring(@href, string-length(@href) - string-length(%1$s) + 1)=%1$s]', Crawler::xpathLiteral( $url ) ) );
            if ( $crawler->count() === 0 ) {
                $this->fail( "No links containing text '$text' and URL '$url' were found in page " . $this->_getCurrentUri() );
            }
        }

        $this->assertTrue( true );
    }

    public function dontSeeLink( $text, $url = null ) {
        $crawler = $this->getCrawler()->selectLink( $text );
        if ( ! $url ) {
            if ( $crawler->count() > 0 ) {
                $this->fail( "Link containing text '$text' was found in page " . $this->_getCurrentUri() );
            }
        }
        $crawler = $crawler->filterXPath( sprintf( './/a[substring(@href, string-length(@href) - string-length(%1$s) + 1)=%1$s]', Crawler::xpathLiteral( $url ) ) );
        if ( $crawler->count() > 0 ) {
            $this->fail( "Link containing text '$text' and URL '$url' was found in page " . $this->_getCurrentUri() );
        }
    }

    /**
     * @return string
     * @throws ModuleException
     */
    public function _getCurrentUri() {
        return $this->baseUrl;
    }

    /**
     * @param $selector
     *
     * @return Crawler
     */
    protected function match( $selector ) {
        if ( is_array( $selector ) ) {
            return $this->strictMatch( $selector );
        }

        if ( Locator::isCSS( $selector ) ) {
            return $this->getCrawler()->filter( $selector );
        }
        if ( Locator::isXPath( $selector ) ) {
            return $this->getCrawler()->filterXPath( $selector );
        }
        throw new MalformedLocatorException( $selector, 'XPath or CSS' );
    }

    /**
     * @param array $by
     *
     * @return Crawler
     * @throws TestRuntimeException
     */
    protected function strictMatch( array $by ) {
        $type    = key( $by );
        $locator = $by[ $type ];
        switch ( $type ) {
            case 'id':
                return $this->filterByCSS( "#$locator" );
            case 'name':
                return $this->filterByXPath( sprintf( './/*[@name=%s]', Crawler::xpathLiteral( $locator ) ) );
            case 'css':
                return $this->filterByCSS( $locator );
            case 'xpath':
                return $this->filterByXPath( $locator );
            case 'link':
                return $this->filterByXPath( sprintf( './/a[.=%s or contains(./@title, %s)]', Crawler::xpathLiteral( $locator ), Crawler::xpathLiteral( $locator ) ) );
            case 'class':
                return $this->filterByCSS( ".$locator" );
            default:
                throw new TestRuntimeException(
                    "Locator type '$by' is not defined. Use either: xpath, css, id, link, class, name"
                );
        }
    }

    protected function filterByAttributes( Crawler $nodes, array $attributes ) {
        foreach ( $attributes as $attr => $val ) {
            $nodes = $nodes->reduce(
                function ( Crawler $node ) use ( $attr, $val ) {
                    return $node->attr( $attr ) == $val;
                }
            );
        }

        return $nodes;
    }

    public function grabTextFrom( $cssOrXPathOrRegex ) {
        if ( @preg_match( $cssOrXPathOrRegex, $this->html, $matches ) ) {
            return $matches[1];
        }
        $nodes = $this->match( $cssOrXPathOrRegex );
        if ( $nodes->count() ) {
            return $nodes->first()->text();
        }
        throw new ElementNotFound( $cssOrXPathOrRegex, 'Element that matches CSS or XPath or Regex' );
    }

    public function grabAttributeFrom( $cssOrXpath, $attribute ) {
        $nodes = $this->match( $cssOrXpath );
        if ( ! $nodes->count() ) {
            throw new ElementNotFound( $cssOrXpath, 'Element that matches CSS or XPath' );
        }

        return $nodes->first()->attr( $attribute );
    }

    public function grabMultiple( $cssOrXpath, $attribute = null ) {
        $result = [];
        $nodes  = $this->match( $cssOrXpath );

        foreach ( $nodes as $node ) {
            if ( $attribute !== null ) {
                $result[] = $node->getAttribute( $attribute );
            } else {
                $result[] = $node->textContent;
            }
        }

        return $result;
    }

    /**
     * Grabs current page source code.
     *
     * @return string Current page source code.
     * @throws ModuleException if no page was opened.
     *
     */
    public function grabPageSource() {
        return $this->html;
    }

    private function stringifySelector( $selector ) {
        if ( is_array( $selector ) ) {
            return trim( json_encode( $selector ), '{}' );
        }

        return $selector;
    }

    public function seeElement( $selector, $attributes = [] ) {
        $nodes    = $this->match( $selector );
        $selector = $this->stringifySelector( $selector );
        if ( ! empty( $attributes ) ) {
            $nodes    = $this->filterByAttributes( $nodes, $attributes );
            $selector .= "' with attribute(s) '" . trim( json_encode( $attributes ), '{}' );
        }
        $this->assertDomContains( $nodes, $selector );
    }

    public function dontSeeElement( $selector, $attributes = [] ) {
        $nodes    = $this->match( $selector );
        $selector = $this->stringifySelector( $selector );
        if ( ! empty( $attributes ) ) {
            $nodes    = $this->filterByAttributes( $nodes, $attributes );
            $selector .= "' with attribute(s) '" . trim( json_encode( $attributes ), '{}' );
        }
        $this->assertDomNotContains( $nodes, $selector );
    }

    public function seeNumberOfElements( $selector, $expected ) {
        $counted = count( $this->match( $selector ) );
        if ( is_array( $expected ) ) {
            list( $floor, $ceil ) = $expected;
            $this->assertTrue(
                $floor <= $counted && $ceil >= $counted,
                'Number of elements counted differs from expected range'
            );
        } else {
            $this->assertEquals(
                $expected,
                $counted,
                'Number of elements counted differs from expected number'
            );
        }
    }

    protected function assertDomContains( $nodes, $message, $text = '' ) {
        $constraint = new CrawlerConstraint( $text, $this->_getCurrentUri() );
        $this->assertThat( $nodes, $constraint, $message );
    }

    protected function assertDomNotContains( $nodes, $message, $text = '' ) {
        $constraint = new CrawlerNotConstraint( $text, $this->_getCurrentUri() );
        $this->assertThat( $nodes, $constraint, $message );
    }

    protected function assertPageContains( $needle, $message = '' ) {
        $constraint = new PageConstraint( $needle, $this->_getCurrentUri() );
        $this->assertThat(
            $this->getNormalizedResponseContent(),
            $constraint,
            $message
        );
    }

    protected function assertPageNotContains( $needle, $message = '' ) {
        $constraint = new PageConstraint( $needle, $this->_getCurrentUri() );
        $this->assertThatItsNot(
            $this->getNormalizedResponseContent(),
            $constraint,
            $message
        );
    }

    protected function assertPageSourceContains( $needle, $message = '' ) {
        $constraint = new PageConstraint( $needle, $this->_getCurrentUri() );
        $this->assertThat(
            $this->html,
            $constraint,
            $message
        );
    }

    protected function assertPageSourceNotContains( $needle, $message = '' ) {
        $constraint = new PageConstraint( $needle, $this->_getCurrentUri() );
        $this->assertThatItsNot(
            $this->html,
            $constraint,
            $message
        );
    }

    /**
     * @param $locator
     *
     * @return Crawler
     */
    protected function filterByCSS( $locator ) {
        if ( ! Locator::isCSS( $locator ) ) {
            throw new MalformedLocatorException( $locator, 'css' );
        }

        return $this->getCrawler()->filter( $locator );
    }

    /**
     * @param $locator
     *
     * @return Crawler
     */
    protected function filterByXPath( $locator ) {
        if ( ! Locator::isXPath( $locator ) ) {
            throw new MalformedLocatorException( $locator, 'xpath' );
        }

        return $this->getCrawler()->filterXPath( $locator );
    }

    /**
     * @return string
     */
    protected function getNormalizedResponseContent() {
        $content = $this->html;
        // Since strip_tags has problems with JS code that contains
        // an <= operator the script tags have to be removed manually first.
        $content = preg_replace( '#<script(.*?)>(.*?)</script>#is', '', $content );

        $content = strip_tags( $content );
        $content = html_entity_decode( $content, ENT_QUOTES );
        $content = str_replace( "\n", ' ', $content );
        $content = preg_replace( '/\s{2,}/', ' ', $content );

        return $content;
    }

    protected function debugSection( $title, $message ) {
        if ( is_array( $message ) || is_object( $message ) ) {
            $message = stripslashes( json_encode( $message ) );
        }

        codecept_debug( "[$title] $message" );
    }
}

[lucatume]

@TimothyBJacobs this would indeed be useful!

Thanks for sharing the code, I feel some duplication could be avoided by:

1. using the WPFilesystem module for the WordPress directory checks and the file operations; I would make this an internal dependency, not required in the suite configuration file.
2. I've got mixed feelings about the module dependency on a Web one; I see how you use it in the context of acceptance tests, and understand its advantages, yet I can also think of someone just willing to assert on email contents w/o clicking on anything. As a first reaction I would "split" the module in two: a "base" WPMail one and one, extending it with web capabilities, e.g. WPWebMail.

[lucatume]

I will get back to this later, and comment further, trying to explain myself better.

I think this is a great idea!

[TimothyBJacobs]

Thanks @lucatume! I agree, splitting the module to have a WPWebMail would make a lot of sense.

I don't totally understand what you mean by using WPFilesystem as an internal dependency.

[lucatume]

Ignore the Stalebot notice, this is a good idea and I will tackle it.

[lucatume]

Still a good idea, targeting version 4

[github-actions[bot]]

This issue is marked stale because it has been open 20 days with no activity. Remove stale label or comment or this will be closed in 5 days.

[github-actions[bot]]

This issue was closed because it has been stalled for 5 days with no activity.