From bde2da45f7737c640f7acbc7b2ccadf5ad3a6917 Mon Sep 17 00:00:00 2001
From: William Allen <william.allen@kitware.com>
Date: Sun, 16 Aug 2026 16:17:28 -0400
Subject: [PATCH] Add `email:test` Artisan command

This PR adds a new `php artisan email:test --email=<email>` command which allows administrators to easily verify that email is configured correctly.

Closes https://github.com/Kitware/CDash/issues/3727.
---
 app/Console/Commands/EmailTestCommand.php     | 53 +++++++++++++++++++
 app/Mail/TestEmail.php                        | 36 +++++++++++++
 app/cdash/tests/CMakeLists.txt                |  2 +
 .../email/email-configuration-test.blade.php  |  3 ++
 tests/Feature/EmailTestCommandTest.php        | 48 +++++++++++++++++
 5 files changed, 142 insertions(+)
 create mode 100644 app/Console/Commands/EmailTestCommand.php
 create mode 100644 app/Mail/TestEmail.php
 create mode 100644 resources/views/email/email-configuration-test.blade.php
 create mode 100644 tests/Feature/EmailTestCommandTest.php

diff --git a/app/Console/Commands/EmailTestCommand.php b/app/Console/Commands/EmailTestCommand.php
new file mode 100644
index 0000000000..2a24e2266d
--- /dev/null
+++ b/app/Console/Commands/EmailTestCommand.php
@@ -0,0 +1,53 @@
+<?php
+
+namespace App\Console\Commands;
+
+use App\Mail\TestEmail;
+use Illuminate\Console\Command;
+use Illuminate\Support\Facades\Mail;
+use Illuminate\Support\Facades\Validator;
+
+class EmailTestCommand extends Command
+{
+    /**
+     * The name and signature of the console command.
+     *
+     * @var string
+     */
+    protected $signature = 'email:test {--email=}';
+
+    /**
+     * The console command description.
+     *
+     * @var string
+     */
+    protected $description = 'Send a test email';
+
+    /**
+     * Execute the console command.
+     */
+    public function handle(): void
+    {
+        $email = $this->option('email');
+
+        $validator = Validator::make([
+            'email' => $email,
+        ], [
+            'email' => 'required|email',
+        ], [
+            'email.required' => 'You must specify the --email option',
+            'email.email' => "Invalid email address: $email",
+        ]);
+
+        if ($validator->fails()) {
+            foreach ($validator->errors()->all() as $error) {
+                $this->error($error);
+            }
+            return;
+        }
+
+        Mail::to($email)->send(new TestEmail());
+
+        $this->info("Test email sent to $email");
+    }
+}
diff --git a/app/Mail/TestEmail.php b/app/Mail/TestEmail.php
new file mode 100644
index 0000000000..4eddd74fcc
--- /dev/null
+++ b/app/Mail/TestEmail.php
@@ -0,0 +1,36 @@
+<?php
+
+namespace App\Mail;
+
+use Illuminate\Bus\Queueable;
+use Illuminate\Contracts\Queue\ShouldQueue;
+use Illuminate\Mail\Mailable;
+use Illuminate\Mail\Mailables\Content;
+use Illuminate\Mail\Mailables\Envelope;
+use Illuminate\Queue\SerializesModels;
+
+class TestEmail extends Mailable implements ShouldQueue
+{
+    use Queueable;
+    use SerializesModels;
+
+    /**
+     * Get the message envelope.
+     */
+    public function envelope(): Envelope
+    {
+        return new Envelope(
+            subject: 'CDash Test Email',
+        );
+    }
+
+    /**
+     * Get the message content definition.
+     */
+    public function content(): Content
+    {
+        return new Content(
+            text: 'email.email-configuration-test',
+        );
+    }
+}
diff --git a/app/cdash/tests/CMakeLists.txt b/app/cdash/tests/CMakeLists.txt
index 7e3307e952..a8c612ffea 100644
--- a/app/cdash/tests/CMakeLists.txt
+++ b/app/cdash/tests/CMakeLists.txt
@@ -258,6 +258,8 @@ add_feature_test_in_transaction(/Feature/Jobs/PruneAuthTokensTest)
 
 add_feature_test_in_transaction(/Feature/UserCommand)
 
+add_feature_test_in_transaction(/Feature/EmailTestCommandTest)
+
 add_feature_test_in_transaction(/Feature/Jobs/NotifyExpiringAuthTokensTest)
 
 add_feature_test_in_transaction(/Feature/Jobs/PruneUploadsTest)
diff --git a/resources/views/email/email-configuration-test.blade.php b/resources/views/email/email-configuration-test.blade.php
new file mode 100644
index 0000000000..1029d77068
--- /dev/null
+++ b/resources/views/email/email-configuration-test.blade.php
@@ -0,0 +1,3 @@
+This is a test email from CDash.
+
+CDash instance URL: {{ config('app.url') }}
diff --git a/tests/Feature/EmailTestCommandTest.php b/tests/Feature/EmailTestCommandTest.php
new file mode 100644
index 0000000000..266ca49bec
--- /dev/null
+++ b/tests/Feature/EmailTestCommandTest.php
@@ -0,0 +1,48 @@
+<?php
+
+namespace Tests\Feature;
+
+use App\Mail\TestEmail;
+use Illuminate\Foundation\Testing\DatabaseTransactions;
+use Illuminate\Support\Facades\Artisan;
+use Illuminate\Support\Facades\Mail;
+use Tests\TestCase;
+
+class EmailTestCommandTest extends TestCase
+{
+    use DatabaseTransactions;
+
+    public function testEmailTestCommand(): void
+    {
+        Mail::fake();
+
+        $email = 'test@example.com';
+
+        Artisan::call('email:test', ['--email' => $email]);
+
+        Mail::assertQueued(TestEmail::class, fn ($mail) => $mail->hasTo($email));
+
+        $output = trim(Artisan::output());
+        $this->assertStringContainsString("Test email sent to $email", $output);
+    }
+
+    public function testEmailTestCommandRequiresEmail(): void
+    {
+        Mail::fake();
+        Artisan::call('email:test');
+        $output = trim(Artisan::output());
+        $this->assertStringContainsString('You must specify the --email option', $output);
+        Mail::assertNothingSent();
+        Mail::assertNothingQueued();
+    }
+
+    public function testEmailTestCommandInvalidEmail(): void
+    {
+        Mail::fake();
+        Artisan::call('email:test', ['--email' => 'not-an-email']);
+        $output = trim(Artisan::output());
+        $this->assertStringContainsString('Invalid email address: not-an-email', $output);
+        Mail::assertNothingSent();
+        Mail::assertNothingQueued();
+    }
+}