Test Docstring Standards¶

"""Unit tests for JWTService.

Tests JWT token creation, validation, and decoding functionality. Covers:
- Access token generation with user claims
- Refresh token generation with JTI
- Token validation and type checking
- Token expiration handling
- JWT payload extraction

Note:
    Uses synchronous test pattern (regular def test_*(), NOT async def)
    following FastAPI TestClient conventions.
"""

class TestJWTService:
    """Test suite for JWTService token operations.

    Covers all JWT creation, validation, and decoding scenarios including
    error handling and edge cases.

    Attributes:
        service: JWTService instance created in setup_method
        test_user_id: UUID for test user
        test_email: Email address for test user
    """

def test_create_access_token(self):
    """Test access token creation with user claims.

    Verifies that:
    - Token is generated as a valid JWT string
    - Token contains correct user_id and email claims
    - Token has standard JWT structure (3 parts separated by dots)
    - Token includes expiration and issued-at timestamps

    Note:
        Access tokens use shorter TTL (30 min) vs refresh tokens (30 days)
    """

def test_login_success(self, client: TestClient, verified_user: User):
    """Test successful user login with valid credentials.

    Verifies that:
    - Login returns 200 status code
    - Response includes both access_token and refresh_token
    - Response includes user profile data
    - Token type is "bearer"
    - User email matches the logged-in user

    Args:
        client: FastAPI TestClient fixture for making HTTP requests
        verified_user: Pre-created user with verified email (from fixtures/users.py)

    Note:
        User must have email_verified=True to successfully login.
        Uses TestClient's synchronous pattern (no await needed).
    """

async def test_token_rotation_with_new_refresh_token(
    self, mock_session, mock_encryption, mock_provider_registry
):
    """Test OAuth token rotation detection when provider sends new refresh token.

    Scenario:
        Provider rotates the refresh token during token refresh operation,
        returning a new refresh token in the response. This is Scenario 1
        of the Universal Token Rotation design.

    Setup:
        - Creates provider with existing expired token
        - Mocks OAuth provider to return NEW refresh token
        - Mocks database session and encryption service

    Verifies that:
        - New refresh token is encrypted before storage
        - Database token record is updated with new values
        - Audit log entry records the rotation
        - Session operations (add, flush, commit) are called

    Args:
        mock_session: Mocked AsyncSession for database operations
        mock_encryption: Mocked EncryptionService for token encryption
        mock_provider_registry: Mocked provider registry returning mock provider

    Raises:
        AssertionError: If rotation detection fails or encryption not called

    Note:
        Uses asyncio.run() to execute async service method in synchronous test.
        This test validates the critical token rotation detection logic.
    """

@pytest.fixture
def verified_user(db_session: Session, test_user: User) -> User:
    """Create a test user with verified email for login tests.

    This fixture extends test_user by setting email_verified=True,
    which is required for successful login operations.

    Args:
        db_session: Database session for persisting user changes
        test_user: Base test user fixture from conftest.py

    Returns:
        User: Test user instance with email_verified=True

    Note:
        Modifications persist in database for the test function scope.
        User is cleaned up automatically by db_session cleanup.
    """
    test_user.email_verified = True
    db_session.add(test_user)
    db_session.commit()
    db_session.refresh(test_user)
    return test_user

def setup_method(self):
    """Set up test fixtures before each test method.

    Initializes:
        - JWTService instance
        - Test user ID (UUID)
        - Test email address

    Note:
        Called automatically before each test method in the class.
    """

def teardown_method(self):
    """Clean up test resources after each test method.

    Resets:
        - Global database engine to None
        - Global session maker to None

    Note:
        Ensures clean state for next test to avoid cross-test pollution.
    """

@pytest.mark.parametrize("password,expected_valid", [
    ("short", False),
    ("NoDigits!", False),
    ("noupperca5e!", False),
    ("NOLOWERCASE5!", False),
    ("NoSpecialChar5", False),
    ("ValidPass123!", True),
])
def test_password_strength_validation(self, password, expected_valid):
    """Test password strength validation with various inputs.

    Validates password requirements:
    - Minimum 8 characters
    - At least one uppercase letter
    - At least one lowercase letter
    - At least one digit
    - At least one special character

    Args:
        password: Password string to validate
        expected_valid: Expected validation result (True/False)

    Note:
        Uses pytest.mark.parametrize for multiple test cases.
    """

def test_auth_service_with_mocked_dependencies(
    self, mock_session, mock_password_service, mock_email_service
):
    """Test AuthService password reset with all dependencies mocked.

    Isolation Strategy:
        Uses unittest.mock to isolate AuthService from:
        - Database (AsyncSession)
        - Password hashing (PasswordService)
        - Email sending (EmailService)

    Mocks:
        - mock_session: AsyncSession for database operations
        - mock_password_service: Password hashing and validation
        - mock_email_service: Email notification sending

    Verifies that:
        - AuthService coordinates all dependencies correctly
        - Password is hashed before storage
        - Email notification is sent after password change
        - All service methods are called with correct parameters

    Args:
        mock_session: Mocked database session fixture
        mock_password_service: Mocked password service fixture
        mock_email_service: Mocked email service fixture

    Note:
        This is a true unit test - no real database or external services.
        Validates service orchestration logic only.
    """

# Run linting to catch docstring issues
make lint

# Format code including docstrings
make format

# ❌ Too brief
def test_login_success(self, client, verified_user):
    """Test login."""

# ✅ Proper documentation
def test_login_success(self, client: TestClient, verified_user: User):
    """Test successful user login with valid credentials.

    Verifies that:
    - Login returns 200 status code
    - Response includes both access_token and refresh_token
    - Response includes user profile data
    - Token type is "bearer"

    Args:
        client: FastAPI TestClient fixture for making HTTP requests
        verified_user: Pre-created user with verified email
    """

# ❌ Missing fixture documentation
def test_login_success(self, client: TestClient, verified_user: User):
    """Test successful user login.

    Verifies that login returns tokens.
    """

# ✅ Complete fixture documentation
def test_login_success(self, client: TestClient, verified_user: User):
    """Test successful user login with valid credentials.

    Verifies that:
    - Login returns 200 status code
    - Response includes tokens and user profile

    Args:
        client: FastAPI TestClient fixture for making HTTP requests
        verified_user: Pre-created user with verified email (from fixtures/users.py)

    Note:
        User must have email_verified=True to successfully login.
    """

# ❌ No verification details
def test_token_rotation(self, mock_session):
    """Test token rotation.

    Args:
        mock_session: Mocked database session
    """

# ✅ Clear verification details
def test_token_rotation(self, mock_session):
    """Test OAuth token rotation detection when provider sends new refresh token.

    Verifies that:
        - New refresh token is encrypted before storage
        - Database token record is updated with new values
        - Audit log entry records the rotation
        - Session operations (add, flush, commit) are called

    Args:
        mock_session: Mocked AsyncSession for database operations

    Note:
        This validates the critical token rotation detection logic.
    """

# ❌ Implementation-focused
def test_password_reset(self, auth_service):
    """Calls auth_service.reset_password() and checks result."""

# ✅ Intent-focused
def test_password_reset(self, auth_service: AuthService):
    """Test password reset flow generates valid reset token.

    Verifies that:
        - Reset token is created and stored in database
        - Token has correct expiration (24 hours)
        - Token is properly hashed before storage
        - Reset email is sent to user with token link

    Args:
        auth_service: AuthService instance for password operations

    Note:
        Token must be single-use and expire after 24 hours.
    """