Chris@0: <?php
Chris@0: 
Chris@0: namespace Drupal\Core\Test;
Chris@0: 
Chris@0: /**
Chris@0:  * Provides methods for testing emails sent during test runs.
Chris@0:  */
Chris@0: trait AssertMailTrait {
Chris@0: 
Chris@0:   /**
Chris@0:    * Gets an array containing all emails sent during this test case.
Chris@0:    *
Chris@0:    * @param array $filter
Chris@0:    *   An array containing key/value pairs used to filter the emails that are
Chris@0:    *   returned.
Chris@0:    *
Chris@0:    * @return array
Chris@0:    *   An array containing email messages captured during the current test.
Chris@0:    */
Chris@0:   protected function getMails(array $filter = []) {
Chris@0:     $captured_emails = $this->container->get('state')->get('system.test_mail_collector', []);
Chris@0:     $filtered_emails = [];
Chris@0: 
Chris@0:     foreach ($captured_emails as $message) {
Chris@0:       foreach ($filter as $key => $value) {
Chris@0:         if (!isset($message[$key]) || $message[$key] != $value) {
Chris@0:           continue 2;
Chris@0:         }
Chris@0:       }
Chris@0:       $filtered_emails[] = $message;
Chris@0:     }
Chris@0: 
Chris@0:     return $filtered_emails;
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that the most recently sent email message has the given value.
Chris@0:    *
Chris@0:    * The field in $name must have the content described in $value.
Chris@0:    *
Chris@0:    * @param string $name
Chris@0:    *   Name of field or message property to assert. Examples: subject, body,
Chris@0:    *   id, ...
Chris@0:    * @param string $value
Chris@0:    *   Value of the field to assert.
Chris@0:    * @param string $message
Chris@0:    *   (optional) A message to display with the assertion. Do not translate
Chris@17:    *   messages: use \Drupal\Component\Render\FormattableMarkup to embed
Chris@0:    *   variables in the message text, not t(). If left blank, a default message
Chris@0:    *   will be displayed.
Chris@0:    * @param string $group
Chris@0:    *   (optional) The group this message is in, which is displayed in a column
Chris@0:    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
Chris@0:    *   translate this string. Defaults to 'Email'; most tests do not override
Chris@0:    *   this default.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on pass, FALSE on fail.
Chris@0:    */
Chris@0:   protected function assertMail($name, $value = '', $message = '', $group = 'Email') {
Chris@0:     $captured_emails = $this->container->get('state')->get('system.test_mail_collector') ?: [];
Chris@0:     $email = end($captured_emails);
Chris@0:     return $this->assertTrue($email && isset($email[$name]) && $email[$name] == $value, $message, $group);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that the most recently sent email message has the string in it.
Chris@0:    *
Chris@0:    * @param string $field_name
Chris@0:    *   Name of field or message property to assert: subject, body, id, ...
Chris@0:    * @param string $string
Chris@0:    *   String to search for.
Chris@0:    * @param int $email_depth
Chris@0:    *   Number of emails to search for string, starting with most recent.
Chris@0:    * @param string $message
Chris@0:    *   (optional) A message to display with the assertion. Do not translate
Chris@17:    *   messages: use \Drupal\Component\Render\FormattableMarkup to embed
Chris@0:    *   variables in the message text, not t(). If left blank, a default message
Chris@0:    *   will be displayed.
Chris@0:    * @param string $group
Chris@0:    *   (optional) The group this message is in, which is displayed in a column
Chris@0:    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
Chris@0:    *   translate this string. Defaults to 'Other'; most tests do not override
Chris@0:    *   this default.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on pass, FALSE on fail.
Chris@0:    */
Chris@0:   protected function assertMailString($field_name, $string, $email_depth, $message = '', $group = 'Other') {
Chris@0:     $mails = $this->getMails();
Chris@0:     $string_found = FALSE;
Chris@0:     // Cast MarkupInterface objects to string.
Chris@0:     $string = (string) $string;
Chris@0:     for ($i = count($mails) - 1; $i >= count($mails) - $email_depth && $i >= 0; $i--) {
Chris@0:       $mail = $mails[$i];
Chris@0:       // Normalize whitespace, as we don't know what the mail system might have
Chris@0:       // done. Any run of whitespace becomes a single space.
Chris@0:       $normalized_mail = preg_replace('/\s+/', ' ', $mail[$field_name]);
Chris@0:       $normalized_string = preg_replace('/\s+/', ' ', $string);
Chris@0:       $string_found = (FALSE !== strpos($normalized_mail, $normalized_string));
Chris@0:       if ($string_found) {
Chris@0:         break;
Chris@0:       }
Chris@0:     }
Chris@0:     if (!$message) {
Chris@0:       $message = format_string('Expected text found in @field of email message: "@expected".', ['@field' => $field_name, '@expected' => $string]);
Chris@0:     }
Chris@0:     return $this->assertTrue($string_found, $message, $group);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Asserts that the most recently sent email message has the pattern in it.
Chris@0:    *
Chris@0:    * @param string $field_name
Chris@0:    *   Name of field or message property to assert: subject, body, id, ...
Chris@0:    * @param string $regex
Chris@0:    *   Pattern to search for.
Chris@0:    * @param string $message
Chris@0:    *   (optional) A message to display with the assertion. Do not translate
Chris@17:    *   messages: use \Drupal\Component\Render\FormattableMarkup to embed
Chris@0:    *   variables in the message text, not t(). If left blank, a default message
Chris@0:    *   will be displayed.
Chris@0:    * @param string $group
Chris@0:    *   (optional) The group this message is in, which is displayed in a column
Chris@0:    *   in test output. Use 'Debug' to indicate this is debugging output. Do not
Chris@0:    *   translate this string. Defaults to 'Other'; most tests do not override
Chris@0:    *   this default.
Chris@0:    *
Chris@0:    * @return bool
Chris@0:    *   TRUE on pass, FALSE on fail.
Chris@0:    */
Chris@0:   protected function assertMailPattern($field_name, $regex, $message = '', $group = 'Other') {
Chris@0:     $mails = $this->getMails();
Chris@0:     $mail = end($mails);
Chris@0:     $regex_found = preg_match("/$regex/", $mail[$field_name]);
Chris@0:     if (!$message) {
Chris@0:       $message = format_string('Expected text found in @field of email message: "@expected".', ['@field' => $field_name, '@expected' => $regex]);
Chris@0:     }
Chris@0:     return $this->assertTrue($regex_found, $message, $group);
Chris@0:   }
Chris@0: 
Chris@0:   /**
Chris@0:    * Outputs to verbose the most recent $count emails sent.
Chris@0:    *
Chris@0:    * @param int $count
Chris@0:    *   Optional number of emails to output.
Chris@0:    */
Chris@0:   protected function verboseEmail($count = 1) {
Chris@0:     $mails = $this->getMails();
Chris@0:     for ($i = count($mails) - 1; $i >= count($mails) - $count && $i >= 0; $i--) {
Chris@0:       $mail = $mails[$i];
Chris@0:       $this->verbose('Email:<pre>' . print_r($mail, TRUE) . '</pre>');
Chris@0:     }
Chris@0:   }
Chris@0: 
Chris@0: }