gh-christianlouis-inboxconverge/docs/TESTING_GUIDE.md

Testing Guide for Web Interface

This guide will help you test the complete multi-tenant web interface with the backend services.

Prerequisites

• Docker and Docker Compose installed
• Git repository cloned
• Terminal/Command line access

Step 1: Environment Setup

Backend Configuration

1. Navigate to the backend directory:

   cd backend
   

2. Copy the example environment file:

   cp .env.example .env
   

3. Edit the .env file and update the following critical values:

   # Database - should point to Docker service
   DATABASE_URL=postgresql+asyncpg://postgres:password@postgres:5432/inbox_converge
   
   # Redis - should point to Docker service
   REDIS_URL=redis://redis:6379/0
   CELERY_BROKER_URL=redis://redis:6379/0
   CELERY_RESULT_BACKEND=redis://redis:6379/0
   
   # Security - CHANGE THESE IN PRODUCTION!
   SECRET_KEY=your-generated-secret-key-min-32-characters
   ENCRYPTION_KEY=your-generated-encryption-key-min-32-characters
   
   # CORS for frontend
   CORS_ORIGINS=http://localhost:3000,http://localhost:8000
   
   # Google OAuth (optional for testing)
   GOOGLE_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
   GOOGLE_CLIENT_SECRET=your-google-client-secret
   GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback
   

Frontend Configuration

1. Navigate to the frontend directory:

   cd ../frontend
   

2. Create .env.local file:

   echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local
   

Step 2: Start Services

From the project root directory:

# Start all services
docker-compose -f docker-compose.new.yml up -d

# Check that all services are running
docker-compose -f docker-compose.new.yml ps

Expected output should show all services as "Up":

• postgres
• redis
• backend
• celery-worker
• celery-beat
• frontend

Step 3: Initialize Database

Run database migrations:

docker-compose -f docker-compose.new.yml exec backend alembic upgrade head

Step 4: Access the Application

Web Interface

Open your browser to: http://localhost:3000

You should see the landing page with:

• Hero section explaining the service
• Features list
• "Sign In" and "Sign Up" buttons

API Documentation

Open your browser to: http://localhost:8000/api/docs

This shows the interactive Swagger/OpenAPI documentation.

Step 5: Test User Registration

Method 1: Via Web Interface

1. Go to http://localhost:3000
2. Click "Sign Up"
3. Fill in the form:
   • Full Name: "Test User"
   • Email: "test@example.com"
   • Password: "testpassword123"
   • Confirm Password: "testpassword123"
4. Click "Sign up"
5. You should be redirected to the dashboard

Method 2: Via API

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "test@example.com",
    "password": "testpassword123",
    "full_name": "Test User"
  }'

Step 6: Test Login

Via Web Interface

1. Go to http://localhost:3000/login
2. Enter credentials:
   • Email: "test@example.com"
   • Password: "testpassword123"
3. Click "Sign in"
4. You should be redirected to the dashboard

Via API

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=test@example.com&password=testpassword123"

Save the returned access_token for subsequent API requests.

Step 7: Test Dashboard

After logging in, you should see the dashboard with:

• Overview Cards showing:

  • Total Accounts: 0
  • Emails Forwarded: 0
  • Active Accounts: 0
  • Errors: 0

• Recent Processing Runs table (empty initially)

• Quick Actions buttons:

  • Add Mail Account
  • View All Accounts

Step 8: Test Adding Mail Account

Via Web Interface

1. Click "Add Mail Account" button
2. Fill in the form:
   • Account Name: "Test Gmail"
   • Email: "test@gmail.com"
   • Click "Auto-Detect" to automatically fill settings
   • Or manually enter:
     • Protocol: POP3+SSL
     • Host: pop.gmail.com
     • Port: 995
     • Username: test@gmail.com
     • Password: (your Gmail app password)
     • Use SSL: checked
     • Check Interval: 5 minutes
3. Click "Test Connection" (optional)
4. Click "Save"

Via API

TOKEN="your-access-token-from-login"

curl -X POST http://localhost:8000/api/v1/mail-accounts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Gmail",
    "protocol": "pop3_ssl",
    "host": "pop.gmail.com",
    "port": 995,
    "username": "test@gmail.com",
    "password": "your-app-password",
    "use_ssl": true,
    "check_interval_minutes": 5
  }'

Step 9: Test Auto-Detection Feature

The auto-detection feature automatically configures mail server settings:

Via Web Interface

