Initial commit
This commit is contained in:
Zhongwei Li
268
skills/django-allauth/references/test-validation-guide.md
Normal file
268
skills/django-allauth/references/test-validation-guide.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# Django-Allauth Test Validation Guide
|
||||
|
||||
This reference provides detailed information about the django-allauth test suite and what each test category validates.
|
||||
|
||||
## Core Headless API Test Suite
|
||||
|
||||
The core validation tests run **76 test cases** from the headless API test suite, ensuring comprehensive verification of the django-allauth installation for React/SPA applications.
|
||||
|
||||
**Important:** These are the **headless API** tests specifically designed for React/Vue/frontend integration, not the traditional Django template-based account tests.
|
||||
|
||||
## Test Requirements
|
||||
|
||||
- **Pytest version:** `>=7.4,<9.0` (pytest 9.x has compatibility issues)
|
||||
- **Pytest-asyncio version:** `==0.23.8`
|
||||
|
||||
### Test Categories
|
||||
|
||||
#### 1. Login Tests (16 tests)
|
||||
**File:** `tests/apps/headless/account/test_login.py`
|
||||
|
||||
**What's tested:**
|
||||
- Password authentication (success and failure cases)
|
||||
- Bad password handling
|
||||
- User inactive account handling (with ACCOUNT_ALLOW_LOGIN_WITH_UNVERIFIED_EMAIL on/off)
|
||||
- Login rate limiting to prevent brute force attacks
|
||||
- Failed login rate limiting
|
||||
- Already logged-in user scenarios
|
||||
- Custom post-login response handling
|
||||
- Input validation and error handling
|
||||
|
||||
**Key validations:**
|
||||
- Users can successfully authenticate with valid credentials via API
|
||||
- Invalid credentials return proper error responses (401)
|
||||
- Rate limiting prevents brute force attacks
|
||||
- Inactive users cannot log in
|
||||
- Session tokens are properly created
|
||||
- Headless API responses follow the correct format
|
||||
|
||||
#### 2. Signup Tests (12 tests)
|
||||
**File:** `tests/apps/headless/account/test_signup.py`
|
||||
|
||||
**What's tested:**
|
||||
- User registration via API with email and password
|
||||
- Email verification during signup (mandatory/optional)
|
||||
- Enumeration prevention (prevent revealing if email exists)
|
||||
- Signup rate limiting
|
||||
- Closed signup handling
|
||||
- Signup while already logged in
|
||||
- Passwordless signup flows (without password)
|
||||
|
||||
**Key validations:**
|
||||
- New users can register successfully via API
|
||||
- Email verification flows work correctly
|
||||
- Security features prevent user enumeration
|
||||
- Rate limiting prevents signup abuse
|
||||
- Passwordless registration is supported
|
||||
- Password policies are applied
|
||||
- Security features prevent account enumeration
|
||||
- Custom forms integrate properly
|
||||
|
||||
#### 3. Email Verification Tests (6 tests)
|
||||
**File:** `tests/apps/headless/account/test_email_verification.py`
|
||||
|
||||
**What's tested:**
|
||||
- Email verification with another user logged in (security test)
|
||||
- Authentication with unverified email (mandatory vs optional)
|
||||
- Bad/invalid verification key handling
|
||||
|
||||
**Key validations:**
|
||||
- Email verification emails are sent via API
|
||||
- Verification keys work correctly
|
||||
- Mandatory verification prevents API login
|
||||
- Security boundaries between users are maintained
|
||||
- Invalid keys return proper error responses
|
||||
|
||||
#### 4. Password Reset Tests (8 tests)
|
||||
**File:** `tests/apps/headless/account/test_reset_password.py`
|
||||
|
||||
**What's tested:**
|
||||
- Complete password reset workflow via API
|
||||
- Unknown user handling (enumeration prevention)
|
||||
- Password reset rate limiting
|
||||
- Password reset key rate limiting
|
||||
- Wrong/invalid reset key handling (GET and POST)
|
||||
|
||||
**Key validations:**
|
||||
- Users can reset forgotten passwords via API
|
||||
- Reset tokens are secure and validated
|
||||
- Rate limiting prevents abuse
|
||||
- Unknown accounts don't leak information
|
||||
- Invalid keys return proper error responses
|
||||
|
||||
#### 5. Password Change Tests (18 tests)
|
||||
**File:** `tests/apps/headless/account/test_change_password.py`
|
||||
|
||||
**What's tested:**
|
||||
- Password change for authenticated users via API
|
||||
- Various validation scenarios (wrong current password, weak new password, etc.)
|
||||
- Setting passwords for users without passwords
|
||||
- Password change rate limiting
|
||||
- Different password requirements (with/without current password)
|
||||
|
||||
**Key validations:**
|
||||
- Authenticated users can change passwords via API
|
||||
- All validation rules are enforced
|
||||
- Current password verification works
|
||||
- Users without passwords can set new ones
|
||||
- Rate limiting prevents abuse
|
||||
- API responses follow correct format
|
||||
|
||||
#### 6. Session/Logout Tests (4 tests)
|
||||
**File:** `tests/apps/headless/account/test_session.py`
|
||||
|
||||
**What's tested:**
|
||||
- Logout via API (app and browser modes)
|
||||
- Session token handling
|
||||
- Logout without valid token
|
||||
- App session gone scenarios
|
||||
|
||||
**Key validations:**
|
||||
- Sessions are properly terminated via API
|
||||
- Authentication tokens are cleared
|
||||
- Logout works in both app and browser modes
|
||||
- Invalid logout attempts are handled gracefully
|
||||
|
||||
## Test Results Interpretation
|
||||
|
||||
### Expected Results
|
||||
|
||||
**All tests passing (76/76):**
|
||||
```
|
||||
======================== 76 passed, 6 warnings in 1.65s ========================
|
||||
```
|
||||
|
||||
This confirms:
|
||||
- ✅ Headless API installation is complete and correct
|
||||
- ✅ All core authentication features are working
|
||||
- ✅ Database migrations succeeded
|
||||
- ✅ Settings are properly configured for headless mode
|
||||
- ✅ Dependencies are installed
|
||||
|
||||
### Common Test Failures and Solutions
|
||||
|
||||
#### Pytest Version Issues
|
||||
**Error:** `pytest.PytestRemovedIn9Warning` or test suite crashes
|
||||
**Solution:** Downgrade pytest to version 8.x:
|
||||
```bash
|
||||
pip install 'pytest>=7.4,<9.0' 'pytest-asyncio==0.23.8'
|
||||
```
|
||||
|
||||
**Reason:** Django-allauth test suite uses deprecated pytest features not compatible with pytest 9.x.
|
||||
|
||||
#### Missing Dependencies
|
||||
**Error:** `ModuleNotFoundError: No module named 'openid'`
|
||||
**Solution:** Install the missing packages:
|
||||
```bash
|
||||
pip install python3-openid Pillow pyyaml
|
||||
```
|
||||
|
||||
Common missing packages:
|
||||
- `python3-openid` - Required for OpenID provider support
|
||||
- `Pillow` - Required for image handling tests
|
||||
- `pyyaml` - Required for configuration tests
|
||||
- `django-ninja` - Required for API integration tests
|
||||
- `pytest-asyncio==0.23.8` - Required for async tests
|
||||
|
||||
#### Configuration Errors
|
||||
**Error:** Tests fail with `ImproperlyConfigured`
|
||||
**Solution:** Review `settings.py` for:
|
||||
- Missing apps in `INSTALLED_APPS` (especially `allauth.headless`)
|
||||
- Missing middleware in `MIDDLEWARE` (`allauth.account.middleware.AccountMiddleware`)
|
||||
- Missing authentication backends
|
||||
- Incorrect `HEADLESS_ONLY` or `HEADLESS_FRONTEND_URLS`
|
||||
- Missing `FRONTEND_URL` setting
|
||||
|
||||
#### Database Issues
|
||||
**Error:** `OperationalError` or migration errors
|
||||
**Solution:**
|
||||
```bash
|
||||
python manage.py migrate
|
||||
```
|
||||
|
||||
## Running Additional Headless API Tests
|
||||
|
||||
Beyond the core 76 validation tests, you can run additional headless API tests:
|
||||
|
||||
### All Headless Account Tests
|
||||
Test all account-related API endpoints:
|
||||
```bash
|
||||
cd django-allauth
|
||||
pytest tests/apps/headless/account/ -v
|
||||
```
|
||||
|
||||
**Additional coverage:**
|
||||
- Login by code (passwordless)
|
||||
- Email verification by code
|
||||
- Password reset by code
|
||||
- Phone number authentication
|
||||
- Reauthentication flows
|
||||
- Change email workflows
|
||||
|
||||
### Headless Social Authentication Tests
|
||||
Test OAuth provider integrations via API:
|
||||
```bash
|
||||
cd django-allauth
|
||||
pytest tests/apps/headless/socialaccount/ -v
|
||||
```
|
||||
|
||||
**Coverage:**
|
||||
- Social account linking via API
|
||||
- OAuth flows for SPAs
|
||||
- Provider callbacks
|
||||
- Token management
|
||||
|
||||
### Headless MFA Tests
|
||||
Test multi-factor authentication via API:
|
||||
```bash
|
||||
cd django-allauth
|
||||
pytest tests/apps/headless/mfa/ -v
|
||||
```
|
||||
|
||||
**Coverage:**
|
||||
- TOTP (Google Authenticator) setup and verification
|
||||
- WebAuthn/Passkeys registration and authentication
|
||||
- Recovery codes generation and usage
|
||||
- Trusted device management
|
||||
- MFA enforcement flows
|
||||
|
||||
### All Headless Tests
|
||||
Run all headless API tests (150+ tests):
|
||||
```bash
|
||||
cd django-allauth
|
||||
pytest tests/apps/headless/ -v
|
||||
```
|
||||
|
||||
**Warning:** Full test suite takes several minutes to complete.
|
||||
|
||||
## Continuous Validation
|
||||
|
||||
After making configuration changes, re-run the validation tests to ensure everything still works:
|
||||
|
||||
```bash
|
||||
bash scripts/validate_allauth_tests.sh
|
||||
```
|
||||
|
||||
This is especially important after:
|
||||
- Modifying `settings.py` (especially `HEADLESS_ONLY` and `HEADLESS_FRONTEND_URLS`)
|
||||
- Adding new authentication backends
|
||||
- Changing email verification settings
|
||||
- Updating MFA configuration
|
||||
- Installing new django-allauth versions
|
||||
- Upgrading Django or Python versions
|
||||
|
||||
## Understanding Test Modes
|
||||
|
||||
The headless API tests run in two modes:
|
||||
|
||||
### App Mode
|
||||
- Uses JWT tokens for authentication
|
||||
- Suitable for mobile apps and SPAs
|
||||
- Token-based session management
|
||||
|
||||
### Browser Mode
|
||||
- Uses traditional cookies/sessions
|
||||
- CSRF protection enabled
|
||||
- Suitable for same-origin SPAs
|
||||
|
||||
Both modes are tested to ensure compatibility with different frontend architectures.
|
||||
Reference in New Issue
Block a user