rxminder/tests/e2e/AUTH-DEBUG-SETUP-GUIDE.md

Authentication Debug Setup Guide

This guide explains the auth-debug-setup.ts file and how to use it for debugging authentication flows in the Medication Reminder application.

Overview

The auth-debug-setup.ts file is a Playwright global setup script specifically designed for debugging authentication-related issues. It ensures that all required services are running and properly configured before running authentication tests.

What It Does

🔧 Service Initialization

• Frontend Service: Verifies the app is running on http://localhost:8080
• CouchDB Database: Ensures CouchDB is accessible on http://localhost:5984
• Database Setup: Creates necessary databases if they don't exist
• Admin User Verification: Tests admin login functionality end-to-end

📊 Diagnostics

• Service Health Checks: Comprehensive connectivity testing
• Database Status: Lists available databases and connection status
• Environment Information: Logs Node.js version, platform, and environment variables
• Network Connectivity: Tests various endpoints for accessibility

File Structure

// Main setup functions
globalSetup(); // Orchestrates all setup tasks
waitForServices(); // Waits for services to be ready
initializeTestData(); // Creates required databases
verifyAdminUser(); // Tests admin login flow
logEnvironmentInfo(); // Logs debugging information

// Diagnostic utilities
runServiceDiagnostics(); // Comprehensive service testing
testDatabaseConnectivity(); // Detailed database status

Configuration

Required Services

Before running auth debug tests, ensure these services are running:

1. Frontend Application

   bun run dev
   # Runs on http://localhost:8080
   

2. CouchDB Database

   docker-compose -f docker/docker-compose.yaml up -d
   # Runs on http://localhost:5984
   

Environment Variables

The setup respects these environment variables:

• NODE_ENV: Environment mode (development/test/production)
• CI: CI/CD environment flag
• DEBUG_MODE: Enables additional debugging features

Database Configuration

The setup creates these databases automatically:

• users - User accounts and authentication data
• medications - Medication information
• settings - Application settings
• taken_doses - Medication intake records
• reminders - Reminder configurations

Default Credentials

The setup uses these default credentials for testing:

• CouchDB: admin:password
• Test Admin User: admin@localhost:admin123!

Usage

Running Auth Debug Tests

# Run auth debug tests specifically
bunx playwright test --config=tests/e2e/playwright.auth.config.ts

# Run with UI for interactive debugging
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --ui

# Run in debug mode
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --debug

Manual Setup Verification

You can verify the setup manually:

# Check frontend
curl http://localhost:8080

# Check CouchDB
curl -u admin:password http://localhost:5984

# List databases
curl -u admin:password http://localhost:5984/_all_dbs

Troubleshooting

Common Issues

1. Services Not Ready

Symptoms: Setup fails with service connection errors Solutions:

# Check if services are running
docker ps
netstat -tlnp | grep 8080
netstat -tlnp | grep 5984

# Restart services
docker-compose -f docker/docker-compose.yaml restart
bun run dev

2. Database Connection Failed

Symptoms: CouchDB authentication or connection errors Solutions:

# Check CouchDB logs
docker-compose -f docker/docker-compose.yaml logs couchdb

# Reset CouchDB data
docker-compose -f docker/docker-compose.yaml down -v
docker-compose -f docker/docker-compose.yaml up -d

3. Admin User Not Found

Symptoms: Admin login verification fails Solutions:

• Check if admin user exists in the users database
• Verify credentials match the expected format
• Create admin user manually if needed

4. Timeout Issues

Symptoms: Setup times out waiting for services Solutions:

# Increase timeout values in setup
# Check system resources
free -h
docker stats

# Reduce parallel processes
pkill -f "node.*vite"
pkill -f "playwright"

Debug Logs

The setup provides detailed logging at different levels:

// Enable debug logging
logger.setLevel(LogLevel.DEBUG);

// View specific context logs
logger.getLogs('SETUP');
logger.getLogs('AUTH');
logger.getLogs('DATABASE');

Diagnostic Output

The setup generates comprehensive diagnostic information:

🌍 Environment Information:
   Node.js: v18.17.0
   Platform: linux
   NODE_ENV: test
   CI: false
   Frontend URL: http://localhost:8080
   CouchDB URL: http://localhost:5984

🔍 Running comprehensive service diagnostics...
   Frontend status: 200 OK
   Database connected with 5 databases
   Health endpoint accessible

✅ Auth debug setup completed in 2847ms

Integration with Test Suite

Playwright Configuration

The setup integrates with playwright.auth.config.ts:

export default defineConfig({
  globalSetup: require.resolve('./auth-debug-setup.ts'),
  globalTeardown: require.resolve('./auth-debug-teardown.ts'),
  // ... other config
});

Test Dependencies

Tests that depend on this setup:

• auth-debug.spec.ts - Main authentication validation tests
• admin.spec.ts - Admin functionality tests
• auth.spec.ts - General authentication tests

Best Practices

1. Environment Isolation

• Use dedicated test databases
• Clean up test data between runs
• Avoid production credentials

2. Robust Error Handling

• Don't fail setup for non-critical issues
• Log warnings for optional features
• Provide helpful error messages

3. Service Dependencies

• Wait for all required services
• Test actual connectivity, not just port availability
• Verify service functionality, not just status

4. Debugging Support

• Comprehensive logging at appropriate levels
• Detailed diagnostic information
• Clear failure messages with next steps

Development

Modifying the Setup

When modifying the setup script:

1. Test thoroughly in different environments
2. Maintain backward compatibility with existing tests
3. Update documentation for any new features
4. Add appropriate logging for debugging

Adding New Services

To add new service checks:

// Add to waitForServices()
await waitForService('http://localhost:9000', 'NewService');

// Add diagnostic check
async function checkNewService() {
  // Implementation
}

Environment-Specific Configuration

For different environments:

const config = {
  development: {
    timeout: 60000,
    retries: 3,
  },
  ci: {
    timeout: 120000,
    retries: 5,
  },
};

Related Files

• auth-debug-teardown.ts - Cleanup and reporting
• auth-debug.spec.ts - Main authentication tests
• playwright.auth.config.ts - Playwright configuration
• AUTH-DEBUG-GUIDE.md - Test execution guide

Support

For issues with the auth debug setup:

1. Check the diagnostic output for specific error messages
2. Verify all required services are running
3. Review the troubleshooting section above
4. Check related test files for configuration examples
5. Enable debug logging for detailed information

The setup is designed to be self-diagnosing and should provide clear information about any issues encountered during initialization.