Laravel Mailable Test Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require spatie/laravel-mailable-test --dev
   

   Add the service provider to config/app.php under providers (if not auto-discovered):

   Spatie\MailableTest\MailableTestServiceProvider::class,
   

2. First Use Case: Test a OrderConfirmation mailer with a recipient:

   php artisan mail:send-test "OrderConfirmation" recipient@example.com
   

   • The command automatically resolves constructor arguments (e.g., Order model) if passed as CLI arguments:

     php artisan mail:send-test "OrderConfirmation" recipient@example.com 1
     

3. Where to Look First:

   • Command Syntax: Run php artisan mail:send-test --help for usage details.
   • Configuration: Check config/mailable-test.php (if published) for customizations like default mailers or queues.
   • Examples: Review the GitHub README for advanced use cases (e.g., testing queueable mailers).

Implementation Patterns

Usage Patterns

1. Basic Testing: Send a mailer with default arguments:

   php artisan mail:send-test "InvoiceMailable" user@example.com
   

2. Constructor Arguments: Pass arguments directly to the mailer’s constructor:

   php artisan mail:send-test "ResetPasswordMailable" user@example.com 123
   

   • Map CLI arguments to constructor parameters via config/mailable-test.php:

     'argument_mappings' => [
         'ResetPasswordMailable' => [
             'user_id' => 0, // 0-based index for CLI args
         ],
     ],
     

3. Queueable Mailers: Test queueable mailers by dispatching them directly:

   php artisan mail:send-test "DelayedNewsletterMailable" user@example.com --queue
   

   • Uses Laravel’s queue system (configure MAIL_MAILER in .env for testing).

4. Custom Mailers: Extend the command for custom logic (e.g., mocking services):

   // app/Console/Commands/CustomMailTest.php
   use Spatie\MailableTest\MailTestCommand;
   
   class CustomMailTest extends MailTestCommand {
       protected $signature = 'mail:custom-test {mailable} {recipient} {--queue}';
       protected $description = 'Custom mail test command';
   
       public function handle() {
           $this->sendTestMail($this->argument('mailable'), $this->argument('recipient'), $this->option('queue'));
       }
   }
   

5. Integration with Tests: Use in PHPUnit tests to verify mail content:

   use Spatie\MailableTest\MailTest;
   
   public function test_invoice_mail() {
       MailTest::sendTestMail('InvoiceMailable', 'user@example.com', 1);
       $this->assertCount(1, Mail::to('user@example.com')->hasBeenSent());
   }
   

Workflows

• Debugging Emails: Use --preview to render the email without sending:

  php artisan mail:send-test "WelcomeMailable" user@example.com --preview
  

  • Outputs HTML/Plaintext to CLI or saves to a file (configure in config/mailable-test.php).

• Batch Testing: Loop through recipients in a script:

  for email in $(cat emails.txt); do
      php artisan mail:send-test "NewsletterMailable" "$email"
  done
  

• CI/CD Pipelines: Add to deployment scripts to validate emails before release:

  # .github/workflows/test.yml
  - name: Test Mailables
    run: php artisan mail:send-test "CriticalAlertMailable" ci@example.com
  

Gotchas and Tips

Pitfalls

1. Argument Mismatch:

   • Issue: CLI arguments don’t match the mailer’s constructor.
   • Fix: Use argument_mappings in config or ensure argument order matches:

     // For: public function __construct(User $user, string $token)
     php artisan mail:send-test "ResetPasswordMailable" user@example.com 1 abc123
     

2. Queue Configuration:

   • Issue: Queueable mailers fail silently if MAIL_MAILER is not set to a queue driver (e.g., queue:async).
   • Fix: Set .env for testing:

     MAIL_MAILER=queue
     QUEUE_CONNECTION=sync
     

3. Preview Mode Quirks:

   • Issue: --preview may not render assets (CSS/JS) if not configured for local development.
   • Fix: Use Laravel Mix/Vite’s dev server or mock assets in tests.

4. Namespace Conflicts:

   • Issue: Multiple mailers with similar names (e.g., App\Mailers\OrderConfirmation vs. App\Mail\OrderConfirmation).
   • Fix: Use fully qualified names:

     php artisan mail:send-test "App\Mailers\OrderConfirmation" user@example.com
     

5. Environment-Specific Behavior:

   • Issue: Mailers behave differently in testing vs. local environments (e.g., assets, queues).
   • Fix: Use .env.testing or override config per environment.

Debugging

1. Log Output: Enable verbose logging for the command:

   php artisan mail:send-test "Mailable" user@example.com --verbose
   

2. Mail Facade Inspection: Use Laravel’s Mail::pretend() in tests to inspect sent mail:

   Mail::pretend();
   MailTest::sendTestMail('Mailable', 'user@example.com');
   $mail = Mail::assertSentTo('user@example.com')->first();
   

3. Swift Mailer Debugging: For Swift Mailer errors, check Laravel logs or enable Swift’s debug mode:

   // config/mail.php
   'debug' => env('MAIL_DEBUG', false),
   

Tips

1. Custom Recipients: Use environment variables for dynamic recipients:

   php artisan mail:send-test "Mailable" "${TEST_EMAIL}" --queue
   

   TEST_EMAIL=test@example.com
   

2. Template Testing: Test Blade templates by passing dynamic data:

   php artisan mail:send-test "TemplateMailable" user@example.com --data='{"key":"value"}'
   

3. Performance: Disable queues for local testing to avoid delays:

   php artisan mail:send-test "Mailable" user@example.com --queue=sync
   

4. Extension Points:

   • Custom Senders: Override Spatie\MailableTest\MailTestCommand to add pre/post-send logic.
   • Mocking: Use Laravel’s Mail::fake() to assert mail content in tests without sending:

     Mail::fake();
     MailTest::sendTestMail('Mailable', 'user@example.com');
     Mail::assertSent(Mailable::class);
     

5. Configuration: Publish the config for customization:

   php artisan vendor:publish --provider="Spatie\MailableTest\MailableTestServiceProvider" --tag="config"
   

   • Example: Set a default mailer or queue:

     'default_mailer' => 'ses',
     'default_queue' => 'mail',