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