aethex-forge/docs/PHASE3-TESTING-PLAN.md

Phase 3 Testing Plan

Pre-Testing Requirements

Before running tests, ensure:

1. Environment variables are set:

   VITE_FOUNDATION_URL=https://aethex.foundation  # or staging/localhost
   FOUNDATION_OAUTH_CLIENT_SECRET=<received-from-foundation>
   VITE_API_BASE=https://aethex.dev  # or http://localhost:5173
   

2. Foundation is operational:

   • aethex.foundation is running
   • OAuth endpoints are accessible
   • Test user accounts exist

3. App is running:

   npm run dev  # or equivalent for your setup
   

---

Test Scenarios

Test 1: Login Page Loads Correctly

Objective: Verify the login page displays Foundation OAuth button

Steps:

1. Navigate to http://localhost:5173/login (or prod URL)
2. Look for "Login with Foundation" button
3. Verify button is visible and clickable

Expected Result:

✓ Login page displays
✓ "Login with Foundation" button visible
✓ Other options (Roblox, Ethereum) still available
✓ Email/password form visible

Success Criteria: ✅ Button visible and no console errors

---

Test 2: Foundation Redirect

Objective: Verify clicking the button redirects to Foundation

Steps:

1. On login page, click "Login with Foundation" button
2. Observe browser URL change
3. Check redirect parameters

Expected Result:

Redirected to:
https://aethex.foundation/api/oauth/authorize
  ?client_id=aethex-corp
  &redirect_uri=https://aethex.dev/api/auth/foundation-callback
  &response_type=code
  &scope=openid%20profile%20email
  &state=...

Success Criteria: ✅ Redirected to Foundation OAuth authorize endpoint

---

Test 3: Foundation Authentication (Manual)

Objective: User authenticates on Foundation

Steps:

1. You're now on Foundation login page
2. Enter test credentials
3. If prompted, grant aethex.dev permissions
4. Click "Authorize" or similar

Expected Result:

✓ Foundation accepts credentials
✓ Permission screen appears (if configured)
✓ Successful authentication

Success Criteria: ✅ Authentication succeeds, no Foundation-side errors

---

Test 4: Callback Reception

Objective: Verify Foundation redirects back with authorization code

Steps:

1. After Foundation authentication completes
2. Observe browser URL change
3. Look for authorization code in URL

Expected Result:

Browser redirects to:
https://aethex.dev/api/auth/foundation-callback
  ?code=AUTH_CODE_VALUE
  &state=...

Check browser console:
✓ No errors about code
✓ Processing message may appear

Success Criteria: ✅ Callback endpoint receives authorization code

---

Test 5: Token Exchange

Objective: Backend exchanges code for access token

Steps:

1. Monitor network requests in browser Dev Tools
2. Look for POST to /api/auth/exchange-token
3. Check response status

Expected Result:

Network:
POST /api/auth/exchange-token
Status: 200 OK
Response: {
  "accessToken": "eyJ...",
  "user": {
    "id": "uuid",
    "email": "user@example.com",
    "username": "testuser",
    "profile_complete": false
  }
}

Cookies set:
✓ foundation_access_token=<token>
✓ auth_user_id=<uuid>

Success Criteria: ✅ Token received, cookies set, no 401/403 errors

---

Test 6: User Profile Sync

Objective: Verify user profile created/updated in local database

Steps:

1. After successful login, check database
2. Query user_profiles table
3. Verify user exists with correct data

Database Query:

-- Check user was created/updated
SELECT id, email, username, profile_completed, updated_at
FROM user_profiles
WHERE email = 'test@example.com'
ORDER BY updated_at DESC
LIMIT 1;

-- Expected result:
/*
| id           | email            | username  | profile_completed | updated_at          |
|--------------|------------------|-----------|-------------------|---------------------|
| <uuid>       | test@example.com | testuser  | false             | 2024-01-XX HH:MM:SS |
*/

Success Criteria: ✅ User profile exists in local database with correct data

---

Test 7: Dashboard Redirect

Objective: User redirected to dashboard after authentication

Steps:

1. After token exchange and profile sync
2. Browser should automatically redirect
3. Check final URL

Expected Result:

Browser URL: https://aethex.dev/dashboard
✓ Dashboard loads successfully
✓ User info displays correctly
✓ Profile data matches Foundation user

Success Criteria: ✅ Dashboard loads, user is authenticated

---

Test 8: Authenticated API Requests

Objective: User can make authenticated API calls

Steps:

1. On authenticated dashboard
2. Use browser console to test:

   const token = document.cookie
     .split(';')
     .find(c => c.trim().startsWith('foundation_access_token='))
     ?.split('=')[1];
   
   fetch('/api/user/profile', {
     headers: { 'Authorization': `Bearer ${token}` },
     credentials: 'include'
   })
   .then(r => r.json())
   .then(console.log);
   

Expected Result:

// Console output:
{
  "id": "uuid",
  "email": "user@example.com",
  "username": "testuser",
  // ... other profile data
}

Success Criteria: ✅ API returns 200, user data correct

---

Test 9: Logout

Objective: Verify logout clears Foundation auth

Steps:

1. On authenticated dashboard
2. Click logout/settings
3. Trigger logout action
4. Verify redirect to login

Expected Result:

✓ Logout triggered
✓ Cookies cleared:
  - foundation_access_token removed
  - auth_user_id removed
✓ Redirected to /login
✓ Previous authenticated state lost

**Test command (if logout has UI):

// Clear cookies manually in console
document.cookie = 'foundation_access_token=; expires=Thu, 01 Jan 1970 00:00:00 UTC;';
document.cookie = 'auth_user_id=; expires=Thu, 01 Jan 1970 00:00:00 UTC;';

Success Criteria: ✅ Cookies cleared, session terminated

