gh-lyndonkl-claude/skills/code-data-analysis-scaffolds/resources/examples/tdd-authentication.md

# TDD Example: User Authentication

Complete TDD example showing test-first development for authentication function.

## Task

Build a `validate_login(username, password)` function that:
- Returns `True` for valid credentials
- Returns `False` for invalid password
- Raises `ValueError` for missing username/password
- Raises `User Not FoundError` for nonexistent users
- Logs failed attempts

## Step 1: Write Tests FIRST

```python
# test_auth.py
import pytest
from auth import validate_login, UserNotFoundError

# HAPPY PATH
def test_valid_credentials():
    """User with correct password should authenticate"""
    assert validate_login("alice@example.com", "SecurePass123!") == True

# EDGE CASES
def test_empty_username():
    """Empty username should raise ValueError"""
    with pytest.raises(ValueError, match="Username required"):
        validate_login("", "password")

def test_empty_password():
    """Empty password should raise ValueError"""
    with pytest.raises(ValueError, match="Password required"):
        validate_login("alice@example.com", "")

def test_none_credentials():
    """None values should raise ValueError"""
    with pytest.raises(ValueError):
        validate_login(None, None)

# ERROR CONDITIONS
def test_invalid_password():
    """Wrong password should return False"""
    assert validate_login("alice@example.com", "WrongPassword") == False

def test_nonexistent_user():
    """User not in database should raise UserNotFoundError"""
    with pytest.raises(UserNotFoundError):
        validate_login("nobody@example.com", "anypassword")

def test_case_sensitive_password():
    """Password check should be case-sensitive"""
    assert validate_login("alice@example.com", "securepass123!") == False

# STATE/SIDE EFFECTS
def test_failed_attempt_logged(caplog):
    """Failed login should be logged"""
    validate_login("alice@example.com", "WrongPassword")
    assert "Failed login attempt" in caplog.text
    assert "alice@example.com" in caplog.text

def test_successful_login_logged(caplog):
    """Successful login should be logged"""
    validate_login("alice@example.com", "SecurePass123!")
    assert "Successful login" in caplog.text

# INTEGRATION TEST
@pytest.fixture
def mock_database():
    """Mock database with test users"""
    return {
        "alice@example.com": {
            "password_hash": "hashed_SecurePass123!",
            "salt": "random_salt_123"
        }
    }

def test_database_integration(mock_database, monkeypatch):
    """Function should query database correctly"""
    def mock_get_user(username):
        return mock_database.get(username)

    monkeypatch.setattr("auth.get_user_from_db", mock_get_user)
    result = validate_login("alice@example.com", "SecurePass123!")
    assert result == True
```

## Step 2: Run Tests (They Should FAIL - Red)

```bash
$ pytest test_auth.py
FAILED - ModuleNotFoundError: No module named 'auth'
```

## Step 3: Write Minimal Implementation (Green)

```python
# auth.py
import logging
import hashlib

logger = logging.getLogger(__name__)

class UserNotFoundError(Exception):
    pass

def validate_login(username, password):
    # Input validation
    if not username:
        raise ValueError("Username required")
    if not password:
        raise ValueError("Password required")

    # Get user from database
    user = get_user_from_db(username)
    if user is None:
        raise UserNotFoundError(f"User {username} not found")

    # Hash password and compare
    password_hash = hash_password(password, user['salt'])
    is_valid = (password_hash == user['password_hash'])

    # Log attempt
    if is_valid:
        logger.info(f"Successful login for {username}")
    else:
        logger.warning(f"Failed login attempt for {username}")

    return is_valid

def get_user_from_db(username):
    # Stub - implement database query
    users = {
        "alice@example.com": {
            "password_hash": hash_password("SecurePass123!", "random_salt_123"),
            "salt": "random_salt_123"
        }
    }
    return users.get(username)

def hash_password(password, salt):
    # Simplified - use bcrypt/argon2 in production
    return hashlib.sha256(f"{password}{salt}".encode()).hexdigest()
```

## Step 4: Run Tests Again (Should PASS - Green)

```bash
$ pytest test_auth.py -v
test_valid_credentials PASSED
test_empty_username PASSED
test_empty_password PASSED
test_none_credentials PASSED
test_invalid_password PASSED
test_nonexistent_user PASSED
test_case_sensitive_password PASSED
test_failed_attempt_logged PASSED
test_successful_login_logged PASSED
test_database_integration PASSED

========== 10 passed in 0.15s ==========
```

## Step 5: Refactor (Keep Tests Green)

```python
# auth.py (refactored for readability)
class AuthenticationService:
    def __init__(self, user_repo, password_hasher):
        self.user_repo = user_repo
        self.password_hasher = password_hasher
        self.logger = logging.getLogger(__name__)

    def validate_login(self, username, password):
        self._validate_inputs(username, password)
        user = self._get_user(username)
        is_valid = self._check_password(password, user)
        self._log_attempt(username, is_valid)
        return is_valid

    def _validate_inputs(self, username, password):
        if not username:
            raise ValueError("Username required")
        if not password:
            raise ValueError("Password required")

    def _get_user(self, username):
        user = self.user_repo.get_by_username(username)
        if user is None:
            raise UserNotFoundError(f"User {username} not found")
        return user

    def _check_password(self, password, user):
        password_hash = self.password_hasher.hash(password, user.salt)
        return password_hash == user.password_hash

    def _log_attempt(self, username, is_valid):
        if is_valid:
            self.logger.info(f"Successful login for {username}")
        else:
            self.logger.warning(f"Failed login attempt for {username}")
```

Tests still pass after refactoring!

## Key Takeaways

1. **Tests written FIRST** define expected behavior
2. **Minimal implementation** to make tests pass
3. **Refactor** with confidence (tests catch regressions)
4. **Comprehensive coverage**: happy path, edge cases, errors, side effects, integration
5. **Fast feedback**: Know immediately if something breaks

## Self-Assessment

Using rubric:

- **Clarity** (5/5): Requirements clearly defined by tests
- **Completeness** (5/5): All cases covered (happy, edge, error, integration)
- **Rigor** (5/5): TDD cycle followed (Red → Green → Refactor)
- **Actionability** (5/5): Tests are executable specification

**Average**: 5.0/5 ✓

This is production-ready test-first code.