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

🔐 Authentication Debug Testing Guide

Overview

The authentication debug test suite (auth-debug.spec.ts) provides comprehensive automated testing and debugging capabilities for all authentication flows in the Medication Reminder App. This replaces the previous manual browser console debugging scripts with fully automated, cross-browser tests.

🎯 What This Replaces

Before (Manual Tests)

• tests/manual/admin-login-debug.js - Browser console script
• tests/manual/auth-db-debug.js - Database debugging script
• tests/manual/debug-email-validation.js - Email validation script

After (Automated Tests)

• tests/e2e/auth-debug.spec.ts - Comprehensive E2E test suite
• Cross-browser automated testing
• CI/CD pipeline integration
• Interactive debugging capabilities

🧪 Test Coverage

1. Admin User Validation

• Verifies admin@localhost account exists
• Tests admin login flow
• Validates admin permissions and UI access
• Checks admin interface functionality

2. Email Format Validation

• Tests various email formats including localhost domains
• Validates email input validation rules
• Covers edge cases and invalid formats
• Ensures proper error messaging

3. User Registration

• Tests user creation with password
• Validates registration form fields
• Checks verification flow
• Ensures unique user handling

4. OAuth Integration

• Verifies OAuth buttons are present
• Tests OAuth flow initiation
• Handles OAuth redirects and errors
• Validates OAuth user creation

5. Database Connection

• Checks system status indicators
• Validates database connectivity
• Ensures app loads properly
• Tests service health

6. Password Security

• Tests password strength requirements
• Validates weak password rejection
• Ensures strong password acceptance
• Checks security messaging

7. Session Management

• Tests session persistence across page reloads
• Validates login state maintenance
• Checks automatic logout scenarios
• Ensures proper session handling

8. Error Handling

• Tests invalid login attempts
• Validates error messaging
• Checks form validation
• Ensures proper feedback

9. User Management

• Tests admin user lookup functionality
• Validates user search capabilities
• Checks user list display
• Ensures admin tools work

🚀 Running Auth Debug Tests

Quick Commands

# Run auth debug tests (headless)
make test-auth-debug

# Run with interactive UI for debugging
make test-auth-debug-ui

# Run specific test with debug mode
bunx playwright test auth-debug.spec.ts --debug

# Run on specific browser
bunx playwright test auth-debug.spec.ts --project=auth-debug-firefox

Full Command Options

# All browsers with full reporting
bunx playwright test --config=tests/e2e/playwright.auth.config.ts

# Single browser with trace
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --project=auth-debug-chromium --trace=on

# Headed mode for visual debugging
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --headed

# Debug specific failing test
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --debug -g "should validate admin user"

🔧 Test Configuration

The auth debug tests use a specialized Playwright configuration (playwright.auth.config.ts) with:

• Extended timeouts for auth operations (60s per test)
• Sequential execution to avoid auth conflicts
• Enhanced reporting with multiple output formats
• Service auto-start for dependencies
• Cross-browser testing on desktop and mobile
• Detailed tracing on failures

Browser Coverage

• Desktop: Chrome, Firefox, Safari
• Mobile: Chrome on Android, Safari on iOS
• Special configs for auth-specific browser settings

📊 Reports and Output

Generated Reports

1. HTML Report: playwright-report-auth/index.html

   • Interactive test results
   • Screenshots and videos
   • Detailed failure analysis

2. JSON Report: playwright-report-auth.json

   • Machine-readable results
   • Integration with CI/CD
   • Detailed test metadata

3. Summary Report: auth-debug-summary.json

   • High-level test statistics
   • Environment information
   • Quick status overview

4. JUnit Report: playwright-auth-results.xml

   • CI/CD integration format
   • Test result parsing
   • Build system integration

Viewing Reports

# Open HTML report
npx playwright show-report playwright-report-auth

# View summary
cat auth-debug-summary.json | jq

# Check specific failures
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --reporter=list

🐛 Debugging Workflows

Interactive Debugging

# Launch interactive debug mode
make test-auth-debug-ui

# Debug specific test
bunx playwright test auth-debug.spec.ts --debug -g "admin user"

# Step through test with browser open
bunx playwright test auth-debug.spec.ts --headed --debug

Common Debugging Scenarios

1. Admin Login Issues

# Debug admin login specifically
bunx playwright test --debug -g "should validate admin user exists"

# Check with different browser
bunx playwright test --project=auth-debug-firefox --debug -g "admin user"

2. Email Validation Problems

# Debug email validation
bunx playwright test --debug -g "email format"