---

Test 10: Redirect Destination (Optional)

Objective: Verify redirect works when accessing protected page first

Steps:

1. Logout (or clear cookies)
2. Visit protected page: http://localhost:5173/dashboard?next=/admin
3. Get redirected to login
4. Click "Login with Foundation"
5. After auth, should redirect to /admin instead of /dashboard

Expected Result:

✓ Initial redirect to /login with ?next=/admin
✓ After Foundation auth, redirected to /admin

Success Criteria: ✅ Redirect destination preserved through auth flow

---

Error Testing

Error 1: Invalid Authorization Code

How to trigger:

1. Manually modify URL code parameter: ?code=invalid_code
2. Let callback process

Expected Result:

Error: token_exchange
Message: Failed to exchange authorization code
Redirect to: /login?error=token_exchange

Success Criteria: ✅ Graceful error handling, user redirected to login

---

Error 2: Missing Client Secret

How to trigger:

1. Unset FOUNDATION_OAUTH_CLIENT_SECRET env var
2. Attempt login

Expected Result:

Error: 500 or token_exchange error
Message: Missing environment variables
Redirect to: /login with error

Success Criteria: ✅ Clear error, server doesn't crash

---

Error 3: Foundation Unavailable

How to trigger:

1. Stop Foundation service
2. Attempt login
3. Foundation authorize redirects back

Expected Result:

Error: Token exchange fails
Message: Failed to connect to Foundation
Redirect to: /login with error message

Success Criteria: ✅ Handles offline Foundation gracefully

---

Error 4: Expired Authorization Code

How to trigger:

1. Wait >10 minutes after Foundation redirect
2. Complete the callback

Expected Result:

Error: invalid_grant or code_expired
Message: Authorization code has expired
Redirect to: /login?error=token_exchange

Success Criteria: ✅ Clear error, user redirected to login

---

Browser Compatibility Testing

Test on multiple browsers:

• Chrome/Chromium (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)
• Mobile Chrome
• Mobile Safari

Checklist for each browser:

• Login page renders correctly
• Redirect to Foundation works
• Cookies are set (check Dev Tools)
• Dashboard loads after auth
• Logout works

---

Performance Testing

Page Load Time

# Test login page load
curl -w "@curl-format.txt" -o /dev/null -s https://aethex.dev/login
# Expected: < 2 seconds

# Test dashboard load after auth
curl -H "Authorization: Bearer <token>" -w "@curl-format.txt" -o /dev/null -s https://aethex.dev/api/user/profile
# Expected: < 500ms

Token Exchange Time

Time from receiving auth code to dashboard redirect:

Target: < 2 seconds Acceptable: 2-5 seconds Problematic: > 5 seconds

---

User Flow Testing

Real User Journey

Step-by-step test with actual user:

1. Visit login page - Fresh browser tab
2. Click "Login with Foundation" - No pre-existing auth
3. Enter test credentials - On Foundation
4. Authorize app - If permission prompt appears
5. Check redirect - Should arrive at dashboard
6. Verify profile - Data should display
7. Test API - Make authenticated request
8. Logout - Clear session
9. Re-login - Ensure can login again

Success: All steps complete without errors

---

Deployment Testing

Staging Environment

Before deploying to production:

1. Deploy Phase 3 code to staging
2. Set Foundation OAuth credentials
3. Test complete flow on staging
4. Verify Foundation integration stable
5. Check error handling
6. Review logs for issues
7. Get team sign-off

Production Deployment

1. Backup current auth system
2. Deploy Phase 3 code
3. Monitor logs closely
4. Have rollback plan ready
5. Communicate with users
6. Watch for auth issues

---

Test Report Template

# Phase 3 Testing Report

Date: YYYY-MM-DD
Tester: [Name]
Environment: [Staging/Production]

## Test Results

| Test | Status | Notes |
|------|--------|-------|
| Test 1: Login Page | ✅/❌ | |
| Test 2: Redirect | ✅/❌ | |
| Test 3: Foundation Auth | ✅/❌ | |
| Test 4: Callback | ✅/❌ | |
| Test 5: Token Exchange | ✅/❌ | |
| Test 6: Profile Sync | ✅/❌ | |
| Test 7: Dashboard | ✅/❌ | |
| Test 8: API Requests | ✅/❌ | |
| Test 9: Logout | ✅/❌ | |
| Test 10: Redirects | ✅/❌ | |

## Errors Encountered

[List any errors found]

## Performance Metrics

- Login page load: XXX ms
- Token exchange: XXX ms
- Dashboard load: XXX ms

## Browser Compatibility

- Chrome: ✅/❌
- Firefox: ✅/❌
- Safari: ✅/❌
- Edge: ✅/❌

## Recommendation

🟢 Ready for production / 🟡 Needs fixes / 🔴 Do not deploy

[Explain any blockers]

---

Monitoring After Deployment

Key Metrics to Monitor

1. Authentication Success Rate

   • Should be >99%
   • Track failed logins

2. Error Categories

   • Code exchange failures
   • Token validation failures
   • Profile sync failures

3. Performance

   • Token exchange time (target <2s)
   • Dashboard load time after auth
   • API request latency

4. User Feedback

   • Support tickets about login
   • Issues reported by users
   • Accessibility issues

Alert Thresholds

Set alerts for:

• Auth failure rate > 5%
• Token exchange time > 5 seconds
• Foundation connectivity issues
• Database sync failures

---

Rollback Triggers

Immediately rollback if:

• Auth failure rate > 25%
• Unable to authenticate any new users
• Data corruption in user_profiles
• Foundation connection completely down
• Security vulnerability discovered

---

Testing Status: ⏳ Ready to Test

Once Foundation OAuth credentials are obtained and staging environment is ready, proceed with testing according to this plan.