GSOC-E2E-3: Add Mailpit-based email verification for signup e2e test

.env.e2e

@@ -22,3 +22,13 @@ PREVIEW_URL=http://localhost:9002
 E2E_TEST_USERNAME_PREFIX=e2e
 E2E_TEST_EMAIL_SUFFIX=@example.com
 E2E_TEST_PASSWORD=e2e-Test-Password-1
+
+# --- EMAIL SETUP: ----
+EMAIL_SENDER=from_e2e_test_run@example.com
+
+# Send emails over SMTP to a local mail catcher (Mailpit) instead of Mailgun.
+# Defaults match Mailpit's own (SMTP :1025, HTTP UI/API :8025).
+# If you change these, also update the service port mappings in .github/workflows/e2e.yml.
+EMAIL_TRANSPORT=smtp
+MAILPIT_SMTP_PORT=1025
+MAILPIT_UI_PORT=8025

.github/workflows/e2e.yml

@@ -3,15 +3,53 @@ on:
   workflow_dispatch:
   pull_request:
     branches: [develop]
+  issue_comment:
+    types: [created]
 jobs:
   test-e2e:
-    environment: e2e-tests
+    # temporary while new e2e environment is not yet created:
+    # only trigger on workflow_dispatch, maintainer comment, or if PR is from GSOC project mentor or mentee
+    if: >
+      github.event_name == 'workflow_dispatch' ||
+      (
+        github.event_name == 'pull_request' &&
+        contains(fromJSON('["Geethegreat", "clairep94"]'), github.event.pull_request.user.login)
+      ) ||
+      (
+        github.event.issue.pull_request &&
+        github.event.comment.body == '/e2e' &&
+        contains(fromJSON('["OWNER", "MEMBER", "COLLABORATOR"]'), github.event.comment.author_association)
+      )
     timeout-minutes: 60
     runs-on: ubuntu-latest
 
+    services:
+      # Local mail catcher: the app sends verification emails here over SMTP (port 1025)
+      # and the e2e tests read them back via Mailpit's REST API (port 8025)
+      mailpit:
+        image: axllent/mailpit:latest
+        ports:
+          - 1025:1025
+          - 8025:8025
+
     steps:
+    - name: Resolve PR head ref
+      if: github.event_name == 'issue_comment'
+      id: pr
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: pr } = await github.rest.pulls.get({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            pull_number: context.issue.number
+          });
+          core.setOutput('sha', pr.head.sha);
+
     - name: Checkout code
       uses: actions/checkout@v4
+      with:
+        ref: ${{ github.event_name == 'issue_comment' && steps.pr.outputs.sha || github.ref }}
 
     - name: Set up node
       uses: actions/setup-node@v4

e2e/helpers/env.ts

@@ -1,14 +1,21 @@
 /** Returns the env var's value, or throws if it is missing or empty —
  * so the constants below are `string`, not `string | undefined`. */
