feat: add comprehensive authentication debug test suite
Add automated authentication testing infrastructure: - AUTH-DEBUG-GUIDE.md: Complete guide for auth debugging - auth-debug.spec.ts: Comprehensive auth flow validation tests - playwright.auth.config.ts: Specialized config with extended timeouts - auth-debug-setup.ts: Global test environment setup - auth-debug-teardown.ts: Test cleanup and environment reset Features: - Admin user validation and permissions testing - Email format validation including localhost domains - User registration and OAuth integration testing - Database connectivity and session management - Password security and error handling validation - Cross-browser testing with mobile support - Enhanced reporting and interactive debugging - CI/CD integration with artifacts and JUnit reports Replaces manual browser console debugging scripts with automated, cross-browser E2E tests for better reliability and maintainability.
This commit is contained in:
William Valentin
421
tests/e2e/AUTH-DEBUG-GUIDE.md
Normal file
421
tests/e2e/AUTH-DEBUG-GUIDE.md
Normal file
@@ -0,0 +1,421 @@
|
||||
# 🔐 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.
|
||||
Reference in New Issue
Block a user