API Test Cases Reference
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The API Test Cases Reference provides a comprehensive overview of the functional and integration tests designed to validate the FlextAuth facade and its underlying services. These tests ensure the reliability of core authentication workflows, including user registration, identity management, session handling, and token operations. The test suite is structured into multiple "case groups" (e.g., case_01 through case_11) that are aggregated into a single public test facade, TestsFlextAuthApi, to facilitate execution and maintainability.
The scope of these test cases covers both successful "happy path" scenarios and robust error handling for edge cases, such as invalid inputs, duplicate registrations, and account lockouts. By utilizing a common FlextAuthApiTestDataHelper, the suite maintains consistency in data generation and validation patterns across different test modules.
Sources: tests/unit/test_api.py:19-35, tests/unit/api_cases/case_01.py:1-15, tests/README.md:10-25
Architecture and Test Organization
The API testing architecture follows a modular approach where specific features are isolated into case-specific classes. These classes are then inherited by a central test facade. This structure allows developers to focus on specific functional areas while ensuring the entire API surface is covered.
Component Interaction Flow
The following diagram illustrates how the FlextAuth facade interacts with its internal services during a standard testing lifecycle.
This diagram shows the delegation of tasks from the main FlextAuth entry point to specialized internal managers and services.
Sources: tests/unit/api_cases/case_01.py:18-24, tests/unit/api_cases/case_09.py:15-30
Core API Services
| Service Property | Responsibility | Key Test Cases |
|---|---|---|
identity_service | Manages user entities, lookups, and registration logic. | test_get_user_method, test_get_user_by_username_method |
session_service | Handles session creation, lifecycle, and cleanup. | test_session_management, test_cleanup_expired_sessions |
token_service | Manages JWT token generation and validation. | test_flext_auth_validate_token, test_create_token_for_user |
registry | Maintains a list of active authentication providers. | test_registry_lists_providers, test_provider_registry_initialization |
Sources: tests/unit/api_cases/case_01.py:20-23, tests/unit/api_cases/case_07.py:16-40, tests/unit/api_cases/case_09.py:15-50
Functional Test Categories
User Registration and Identity
Tests in this category validate the creation of new user identities and the enforcement of business rules such as email normalization and username uniqueness.
- Email Normalization: Validates that emails are converted to lowercase during registration (e.g.,
TEST@EXAMPLE.COMbecomestest@example.com). - Duplicate Handling: Ensures that registering a username that already exists returns a failure result.
- Validation Rules: Checks for minimum username length and password strength requirements.
Sources: tests/unit/api_cases/case_01.py:38-51, tests/unit/api_cases/case_02.py:53-60, tests/unit/api_cases/case_05.py:112-127
Authentication and Security
Authentication tests focus on the authenticate_user method and the security mechanisms surrounding it.
The sequence above details the logic for credential verification and subsequent session creation.
Sources: tests/unit/api_cases/case_01.py:108-115, tests/unit/api_cases/case_04.py:114-125
Account Lockout Logic
The system implements a lockout mechanism after a defined number of failed attempts (default is 5). Tests verify that once the threshold is reached, subsequent attempts return a "locked" or "inactive" status error.
Sources: tests/unit/api_cases/case_04.py:114-125, tests/unit/api_cases/case_07.py:113-125
Session and Token Management
This section covers the lifecycle of sessions and JWT tokens.
- Active Sessions: Tests verify that
get_active_sessionscorrectly retrieves sessions associated with a specificunique_id. - Session Revocation: Validates the ability to end sessions by ID via the
session_manager. - Token Creation: Confirms that tokens can be generated for authenticated identities, though validation may fail if specific providers (like JWT) are not fully implemented in certain environments.
- Cleanup: Tests the
cleanup_expired_sessionsmethod which removes stale session data from the system.
Sources: tests/unit/api_cases/case_04.py:33-72, tests/unit/api_cases/case_09.py:32-45, tests/unit/api_cases/case_07.py:84-95
Error Handling and Edge Cases
The test suite explicitly targets failure modes to ensure system resilience.
| Scenario | Expected Behavior | Source File |
|---|---|---|
| Empty Credentials | Registration fails with error result. | case_05.py:17-35 |
| Invalid Email Format | Registration fails; error mentions "email" or "pattern". | case_05.py:112-127 |
| Non-existent User | Authentication or lookup returns "not found" error. | case_10.py:25-28 |
| Invalid Session ID | Logout returns failure with "not found" message. | case_05.py:53-60 |
Sources: tests/unit/api_cases/case_05.py:17-60, tests/unit/api_cases/case_10.py:20-30
Initialization and Configuration
FlextAuth supports multiple initialization patterns, which are validated through the API test cases.
Quick Start Pattern
The quick_start() class method provides a simplified entry point. It can optionally create an administrative user during startup.
# Default initialization
auth = FlextAuth.quick_start()
# Initialization without admin user creation
auth = FlextAuth.quick_start(create_admin_user=False)
Sources: tests/unit/api_cases/case_05.py:62-85, tests/unit/api_cases/case_01.py:18-24
Custom Settings
Initialization with FlextAuthSettings allows overriding default parameters such as expiry_minutes, hash_rounds, and the secret_key.
Sources: tests/unit/api_cases/case_05.py:98-110, tests/unit/api_cases/case_01.py:127-131
Conclusion
The API Test Cases within the FLEXT Auth project serve as a rigorous validation layer for the platform's security and identity features. By organizing tests into distinct case groups and utilizing a centralized facade, the project ensures that every component—from low-level username index management to high-level session cleanup—is verified against both functional requirements and performance benchmarks.