gh-otoshek-claude-code-toolkit/skills/django-allauth/references/test-validation-guide.md

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:

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:

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:

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:

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:

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:

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):

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