269 lines
8.1 KiB
Markdown
269 lines
8.1 KiB
Markdown
# 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.
|