This document contains information about a future release and not the current stable version (3.1).
Be aware that information on this page may change and API's may not be stable for production use.
SilverStripe's test system has built-in support for testing emails sent using the Email class.
How it works
For this to work, you need to send emails using the
$e = new Email(); $e->To = "firstname.lastname@example.org"; $e->Subject = "Hi there"; $e->Body = "I just really wanted to email you and say hi."; $e->send();
send() method would send an email using PHP's
However, if you are running a SapphireTest test, then it holds off actually sending the email,
and instead lets you assert that an email was sent using this method.
$this->assertEmailSent("email@example.com", null, "/th.*e$/");
The arguments are
$body, and can take one of the three following types:
- A string: match exactly that string
null/false: match anything
- A PERL regular expression (starting with '/'): match that regular expression
How to use it
Given all of that, there is not a lot that you have to do in order to test emailing functionality in your application.
Whenever we include e-mailing functionality in our application,
we simply use
$this->assertEmailSent() to check our mail has been passed to PHP
What isn't tested
It's important to realise that this email testing doesn't actually test everything that there is to do with email. The focus of this email testing system is testing that your application is triggering emails correctly. It doesn't test your email infrastructure outside of the webserver. For example:
- It won't test that email is correctly configured on your webserver
- It won't test whether your emails are going to be lost in someone's spam filter
- It won't test bounce-handling or any other auxiliary services of email
How it's built
For those of you who want to dig a little deeper, here's a quick run-through of how the system has been built. As well as explaining how we built the email test, this is a good design pattern for making other "tricky external systems" testable:
Email::send()method makes uses of a static object,
Email::$mailer, to do the dirty work of calling mail(). The default mailer is an object of type
Mailer, which performs a normal send.
Email::set_mailer()can be called to load in a new mailer object.
Email::set_mailer(new TestMailer())to replace the default mailer with a
TestMailerobject. This replacement mailer doesn't actually do anything when it is asked to send an email; it just records the details of the email in an internal field that can be searched with
TestMailer::findEmails()to see if a mail-send was requested by the application.