-function requireEnv(name: string): string {
+export function requireEnv(name: string): string {
   const value = process.env[name];
   if (!value) {
     throw new Error(`Missing ${name} in .env.e2e. Make sure it is set.`);
   }
   return value;
 }
 
-/** Test-user constants from .env.e2e (loaded by playwright.config.ts). */
-export const usernamePrefix = requireEnv('E2E_TEST_USERNAME_PREFIX');
-export const emailSuffix = requireEnv('E2E_TEST_EMAIL_SUFFIX');
-export const password = requireEnv('E2E_TEST_PASSWORD');
+/**
+ * Test-user constants from .env.e2e (loaded by playwright.config.ts).
+ * Lazy (functions, not eager consts): playwright.config.ts also imports
+ * requireEnv from this file (via mailpit.ts, for the Mailpit webServer
+ * command), and CommonJS runs a module's whole body on import regardless of
+ * which export is used — eager consts here would call requireEnv before
+ * loadEnv() has loaded .env.e2e.
+ */
+export const usernamePrefix = () => requireEnv('E2E_TEST_USERNAME_PREFIX');
+export const emailSuffix = () => requireEnv('E2E_TEST_EMAIL_SUFFIX');
+export const password = () => requireEnv('E2E_TEST_PASSWORD');

e2e/helpers/mailpit.ts

@@ -0,0 +1,46 @@
+import { expect } from '../fixtures';
+import { requireEnv } from './env';
+
+/**
+ * Mailpit addresses derived from the MAILPIT_*_PORT vars in .env.e2e. Emails
+ * are captured here instead of Mailgun (EMAIL_TRANSPORT=smtp in .env.e2e,
+ * on MAILPIT_SMTP_PORT — see server/utils/mail.ts).
+ */
+export const mailpitSmtpPort = () => requireEnv('MAILPIT_SMTP_PORT');
+export const mailpitUiPort = () => requireEnv('MAILPIT_UI_PORT');
+export const mailpitApiUrl = () => `http://localhost:${mailpitUiPort()}/api/v1`;
+
+/**
+ * Polls Mailpit until a verification email arrives for `email` (delivery is
+ * async), then returns the `/verify?t=<token>` link from its HTML body.
+ */
+export async function getVerificationLink(email: string): Promise<string> {
+  let messageId: string | undefined;
+  await expect
+    .poll(
+      async () => {
+        const res = await fetch(
+          `${mailpitApiUrl()}/search?query=${encodeURIComponent(`to:${email}`)}`
+        );
+        const data = await res.json();
+        messageId = data.messages?.[0]?.ID;
+        return messageId;
+      },
+      {
+        message: `Expected a verification email to ${email} to arrive in Mailpit`,
+        timeout: 15_000
+      }
+    )
+    .toBeTruthy();
+
+  const res = await fetch(`${mailpitApiUrl()}/message/${messageId}`);
+  const message = await res.json();
+  const match = (message.HTML as string).match(
+    /href="(http[^"]*\/verify\?t=[^"]+)"/
+  );
+  expect(
+    match,
+    'Expected the email to contain a /verify?t=<token> link'
+  ).toBeTruthy();
+  return match![1];
+}

e2e/specs/signup.spec.ts

@@ -1,23 +1,24 @@
 import { test, expect } from '../fixtures';
 import { dismissCookieBanner } from '../helpers/cookie-banner';
 import { usernamePrefix, emailSuffix, password } from '../helpers/env';
+import { getVerificationLink } from '../helpers/mailpit';
 
 test.describe('signup and email verification', () => {
   test('can sign up and verify email via the emailed link', async ({
     page
   }) => {
     // Unique per run so the duplicate username/email check passes
-    const uniqueId = `${usernamePrefix}${Date.now()}`;
-    const email = `${uniqueId}${emailSuffix}`;
+    const uniqueId = `${usernamePrefix()}${Date.now()}`;
+    const email = `${uniqueId}${emailSuffix()}`;
 
     await page.goto('/signup');
 
     await dismissCookieBanner(page);
 
     await page.locator('#username').fill(uniqueId);
     await page.locator('#email').fill(email);
-    await page.locator('#password').fill(password);
-    await page.locator('#confirmPassword').fill(password);
+    await page.locator('#password').fill(password());
+    await page.locator('#confirmPassword').fill(password());
 
     // The submit button stays disabled until the async duplicate
     // username/email check resolves; click() auto-waits for enabled
@@ -27,6 +28,18 @@ test.describe('signup and email verification', () => {
     await expect(page.locator('.editor-holder')).toBeVisible({
       timeout: 15_000
     });
-    // TODO: on next PR, email verification
+
+    // "Receive" the verification email and click its link
+    const verificationLink = await getVerificationLink(email);
+    await page.goto(verificationLink);
+
+    // On success the verify page flashes a message for ~1s and then redirects
+    // home, so asserting on the message races the redirect. The redirect only
+    // happens for a valid token (invalid tokens stay on /verify showing an
+    // error), so assert the redirect, then the durable outcome via the API.
+    await expect(page).toHaveURL('/', { timeout: 15_000 });
+
+    const session = await page.request.get('/editor/session');
+    expect((await session.json()).verified).toBe('verified');
   });
 });

playwright.config.ts

@@ -1,12 +1,18 @@
 import { defineConfig, devices } from '@playwright/test';
 import { warnToStartE2eAppServerSeparately } from './e2e/setup/warn-to-start-e2e-server-separately';
+import { requireEnv } from './e2e/helpers/env';
+import {
+  mailpitApiUrl,
+  mailpitSmtpPort,
+  mailpitUiPort
+} from './e2e/helpers/mailpit';
 
 // DO NOT REMOVE: makes sure that playwright is always run with the e2e env overrides. See loadEnv.js
 process.env.APP_ENV = 'e2e';
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 require('./loadEnv')();
 
-const EDITOR_URL = process.env.EDITOR_URL || 'http://localhost:9000';
+const EDITOR_URL = requireEnv('EDITOR_URL');
 
 warnToStartE2eAppServerSeparately();
 /**
@@ -49,6 +55,21 @@ export default defineConfig({
       stderr: 'pipe',
       /** First start compiles webpack from scratch, hence the long timeout. */
       timeout: 180_000
+    },
+    {
+      /**
+       * Local mail catcher for signup/verification emails. Requires the
+       * binary locally (e.g. `winget install axllent.mailpit` / `brew
+       * install mailpit`); on CI an already-running service container is
+       * reused instead (see e2e.yml).
+       */
+      name: 'Mailpit',
+      command: `mailpit --smtp localhost:${mailpitSmtpPort()} --listen localhost:${mailpitUiPort()}`,
+      url: `${mailpitApiUrl()}/info`,
+      reuseExistingServer: true,
+      stdout: 'pipe',
+      stderr: 'pipe',
+      timeout: 15_000
     }
   ],
 

server/utils/mail.ts

@@ -2,14 +2,40 @@ import nodemailer from 'nodemailer';
 import mg from 'nodemailer-mailgun-transport';
 import { RenderedMailerData } from '../types/email';
 
-if (!process.env.MAILGUN_KEY) {
-  throw new Error('Mailgun key missing');
-}
+// When EMAIL_TRANSPORT=smtp, emails are sent over plain SMTP (e.g. to a local
+// mail catcher like Mailpit during e2e tests) instead of Mailgun.
+const useSmtpTransport = process.env.EMAIL_TRANSPORT === 'smtp';
+
+function createTransport(): nodemailer.Transporter {
+  if (useSmtpTransport) {
+    const { MAILPIT_SMTP_PORT } = process.env;
+    if (!MAILPIT_SMTP_PORT) {
+      throw new Error('MAILPIT_SMTP_PORT missing from .env.e2e');
+    }
+    if (Number.isNaN(Number(MAILPIT_SMTP_PORT))) {
+      throw new Error(
+        'MAILPIT_SMTP_PORT is not a valid number. Check .env.e2e'
+      );
+    }
+
+    return nodemailer.createTransport({
+      host: 'localhost',
+      port: Number(MAILPIT_SMTP_PORT),
+      secure: false
+    });
+  }
+
+  if (!process.env.MAILGUN_KEY) {
+    throw new Error('Mailgun key missing');
+  }
 
-const auth = {
-  api_key: process.env.MAILGUN_KEY,
-  domain: process.env.MAILGUN_DOMAIN
-};
+  const auth = {
+    api_key: process.env.MAILGUN_KEY,
+    domain: process.env.MAILGUN_DOMAIN
+  };
+
+  return nodemailer.createTransport(mg({ auth }));
+}
 
 /** Mail service class wrapping around mailgun */
 class Mail {
@@ -18,7 +44,7 @@ class Mail {
   sendOptions: Pick<nodemailer.SendMailOptions, 'from'>;
 
   constructor() {
-    this.client = nodemailer.createTransport(mg({ auth }));
+    this.client = createTransport();
     this.sendOptions = {
       from: process.env.EMAIL_SENDER
     };