1. Go to Add Mail Account
2. Enter email: "test@outlook.com"
3. Click "Auto-Detect"
4. Settings should be automatically filled:
   • Protocol: IMAP+SSL
   • Host: outlook.office365.com
   • Port: 993

Supported providers:

• Gmail (pop.gmail.com / imap.gmail.com)
• Outlook/Hotmail (outlook.office365.com)
• Yahoo (pop.mail.yahoo.com / imap.mail.yahoo.com)
• GMX (pop.gmx.com / imap.gmx.com)
• WEB.de (pop3.web.de / imap.web.de)
• T-Online (pop.t-online.de / imap.t-online.de)

Step 10: Test Mail Account Management

List Accounts

Navigate to "Mail Accounts" page to see all configured accounts with:

• Account name and email
• Status indicator (active/inactive)
• Last checked timestamp
• Error messages (if any)
• Enable/Disable toggle
• Edit and Delete buttons

Edit Account

1. Click "Edit" button on an account
2. Modify settings (e.g., change check interval to 10 minutes)
3. Click "Save"
4. Account should be updated

Delete Account

1. Click "Delete" button on an account
2. Confirm deletion
3. Account should be removed from the list

Step 11: Test Settings Page

1. Navigate to "Settings" from the sidebar
2. View current user profile
3. View subscription information (tier, limits)

Step 12: Test Google OAuth (Optional)

If you configured Google OAuth credentials:

1. Go to http://localhost:3000/login
2. Click "Sign in with Google"
3. You should be redirected to Google's authorization page
4. After authorizing, you should be redirected back and logged in

Step 13: Test Multitenancy Isolation

Create a second user and verify data isolation:

1. Logout from first account
2. Register a new user: "test2@example.com"
3. Add mail accounts for this user
4. Verify that mail accounts from first user are not visible
5. Login back as first user
6. Verify that only first user's accounts are visible

Verification Checklist

• Frontend loads successfully at http://localhost:3000
• Backend API docs accessible at http://localhost:8000/api/docs
• User registration works
• Email/password login works
• Dashboard displays correctly
• Can add mail account
• Auto-detect feature works
• Can edit mail account
• Can delete mail account
• Mail accounts list shows all accounts
• Settings page displays user info
• Logout works correctly
• Multitenancy isolation verified (each user sees only their data)
• Mobile responsive design works (test on mobile device or browser dev tools)

Troubleshooting

Backend not accessible

# Check backend logs
docker-compose -f docker-compose.new.yml logs backend

# Restart backend
docker-compose -f docker-compose.new.yml restart backend

Frontend not loading

# Check frontend logs
docker-compose -f docker-compose.new.yml logs frontend

# Rebuild frontend
docker-compose -f docker-compose.new.yml build frontend
docker-compose -f docker-compose.new.yml restart frontend

Database connection errors

# Check if postgres is running
docker-compose -f docker-compose.new.yml ps postgres

# Check postgres logs
docker-compose -f docker-compose.new.yml logs postgres

# Restart postgres
docker-compose -f docker-compose.new.yml restart postgres

CORS errors in browser console

Verify CORS_ORIGINS in backend/.env includes http://localhost:3000

Authentication fails

1. Clear browser local storage
2. Check backend logs for auth errors
3. Verify SECRET_KEY is set in backend/.env

Performance Testing

Load Testing

Use Apache Bench (ab) or similar tool:

# Test registration endpoint
ab -n 100 -c 10 -p registration.json -T application/json \
  http://localhost:8000/api/v1/auth/register

Email Processing Testing

1. Add multiple mail accounts (5-10)
2. Monitor Celery worker logs:

   docker-compose -f docker-compose.new.yml logs -f celery-worker
   

3. Verify emails are being processed
4. Check processing runs in the dashboard

Cleanup

To stop all services and remove containers:

docker-compose -f docker-compose.new.yml down

To also remove volumes (database data):

docker-compose -f docker-compose.new.yml down -v

Next Steps

After successful testing:

1. Set up proper Google OAuth credentials for production
2. Configure Stripe for payment processing
3. Set up email notifications with Apprise
4. Deploy to production server
5. Set up SSL/TLS certificates
6. Configure proper backup strategy
7. Set up monitoring and alerting

Support

For issues or questions:

• Check logs: docker-compose -f docker-compose.new.yml logs [service-name]
• Review API documentation: http://localhost:8000/api/docs
• Open an issue on GitHub