thrilltrack-explorer/AUTHENTICATION_TESTING_GUIDE.md

# Authentication System - Testing Guide

## Quick Start Testing

### Prerequisites

1. **Django Backend Running**
```bash
cd django-backend
python manage.py runserver
```

2. **Next.js Frontend Running**
```bash
npm run dev
# or
bun dev
```

3. **Test User Account**
Create a test user via Django admin or API:
```bash
cd django-backend
python manage.py createsuperuser
```

## Test Scenarios

### Scenario 1: New User Registration

1. Open http://localhost:3000
2. Click "Sign Up" button
3. Fill in the form:
   - Username: testuser
   - Email: test@example.com
   - Password: TestPass123!
   - Confirm Password: TestPass123!
4. Click "Sign Up"
5. **Expected:** Success message, modal closes
6. **Note:** User needs to login separately (Django doesn't auto-login on registration)

### Scenario 2: Login Flow

1. Open http://localhost:3000
2. Click "Login" button
3. Enter credentials:
   - Email: test@example.com
   - Password: TestPass123!
4. Click "Sign In"
5. **Expected:**
   - Modal closes
   - User avatar appears in header
   - Username/email displayed
   - Dashboard link appears in welcome section

### Scenario 3: Access Dashboard

1. After logging in, click "Dashboard" link
2. **Expected:**
   - Redirected to /dashboard
   - User profile card displays
   - Username and email shown
   - User ID visible
   - Quick actions section present

### Scenario 4: Logout Flow

1. While logged in, click "Logout" button
2. **Expected:**
   - Redirected to home page
   - Login/Sign Up buttons reappear
   - Dashboard link hidden
   - User avatar gone

### Scenario 5: Protected Route Access

1. Ensure you're logged out (click Logout if needed)
2. Manually navigate to http://localhost:3000/dashboard
3. **Expected:**
   - Brief loading screen
   - Automatic redirect to home page

### Scenario 6: Token Persistence

1. Login to the application
2. Open browser DevTools → Application → Local Storage
3. **Expected:**
   - `thrillwiki_access_token` present
   - `thrillwiki_refresh_token` present
4. Refresh the page (F5)
5. **Expected:**
   - User remains logged in
   - No need to login again

### Scenario 7: Password Reset Request

1. Click "Login" button
2. Click "Forgot your password?" link
3. Enter email: test@example.com
4. Click "Send Reset Email"
5. **Expected:**
   - Success message shown
   - Check Django console for email output
   - Email contains reset link

### Scenario 8: OAuth Flow (Google)

**Note:** Requires Google OAuth configuration in Django backend

1. Click "Login" button
2. Click "Sign in with Google" button
3. **Expected:**
   - Redirected to Django OAuth endpoint
   - Redirected to Google authorization
   - After authorization, redirected back to callback
   - Logged in and redirected to dashboard

### Scenario 9: MFA Challenge

**Note:** Requires user with MFA enabled

1. Enable MFA for test user in Django admin
2. Login with that user
3. **Expected:**
   - After email/password, MFA code input appears
   - Enter TOTP code from authenticator app
   - After successful verification, redirected to dashboard

### Scenario 10: Session Expiry

1. Login to the application
2. Open DevTools → Application → Local Storage
3. Delete `thrillwiki_access_token`
4. Try to navigate to dashboard
5. **Expected:**
   - Redirected to home page
   - Need to login again

## Browser DevTools Checks

### Local Storage Verification

Open DevTools → Application → Local Storage → http://localhost:3000

**When Logged In:**
```
thrillwiki_access_token: eyJ0eXAiOiJKV1QiLCJhbGc...
thrillwiki_refresh_token: eyJ0eXAiOiJKV1QiLCJhbGc...
```

**When Logged Out:**
Should be empty or missing

### Network Requests

Open DevTools → Network → XHR

**On Login:**
- POST to `/api/v1/auth/login/`
- Response: `{ "access": "...", "refresh": "..." }`
- GET to `/api/v1/auth/user/`
- Response: User object with id, username, email

**On Dashboard Load:**
- GET to `/api/v1/auth/user/`
- Should include `Authorization: Bearer <token>` header

## Error Scenarios to Test

### Invalid Credentials

1. Try to login with wrong password
2. **Expected:** Error message "Invalid credentials" or similar

### Network Error

1. Stop Django backend
2. Try to login
3. **Expected:** Error message about network/server error

### Token Expiry (Manual)

1. Login successfully
2. In DevTools, edit `thrillwiki_access_token` to invalid value
3. Try to access protected route
4. **Expected:** Token refresh attempted, then logout if refresh fails

### Validation Errors

1. Try to register with:
   - Password too short
   - Passwords don't match
   - Invalid email format
2. **Expected:** Validation error messages displayed

## Console Messages

### Expected Console Output (Normal Flow)

```
Access token refreshed successfully  // Every ~55 minutes
Auth check complete
User loaded: {username: "testuser", ...}
```

### Error Console Output

```
Failed to refresh token: ...
Refresh token expired, logging out
Login failed: ...
```

## API Endpoint Testing (Optional)

### Using curl or Postman

**Register:**
```bash
curl -X POST http://localhost:8000/api/v1/auth/register/ \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser","email":"test@example.com","password":"TestPass123!"}'
```

**Login:**
```bash
curl -X POST http://localhost:8000/api/v1/auth/login/ \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"TestPass123!"}'
```

**Get User (with token):**
```bash
curl http://localhost:8000/api/v1/auth/user/ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

## Common Issues & Solutions

### Issue: Can't login, getting 401 errors
**Solution:** Check Django backend is running and accessible at http://localhost:8000

### Issue: CORS errors in console
**Solution:** Ensure Django settings have proper CORS configuration for http://localhost:3000

### Issue: Tokens not persisting
**Solution:** Check browser privacy settings allow localStorage

### Issue: OAuth not working
**Solution:** Verify OAuth credentials configured in Django backend .env file

### Issue: MFA not appearing
**Solution:** User must have MFA enabled in Django admin first

## Success Indicators

✅ **All tests passing if:**
- Can register new user
- Can login with valid credentials
- Dashboard loads with user info
- Logout works and clears session
- Protected routes redirect when not logged in
- Tokens persist across page refreshes
- Password reset email sent
- OAuth flow completes (if configured)
- MFA challenge works (if configured)
- Error messages display appropriately

## Next Steps After Testing

1. **Fix any bugs found** during testing
2. **Document any issues** in GitHub issues
3. **Consider security audit** before production
4. **Set up production environment** variables
5. **Test in production-like environment** (staging)
6. **Add automated tests** (unit, integration, e2e)
7. **Monitor error logs** for auth failures
8. **Set up user analytics** (optional)

## Testing Checklist

Use this checklist to track testing progress:

- [ ] New user registration works
- [ ] Login with email/password works
- [ ] Dashboard displays user info correctly
- [ ] Logout works and clears tokens
- [ ] Protected route redirects when logged out
- [ ] Direct dashboard access requires login
- [ ] Tokens persist on page refresh
- [ ] Password reset email sent
- [ ] OAuth Google works (if configured)
- [ ] OAuth Discord works (if configured)
- [ ] MFA challenge works (if configured)
- [ ] Invalid credentials show error
- [ ] Network errors handled gracefully
- [ ] Form validation works
- [ ] Token refresh works automatically
- [ ] Session expiry handled properly
- [ ] UI responsive on mobile
- [ ] Loading states display correctly
- [ ] Error messages clear and helpful
- [ ] No console errors (except expected ones)

**Date Tested:** ___________
**Tested By:** ___________
**Environment:** Development / Staging / Production
**Status:** Pass / Fail / Needs Work