Compare commits

...
Author SHA1 Message Date
Andrew BeveridgeandClaude Opus 4.5 c0e86a0302 docs: Add GCS path lessons and update E2E spec for testmail.app
- Add "GCS Blob Paths vs Full URIs" section to LESSONS-LEARNED.md
  documenting the path format confusion bug and double-slash gotcha
- Update E2E-HAPPY-PATH-TEST-SPEC.md secrets section to reflect
  testmail.app migration (was still referencing old names)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-03 17:53:03 -05:00
Andrew Beveridge ☄️andClaude Opus 4.5 925dd3c262 fix: Complete mailslurp to testmail.app migration (#168)
## Summary
- Complete the migration from MailSlurp to testmail.app for E2E testing
- Update all workflow files to use `TESTMAIL_API_KEY` and
`TESTMAIL_NAMESPACE` secrets
- Update documentation and test comments

## Changes
- `.github/workflows/e2e-happy-path.yml` - Use testmail.app secrets
- `.github/workflows/ci.yml` - Use testmail.app secrets  
- `docs/E2E-HAPPY-PATH-TEST-SPEC.md` - Update documentation
- `frontend/e2e/production/happy-path-real-user.spec.ts` - Update
comments

## Test plan
- [x] Verify no remaining mailslurp references in active files (archives
excluded)
- [ ] E2E Happy Path test should run (not skip) with testmail.app
secrets

🤖 Generated with [Claude Code](https://claude.com/claude-code)

@coderabbitai ignore

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-03 17:32:53 -05:00
7 changed files with 75 additions and 25 deletions

No files matched your search

+2 -1
View File
@@ -225,7 +225,8 @@ jobs:
- name: Run Happy Path Production Test
working-directory: frontend
env:
MAILSLURP_API_KEY: ${{ secrets.MAILSLURP_API_KEY }}
TESTMAIL_API_KEY: ${{ secrets.TESTMAIL_API_KEY }}
TESTMAIL_NAMESPACE: ${{ secrets.TESTMAIL_NAMESPACE }}
E2E_TEST_TOKEN: ${{ secrets.E2E_TEST_TOKEN }}
E2E_ADMIN_TOKEN: ${{ secrets.E2E_ADMIN_TOKEN }}
run: |
+3 -2
View File
@@ -70,8 +70,9 @@ jobs:
- name: Run E2E Happy Path Test
working-directory: frontend
env:
MAILSLURP_API_KEY: ${{ secrets.MAILSLURP_API_KEY }}
E2E_TEST_TOKEN: ${{ inputs.use_test_token == 'true' && secrets.E2E_TEST_TOKEN || '' }}
TESTMAIL_API_KEY: ${{ secrets.TESTMAIL_API_KEY }}
TESTMAIL_NAMESPACE: ${{ secrets.TESTMAIL_NAMESPACE }}
E2E_TEST_TOKEN: ${{ inputs.use_test_token && secrets.E2E_TEST_TOKEN || '' }}
E2E_ADMIN_TOKEN: ${{ secrets.E2E_ADMIN_TOKEN }}
DEBUG_MODE: ${{ inputs.debug_mode || 'false' }}
run: |
+11 -6
View File
@@ -14,18 +14,20 @@
## Test Requirements
### 1. New User Registration (MailSlurp)
### 1. New User Registration (testmail.app)
- [ ] Navigate to landing page (`gen.nomadkaraoke.com`)
- [ ] Click "Sign In" or "Get Started" button
- [ ] Create a NEW MailSlurp inbox (fresh email address for each test run)
- [ ] Generate a unique test email address (testmail.app namespace)
- [ ] Enter the test email in the beta enrollment form
- [ ] Submit the form
- [ ] Wait for welcome/magic-link email in MailSlurp inbox
- [ ] Wait for welcome/magic-link email via testmail.app API
- [ ] Extract the magic link from the email
- [ ] Click/navigate to the magic link to authenticate
- [ ] Verify user is logged in and has credits
**Note**: When `use_test_token=true` workflow input is set, steps 1-9 above are skipped and the test uses a pre-authenticated token instead.
### 2. Create Karaoke Job (UI Only)
- [ ] Navigate to the karaoke creation page
@@ -118,8 +120,10 @@
### Environment Variables
```bash
MAILSLURP_API_KEY=xxx # Required - for email testing
# No pre-auth tokens - test handles full signup
TESTMAIL_NAMESPACE=xxx # Required - for email testing (testmail.app)
TESTMAIL_API_KEY=xxx # Required - for email testing (testmail.app)
E2E_TEST_TOKEN=xxx # Optional - skip signup, use existing account
# When use_test_token=true, skips email signup and uses pre-authenticated token
```
### Test Song
@@ -160,7 +164,8 @@ Log detailed progress at each step with timestamps for debugging.
### Secrets Required
- `MAILSLURP_API_KEY` - For email testing
- `TESTMAIL_API_KEY` - For email testing (testmail.app)
- `TESTMAIL_NAMESPACE` - testmail.app namespace for unique email addresses
### Workflow Steps
+43
View File
@@ -795,6 +795,49 @@ input_files = [f for f in input_files if "outputs" not in str(f)]
**Lesson**: When writing code that processes files downloaded from GCS, always use recursive glob patterns and verify the expected directory structure matches what's actually stored.
### GCS Blob Paths vs Full URIs
**Problem**: When uploading files to GCS and returning paths to other services, there's confusion between "blob paths" (just the path within a bucket) and "full GCS URIs" (gs://bucket/path).
**Symptoms**:
- 404 errors when downloading files that were just uploaded
- Paths look like: `bucket/gs://bucket/path/file.mp4` (doubled prefix)
- Storage service prepends bucket name to what's already a full URI
**Example of the bug**:
```python
# GCE worker uploads to gs://bucket/jobs/id/encoded/
# Then returns full URI in response: "gs://bucket/jobs/id/encoded/file.mp4"
# Backend tries: storage.download_file("gs://bucket/jobs/id/encoded/file.mp4")
# Storage service prepends bucket: "bucket/gs://bucket/jobs/id/encoded/file.mp4"
# Result: 404 - No such object
```
**Solution**: Return blob paths (path within bucket), not full GCS URIs:
```python
# output_gcs_path = "gs://bucket/jobs/id/encoded/"
gcs_path = output_gcs_path.replace("gs://", "")
parts = gcs_path.split("/", 1)
bucket = parts[0]
prefix = parts[1].rstrip("/") if len(parts) > 1 else ""
# Return blob paths like: "jobs/id/encoded/file.mp4"
blob_path = f"{prefix}/{filename}" if prefix else filename
```
**Related gotcha**: Double slashes in paths. When the prefix already ends with "/" and you concatenate with another "/":
```python
# BAD - creates "encoded//file.mp4"
prefix = "jobs/id/encoded/" # Has trailing slash
blob_name = f"{prefix}/{filename}" # Adds another slash
# GOOD - strip trailing slash first
prefix = parts[1].rstrip("/")
blob_name = f"{prefix}/{filename}" if prefix else filename
```
**Lesson**: When building systems that pass GCS paths between services, establish a clear contract: either always use full URIs (`gs://bucket/path`) or always use blob paths (`path/within/bucket`). Document which format each API expects.
### Library Caches Need GCS Sync in Cloud Run
**Problem**: Libraries like LyricsTranscriber cache API responses to local directories (e.g., `~/lyrics-transcriber-cache`). In Cloud Run, each container is ephemeral - the cache is lost on every restart or scale-up, causing redundant API calls.
+6 -6
View File
@@ -272,8 +272,8 @@ export function JobSubmission({ onJobCreated }: JobSubmissionProps) {
Skip lyrics review (non-interactive)
</Label>
<p className="text-xs mt-1" style={{ color: 'var(--text-muted)' }}>
<span className="text-amber-500 font-medium">Warning:</span> AI lyrics correction isn&apos;t perfect.
Skipping review will likely result in timing errors and incorrect words in your karaoke video.
<span className="text-amber-500 font-medium">Warning:</span> auto lyrics correction isn&apos;t perfect.
Skipping review will likely result in incorrect words in your karaoke video.
</p>
</div>
</div>
@@ -377,8 +377,8 @@ export function JobSubmission({ onJobCreated }: JobSubmissionProps) {
Skip lyrics review (non-interactive)
</Label>
<p className="text-xs mt-1" style={{ color: 'var(--text-muted)' }}>
<span className="text-amber-500 font-medium">Warning:</span> AI lyrics correction isn&apos;t perfect.
Skipping review will likely result in timing errors and incorrect words in your karaoke video.
<span className="text-amber-500 font-medium">Warning:</span> auto lyrics correction isn&apos;t perfect.
Skipping review will likely result in incorrect words in your karaoke video.
</p>
</div>
</div>
@@ -465,8 +465,8 @@ export function JobSubmission({ onJobCreated }: JobSubmissionProps) {
Skip lyrics review (non-interactive)
</Label>
<p className="text-xs mt-1" style={{ color: 'var(--text-muted)' }}>
<span className="text-amber-500 font-medium">Warning:</span> AI lyrics correction isn&apos;t perfect.
Skipping review will likely result in timing errors and incorrect words in your karaoke video.
<span className="text-amber-500 font-medium">Warning:</span> auto lyrics correction isn&apos;t perfect.
Skipping review will likely result in incorrect words in your karaoke video.
</p>
</div>
</div>
@@ -11,7 +11,7 @@ import { createEmailHelper, isEmailTestingAvailable } from '../helpers/email-tes
*
* Test Flow:
* 1. Landing Page - Navigate and verify
* 2. New User Signup - Create MailSlurp inbox, submit beta form, verify email
* 2. New User Signup - Create testmail.app inbox, submit beta form, verify email
* 3. Magic Link Auth - Click magic link to authenticate
* 4. Create Job - Search for test song via UI
* 5. Audio Selection - Select audio source via UI dialog
@@ -24,7 +24,7 @@ import { createEmailHelper, isEmailTestingAvailable } from '../helpers/email-tes
* 12. Cleanup - Delete distributed content and job
*
* Environment Variables:
* - MAILSLURP_API_KEY: Required for email testing (can be skipped with E2E_TEST_TOKEN)
* - TESTMAIL_API_KEY + TESTMAIL_NAMESPACE: Required for email testing (can be skipped with E2E_TEST_TOKEN)
* - E2E_TEST_TOKEN: Pre-configured user token to skip signup flow (for iterations)
* - E2E_ADMIN_TOKEN: Required for cleanup endpoint (optional - cleanup skipped if not set)
*/
@@ -138,12 +138,12 @@ test.describe('E2E Happy Path - Real User with Full UI Interactions', () => {
}) => {
test.setTimeout(TIMEOUTS.fullTest);
// Check if we have a pre-configured token (for iterations without using MailSlurp)
// Check if we have a pre-configured token (for iterations without using testmail.app)
const usePreConfiguredToken = hasPreConfiguredToken();
// Skip if neither pre-configured token nor MailSlurp is available
// Skip if neither pre-configured token nor testmail.app is available
if (!usePreConfiguredToken && !isEmailTestingAvailable()) {
test.skip(true, 'Neither E2E_TEST_TOKEN nor MAILSLURP_API_KEY set - cannot run test');
test.skip(true, 'Neither E2E_TEST_TOKEN nor TESTMAIL_API_KEY/TESTMAIL_NAMESPACE set - cannot run test');
return;
}
@@ -217,7 +217,7 @@ test.describe('E2E Happy Path - Real User with Full UI Interactions', () => {
console.log('STEP 3 COMPLETE: User authenticated with pre-configured token');
} else {
// ----- FULL PATH: Beta signup with MailSlurp -----
// ----- FULL PATH: Beta signup with testmail.app -----
console.log('\n========================================');
console.log('STEP 2: New User Beta Enrollment');
console.log('========================================');
+4 -4
View File
@@ -1268,12 +1268,12 @@ def upload_to_gcs(local_path: Path, gcs_uri: str):
# Upload a file or folder to GCS
parts = gcs_uri.replace("gs://", "").split("/", 1)
bucket_name = parts[0]
prefix = parts[1] if len(parts) > 1 else ""
prefix = parts[1].rstrip("/") if len(parts) > 1 else ""
bucket = storage_client.bucket(bucket_name)
if local_path.is_file():
blob_name = f"{prefix}/{local_path.name}".strip("/")
blob_name = f"{prefix}/{local_path.name}" if prefix else local_path.name
blob = bucket.blob(blob_name)
blob.upload_from_filename(str(local_path))
logger.info(f"Uploaded: {local_path} -> gs://{bucket_name}/{blob_name}")
@@ -1281,7 +1281,7 @@ def upload_to_gcs(local_path: Path, gcs_uri: str):
for file in local_path.rglob("*"):
if file.is_file():
rel_path = file.relative_to(local_path)
blob_name = f"{prefix}/{rel_path}".strip("/")
blob_name = f"{prefix}/{rel_path}" if prefix else str(rel_path)
blob = bucket.blob(blob_name)
blob.upload_from_filename(str(file))
logger.info(f"Uploaded: {file} -> gs://{bucket_name}/{blob_name}")
@@ -1439,7 +1439,7 @@ async def process_job(job_id: str, request: EncodeRequest):
# Convert local paths to blob paths (backend expects blob paths, not full gs:// URIs)
# output_gcs_path is like "gs://bucket/jobs/id/encoded/"
# We need paths like "jobs/id/encoded/output_4k.mp4"
# We need paths like "jobs/id/encoded/output_4k_lossless.mp4"
gcs_path = request.output_gcs_path.replace("gs://", "")
parts = gcs_path.split("/", 1)
prefix = parts[1].rstrip("/") if len(parts) > 1 else ""