# Run with console output
bunx playwright test -g "email format" --reporter=line

3. OAuth Flow Issues

# Debug OAuth with network logs
bunx playwright test --debug -g "OAuth" --trace=on

# Check OAuth buttons
bunx playwright test --headed -g "OAuth user creation"

4. Database Connection Problems

# Debug database connectivity
bunx playwright test --debug -g "database connection"

# Check service status
bunx playwright test -g "database" --reporter=line

Debug Output Interpretation

The tests include extensive console logging:

Testing email validation for: admin@localhost
✅ Admin user verified and functional
⚠️ Search functionality not implemented - this is optional
Testing weak password (too short): 123
📊 Found 1 users in the system

Log Levels:

• ✅ Success/verification messages
• ⚠️ Warnings (expected issues)
• ❌ Errors requiring attention
• 📊 Information and statistics

🔄 CI/CD Integration

Pipeline Configuration

# GitHub Actions example
name: Auth Debug Tests
on: [push, pull_request]

jobs:
  auth-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: bun install
      - run: bunx playwright install --with-deps
      - run: make test-auth-debug
      - uses: actions/upload-artifact@v3
        if: always()
        with:
          name: auth-test-results
          path: |
            playwright-report-auth/
            auth-debug-summary.json

Environment Variables

# Required for CI
NODE_ENV=test
CI=true
VITE_COUCHDB_URL=http://localhost:5984
VITE_COUCHDB_USERNAME=admin
VITE_COUCHDB_PASSWORD=password

🛠️ Maintenance and Updates

Adding New Auth Tests

1. Add test case to auth-debug.spec.ts
2. Follow naming convention: should [action] [expected result]
3. Include console logging for debugging
4. Handle timeouts appropriately
5. Clean up test data if needed

Example New Test

test('should validate two-factor authentication', async ({ page }) => {
  console.log('Testing 2FA validation...');

  // Test implementation
  await page.fill('input[type="email"]', 'admin@localhost');
  await page.fill('input[type="password"]', 'admin123!');
  await page.click('button[type="submit"]');

  // Check for 2FA prompt
  await expect(page.locator('text=Enter verification code')).toBeVisible({
    timeout: 10000,
  });

  console.log('✅ 2FA prompt displayed correctly');
});

Updating Test Credentials

If admin credentials change, update:

• Test files: auth-debug.spec.ts
• Setup files: auth-debug-setup.ts
• Documentation: This guide

🚨 Troubleshooting

Common Issues

1. Tests Timeout

Symptoms: Tests hang or timeout Solutions:

• Check service availability (http://localhost:8080, http://localhost:5984)
• Increase timeouts in config
• Run with --headed to see what's happening

2. Admin User Not Found

Symptoms: Admin login fails Solutions:

• Verify admin user exists in database
• Check credentials in test file
• Run database initialization

3. Service Not Ready

Symptoms: Cannot connect to app/database Solutions:

• Start services manually: make dev and CouchDB
• Check Docker containers
• Verify ports are not blocked

4. Browser Issues

Symptoms: Tests fail in specific browsers Solutions:

• Update Playwright: bunx playwright install
• Check browser-specific configurations
• Run single browser: --project=auth-debug-chromium

Debug Commands

# Check service status
curl http://localhost:8080
curl http://localhost:5984

# Verify test setup
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --list

# Run with maximum verbosity
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --reporter=line --verbose

# Check configuration
bunx playwright test --config=tests/e2e/playwright.auth.config.ts --reporter=json | jq '.config'

📚 Related Documentation

• Main E2E Guide: tests/e2e/README.md
• Test Cleanup Info: tests/README-CLEANUP.md
• Migration Summary: CLEANUP-SUMMARY.md
• Quick Reference: QUICK-REFERENCE.md

💡 Best Practices

Writing Auth Tests

1. Use unique identifiers (timestamps) for test data
2. Include descriptive console logging
3. Handle both success and failure cases
4. Clean up test artifacts
5. Use appropriate timeouts

Debugging Process

1. Start with interactive mode (--ui or --debug)
2. Check service availability first
3. Review console logs for clues
4. Use browser dev tools when needed
5. Isolate failing tests

Maintenance

1. Run tests regularly to catch regressions
2. Update credentials when changed
3. Add tests for new auth features
4. Monitor test performance
5. Review failure patterns

---

Quick Start: Run make test-auth-debug-ui to launch interactive debugging mode and explore the authentication flows visually.

Need Help?: Check the generated HTML report for detailed test results and failure analysis.