## Summary
- Replace MailSlurp email testing service with testmail.app for E2E
magic link authentication tests
- Simpler API with namespace-based email addresses
(`{namespace}.{tag}@inbox.testmail.app`)
- No new dependencies - uses native `fetch` instead of mailslurp-client
## Changes
- **`frontend/e2e/helpers/email-testing.ts`** - Complete rewrite using
testmail.app JSON API
- Uses `livequery=true` to wait for emails (no polling needed)
- Generates unique tags per test run to avoid collisions
- Same `EmailHelper` interface maintained for minimal test changes
- **`frontend/e2e/production/full-user-journey.spec.ts`** - Update env
var references and messages
- **`frontend/playwright.record.config.ts`** - Update env var comment
- **`frontend/package.json`** - Remove `mailslurp-client` dependency,
bump version to 0.79.0
- **`frontend/.env.local.example`** - New file documenting required env
vars for local testing
- **`docs/DEVELOPMENT.md`** - Add testmail.app env vars to frontend
section
## Environment Variables
| Old | New |
|-----|-----|
| `MAILSLURP_API_KEY` | `TESTMAIL_API_KEY` |
| (none) | `TESTMAIL_NAMESPACE` |
**Note:** GitHub Actions org secrets already configured with new env
vars.
## Testing
- [x] Backend tests pass (`make test` - 57 tests)
- [x] Frontend unit tests pass (139 tests)
- [x] Frontend E2E tests pass (64 tests)
- [x] TypeScript compilation clean for changed files
## Review
- [x] Local CodeRabbit CLI review completed
- [x] Review feedback addressed (removed exposed credentials from plan
file)
@coderabbitai ignore
---
🤖 Generated with [Claude Code](https://claude.com/claude-code)
---------
Co-authored-by: Claude <noreply@anthropic.com>
4.1 KiB
Plan: Migrate from MailSlurp to testmail.app
Created: 2026-01-02 Branch: feat/sess-20260102-2109-migrate-mailslurp-testmail Status: Complete
Overview
Replace MailSlurp email testing service with testmail.app for E2E testing of magic link authentication. testmail.app uses a simpler API with namespace-based email addresses that require no inbox creation/deletion - emails just arrive at {namespace}.{tag}@inbox.testmail.app.
Requirements
- Remove all code referencing MailSlurp
- Remove
mailslurp-clientnpm dependency - Implement testmail.app API integration
- Update environment variable names (
TESTMAIL_API_KEY,TESTMAIL_NAMESPACE) - Maintain same
EmailHelperinterface for minimal test changes - Update archive docs to note migration (optional - historical accuracy)
Technical Approach
API Differences
| Feature | MailSlurp | testmail.app |
|---|---|---|
| Email format | Random xxx@mailslurp.com |
{namespace}.{tag}@inbox.testmail.app |
| Inbox creation | Required (createInbox()) |
Not needed - use any tag |
| Inbox deletion | Required (deleteInbox()) |
Not needed |
| Get emails | waitForLatestEmail(inboxId) |
GET /api/json?apikey=X&namespace=Y&tag=Z&livequery=true |
| Auth | API key in constructor | API key as query param |
| Email body | email.body |
email.html or email.text |
Implementation Strategy
- Keep same
EmailHelperinterface -createInbox(),waitForEmail(),extractMagicLink(),deleteInbox() - Use testmail.app's live query feature -
livequery=truewaits for email to arrive (up to timeout) - Generate unique tags - Use timestamp + random suffix for each test run to avoid collisions
- Inbox becomes a simple object -
{ id: tag, emailAddress: '{namespace}.{tag}@inbox.testmail.app' } - Delete becomes no-op - testmail.app emails auto-expire, no cleanup needed
Environment Variables
| Old | New |
|---|---|
MAILSLURP_API_KEY |
TESTMAIL_API_KEY |
| (none) | TESTMAIL_NAMESPACE |
Values: Set via environment variables (see frontend/.env.local.example)
Implementation Steps
-
Update
email-testing.ts- Replace MailSlurp implementation with testmail.app- Remove
mailslurp-clientimport - Add testmail.app API fetch implementation
- Use native
fetch(no new dependencies) - Generate unique tag for each "inbox"
- Implement
livequery=truefor waiting - Adapt email body extraction (
html/textinstead ofbody)
- Remove
-
Update
full-user-journey.spec.ts- Change references- Update doc comments (env var name)
- Update error messages
- Update console logs
-
Update
playwright.record.config.ts- Change env var comment -
Update
package.json- Removemailslurp-clientdependency -
Run
npm install- Update package-lock.json -
Create
.env.local.example- Document required env vars for local testing -
Update archive docs - Skipped intentionally; historical docs preserved for accuracy
Files to Create/Modify
| File | Action | Description |
|---|---|---|
frontend/e2e/helpers/email-testing.ts |
Modify | Replace MailSlurp with testmail.app |
frontend/e2e/production/full-user-journey.spec.ts |
Modify | Update env var refs and messages |
frontend/playwright.record.config.ts |
Modify | Update env var comment |
frontend/package.json |
Modify | Remove mailslurp-client |
frontend/package-lock.json |
Modify | Auto-updated by npm install |
frontend/.env.local.example |
Create | Document env vars for local testing |
Testing Strategy
- Manual testing: Run production E2E test with testmail.app credentials
cd frontend TESTMAIL_API_KEY=your-api-key \ TESTMAIL_NAMESPACE=your-namespace \ npm run test:e2e:prod:headed - Verify: Email received, magic link extracted, auth flow completes
- CI testing: Env vars already configured in GitHub Actions org secrets
Open Questions
None - requirements are clear.
Rollback Plan
- Revert the commit
- Run
npm installto restore mailslurp-client - Re-add MAILSLURP_API_KEY to secrets if removed