feat: allow mails to be intercepted using events

Author: SamMousa

src/Codeception/Lib/Connector/Yii2.php

@@ -18,6 +18,9 @@
 use yii\base\ExitException;
 use yii\base\Security;
 use yii\base\UserException;
+use yii\mail\BaseMailer;
+use yii\mail\MailerInterface;
+use yii\mail\MailEvent;
 use yii\mail\MessageInterface;
 use yii\web\Application;
 use yii\web\ErrorHandler;
@@ -30,6 +33,19 @@ class Yii2 extends Client
 {
     use Shared\PhpSuperGlobalsConverter;
 
+    const MAIL_METHODS = [
+        self::MAIL_CATCH,
+        self::MAIL_EVENT_AFTER,
+        self::MAIL_EVENT_BEFORE,
+        self::MAIL_IGNORE
+    ];
+
+    public const MAIL_CATCH = 'catch';
+    public const MAIL_EVENT_AFTER = 'after';
+    public const MAIL_EVENT_BEFORE = 'before';
+    public const MAIL_IGNORE = 'ignore';
+
+
     const CLEAN_METHODS = [
         self::CLEAN_RECREATE,
         self::CLEAN_CLEAR,
@@ -64,6 +80,10 @@ class Yii2 extends Client
      */
     public $configFile;
 
+    /**
+     * @var self::MAIL_CATCH|self::MAIL_IGNORE|self::MAIL_AFTER|self::MAIL_BEFORE $mailMethod method for handling mails
+     */
+    public $mailMethod;
     /**
      * @var string method for cleaning the response object before each request
      */
@@ -267,7 +287,15 @@ public function startApp(?\yii\log\Logger $logger = null): void
             unset($config['container']);
         }
 
-        $config = $this->mockMailer($config);
+        match ($this->mailMethod) {
+            self::MAIL_CATCH => $config= $this->mockMailer($config),
+            self::MAIL_EVENT_AFTER => $config['components']['mailer']['on ' . BaseMailer::EVENT_AFTER_SEND] = fn(MailEvent $event) => $this->emails[]  = $event->message,
+            self::MAIL_EVENT_BEFORE => $config['components']['mailer']['on ' . BaseMailer::EVENT_BEFORE_SEND] = function(MailEvent $event) {
+                $this->emails[]  = $event->message;
+                return true;
+            },
+            self::MAIL_IGNORE => null// Do nothing
+        }
         Yii::$app = Yii::createObject($config);
 
         if ($logger instanceof \yii\log\Logger) {

src/Codeception/Lib/Connector/Yii2/TestMailer.php

@@ -6,10 +6,11 @@
 
 use Closure;
 use yii\mail\BaseMailer;
+use yii\symfonymailer\Message;
 
 class TestMailer extends BaseMailer
 {
-    public $messageClass = \yii\symfonymailer\Message::class;
+    public $messageClass = Message::class;
 
     public Closure $callback;
 

src/Codeception/Module/Yii2.php

@@ -86,6 +86,11 @@
  *   changes will get discarded.
  * * `recreateApplication` - (default: `false`) whether to recreate the whole
  *   application before each request
+ * * `mailMethod` - (default: `catch`) Method for handling email via the 'mailer'
+ *   component. `ignore` will not do anything with mail, this means mails are not
+ *   inspectable by the test runner, using `before` or `after` will use mailer
+ *   events; making the mails inspectable but also allowing your default mail
+ *   handling to work
  *
  * You can use this module by setting params in your `functional.suite.yml`:
  *
@@ -187,6 +192,7 @@ class Yii2 extends Framework implements ActiveRecord, MultiSession, PartedModule
         'requestCleanMethod' => Yii2Connector::CLEAN_RECREATE,
         'recreateComponents' => [],
         'recreateApplication' => false,
+        'mailMethod' => Yii2Connector::MAIL_CATCH,
         'closeSessionOnRecreateApplication' => true,
         'applicationClass' => null,
     ];
@@ -289,6 +295,12 @@ protected function validateConfig(): void
                 "The response clean method must be one of: " . $validMethods
             );
         }
+        if (!in_array($this->config['mailMethod'], Yii2Connector::MAIL_METHODS, true)) {
+            throw new ModuleConfigException(
+                self::class,
+                "The mail method must be one of: " . $validMethods
+            );
+        }
         if (!in_array($this->config['requestCleanMethod'], Yii2Connector::CLEAN_METHODS, true)) {
             throw new ModuleConfigException(
                 self::class,