Add command to test email configuration (#1618)

* Add command to test email config

* Add return statements

* Refactor and add tests

* Test mail content

* Add to docs, update changelog

CHANGELOG.md

@@ -9,6 +9,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Configurable hook script for recording synchronization ([#1484], [#1604])
+- Command to test email configuration ([#530], [#1618])
 - Configurable hook script for recording synchronization ([#1484], [#1604])
 
 ### Changed
@@ -209,6 +211,7 @@ You can find the changelog for older versions there [here](https://github.com/TH
 [#315]: https://github.com/THM-Health/PILOS/issues/315
 [#372]: https://github.com/THM-Health/PILOS/issues/372
 [#373]: https://github.com/THM-Health/PILOS/pull/373
+[#530]: https://github.com/THM-Health/PILOS/issues/530
 [#532]: https://github.com/THM-Health/PILOS/issues/532
 [#574]: https://github.com/THM-Health/PILOS/pull/574
 [#617]: https://github.com/THM-Health/PILOS/pull/617
@@ -284,6 +287,7 @@ You can find the changelog for older versions there [here](https://github.com/TH
 [#1604]: https://github.com/THM-Health/PILOS/pull/1604
 [#1607]: https://github.com/THM-Health/PILOS/issues/1607
 [#1608]: https://github.com/THM-Health/PILOS/pull/1608
+[#1618]: https://github.com/THM-Health/PILOS/pull/1618
 [unreleased]: https://github.com/THM-Health/PILOS/compare/v4.1.2...develop
 [v3.0.0]: https://github.com/THM-Health/PILOS/releases/tag/v3.0.0
 [v3.0.1]: https://github.com/THM-Health/PILOS/releases/tag/v3.0.1

app/Console/Commands/TestEmailConfig.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Notifications\TestEmail;
+use Illuminate\Console\Command;
+use Notification;
+
+use function Laravel\Prompts\text;
+
+class TestEmailConfig extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'mail:test';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Send a test email to validate config';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle()
+    {
+        // Ask for the email address to send the test email
+        $email = text(label: 'Recipient email address', validate: ['email' => 'required|email']);
+
+        // Send the test email
+        try {
+            Notification::route('mail', [$email])->notifyNow(new TestEmail);
+
+            $this->info('Test email sent successfully');
+
+            return self::SUCCESS;
+        } catch (\Exception $e) {
+            $this->error('Failed to send test email: '.$e->getMessage());
+
+            return self::FAILURE;
+        }
+    }
+}

app/Notifications/TestEmail.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Notifications;
+
+use Illuminate\Notifications\Messages\MailMessage;
+use Illuminate\Notifications\Notification;
+
+class TestEmail extends Notification
+{
+    /**
+     * Create a new notification instance.
+     */
+    public function __construct()
+    {
+        //
+    }
+
+    /**
+     * Get the notification's delivery channels.
+     *
+     * @return array<int, string>
+     */
+    public function via(object $notifiable): array
+    {
+        return ['mail'];
+    }
+
+    /**
+     * Get the mail representation of the notification.
+     */
+    public function toMail(object $notifiable): MailMessage
+    {
+        return (new MailMessage)
+            ->line('This is a test email to check the email configuration.');
+    }
+}

docs/docs/administration/03-configuration.md

@@ -89,6 +89,16 @@ It is a mail testing tool that captures emails sent by the application.
 
 You need to configure a real mail server for production use.
 
+:::tip
+
+To check your email configuration, you can send a test mail using the following command:
+
+```bash
+docker compose exec app pilos-cli mail:test
+```
+
+:::
+
 ## Authentication
 
 | Option               | Default Value | Description                  |

resources/views/vendor/notifications/email.blade.php

@@ -7,7 +7,9 @@
 @endcomponent
 @endslot
 
+@isset($name)
 # @lang('mail.greeting', ['name' => $name])
+@endisset
 
 {{-- Intro Lines --}}
 @foreach ($introLines as $line)

tests/Backend/Unit/Console/TestEmailConfigTest.php

@@ -0,0 +1,70 @@
+<?php
+
+namespace Tests\Backend\Unit\Console;
+
+use App\Notifications\TestEmail;
+use Illuminate\Support\Facades\Notification;
+use Tests\Backend\TestCase;
+
+class TestEmailConfigTest extends TestCase
+{
+    /**
+     * Test the command sends an email successfully.
+     *
+     * @return void
+     */
+    public function test_handle_success()
+    {
+        Notification::fake();
+
+        $this->artisan('mail:test')
+            ->expectsQuestion('Recipient email address', '[email protected]')
+            ->expectsOutput('Test email sent successfully')
+            ->assertSuccessful();
+
+        Notification::assertSentOnDemand(
+            TestEmail::class,
+            function (TestEmail $notification, array $channels, object $notifiable) {
+                // Check the email content
+                $mail = $notification->toMail($notifiable)->toArray();
+                $this->assertEquals('This is a test email to check the email configuration.', $mail['introLines'][0]);
+
+                // Check the email recipient
+                $this->assertEquals(['[email protected]'], $notifiable->routes['mail']);
+
+                return true;
+            }
+        );
+    }
+
+    /**
+     * Test the command validates the email address.
+     */
+    public function test_handle_validation()
+    {
+        Notification::fake();
+
+        $this->artisan('mail:test')
+            ->expectsQuestion('Recipient email address', 'invalid-email')
+            ->assertFailed();
+    }
+
+    /**
+     * Test the command fails to send an email.
+     *
+     * @return void
+     */
+    public function test_handle_failure()
+    {
+        Notification::fake();
+
+        // Simulate an exception when sending the email
+        Notification::shouldReceive('sendNow')
+            ->andThrow(new \Exception('SMTP server not found'));
+
+        $this->artisan('mail:test')
+            ->expectsQuestion('Recipient email address', '[email protected]')
+            ->expectsOutput('Failed to send test email: SMTP server not found')
+            ->assertFailed();
+    }
+}