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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```yaml
# 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

```bash
# 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

```typescript
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

```bash
# 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.