testing-patterns

name	testing-patterns
description	Pytest testing patterns, factory functions, mocking strategies, and TDD workflow. Use when writing unit tests, creating test factories, following TDD red-green-refactor cycle, or determining test coverage priorities.
requires-context	["docs/decisions/business_rules.md","docs/architecture/ARCHITECTURE.md"]
skill_type	universal
version	1.0.0

Testing Patterns and Utilities

Testing Philosophy

Test-Driven Development (TDD):

• Write failing test FIRST.
• Implement minimal code to pass.
• Refactor after green.
• Never write production code without a failing test.
• See test-driven-development skill for the full Iron Law and Red-Green-Refactor cycle.

Behavior-Driven Testing:

• Test behavior, not implementation.
• Focus on public APIs (Services/Routers) and business requirements.
• Avoid testing implementation details (private methods).
• Use descriptive test names: test_<action>_<condition>_<expected_outcome>.

Factory Pattern:

• Create get_mock_x(**overrides) functions.
• Provide sensible defaults.
• Keep tests DRY and maintainable.

---

Coverage Priority Order

When deciding what to test next, work through this priority stack:

Priority	Target	Coverage Goal
🔴 1	Critical business logic (domain constraints, RBAC, payments)	90%+
🟠 2	Complex algorithms and state machines (workflows, state transitions)	85%+
🟡 3	Edge cases that have previously caused bugs (see golden_dataset.yaml)	100% of known cases
🔵 4	Project invariant checks (no broad except, UoW commit, tenant isolation)	All new services
🟢 5	Public API surfaces (FastAPI routers)	80%+
💡 6	Utility and helper functions	70%+

Overall target: ≥80% coverage on src/ ([BUSINESS_RULE_PLACEHOLDER]). Coverage below 70% blocks merge.

---

Factory Pattern

Use simple factory functions to create consistent test data without duplication.

from pydantic import BaseModel
from src.domain.enums import UserRole

class User(BaseModel):
    id: int
    name: str
    role: UserRole   # Always use the enum, never raw strings

def get_mock_user(**overrides) -> User:
    defaults = {
        "id": 1,
        "name": "John Doe",
        "role": UserRole.MEMBER,
    }
    return User(**{**defaults, **overrides})

# Usage in tests
def test_admin_access_allowed():
    user = get_mock_user(role=UserRole.ADMIN)
    assert user.role == UserRole.ADMIN

Tip: For complex SQLAlchemy models with relationships, use factory_boy to manage persistence and FK constraints automatically.

---

Stateful Testing with FakeUnitOfWork

Prefer FakeUnitOfWork over deep repository mocking for service-layer tests. This verifies actual state transitions rather than mock call counts.

# tests/unit/services/test_order_service.py
from tests.utils.fake_unit_of_work import FakeUnitOfWork
from src.application.services.order_service import OrderService
from types import SimpleNamespace
from datetime import datetime, timezone, timedelta

future_date = datetime.now(timezone.utc) + timedelta(hours=3)

def test_cancel_order_success():
    # Arrange
    uow = FakeUnitOfWork()
    uow.orders.entities[1] = SimpleNamespace(id=1, schedule_time=future_date)
    uow.orders.create_order(SimpleNamespace(order_id=1, customer_id=101))
    service = OrderService(uow=uow)

    # Act
    service.cancel_order(order_id=1)

    # Assert
    assert uow.orders.get_order_by_id(1).status == "cancelled"
    assert uow.committed is True   # ← Always verify the commit happened

Always assert uow.committed is True after a successful write operation. A service that fails to commit is silently discarding work.

---

Mocking Patterns

Use unittest.mock / pytest-mock to isolate tests from external dependencies.

# Mocking a service dependency
def test_order_service_sends_confirmation_email(mocker):
    mock_bus = mocker.MagicMock()
    uow = FakeUnitOfWork()
    service = OrderService(uow=uow, bus=mock_bus)

    service.create_order(OrderCreate(email="[e-mail]", ...))

    mock_bus.publish.assert_called_once()
    event = mock_bus.publish.call_args[0][0]
    assert event.customer_email == "[e-mail]"

Rules:

• Mock external dependencies (email, payment gateway, S3) — not the code under test.
• Use FakeUnitOfWork rather than mocking individual repositories.
• Verify mock interactions only when the interaction itself is the behaviour being tested.
• Env var mocking must always use patch.dict('os.environ', {...}), never patch os.environ.get directly to avoid intercepting legitimate env lookups.

---

Tenant Isolation in Integration Tests

All integration tests that write to the database must use a scoped tenant_id to prevent cross-tenant data leakage between test cases.

# conftest.py
@pytest.fixture
def test_tenant(db_session):
    tenant = Tenant(name="Test Tenant", business_id=1)
    db_session.add(tenant)
    db_session.commit()
    return tenant

@pytest.fixture
def scoped_uow(db_session, test_tenant):
    """UnitOfWork pre-scoped to the test tenant."""
    uow = UnitOfWork(db_session)
    uow.set_tenant_context(test_tenant.id)
    return uow

Never share tenant_id=1 across all tests — isolation prevents false passes caused by data left behind by a previous test.

---

Testing Business Invariants

Key project invariants that must have dedicated tests:

# [BUSINESS_RULE_PLACEHOLDER]: No entity overlap / conflict
def test_create_entity_raises_when_conflict_exists():
    uow = FakeUnitOfWork()
    uow.entities.entities[1] = active_entity_fixture()
    service = EntityService(uow=uow)
    with pytest.raises(EntityConflictError):
        service.create_entity(conflicting_entity_data())

# [BUSINESS_RULE_PLACEHOLDER]: Numeric values stored precisely
def test_transaction_stores_precise_value():
    tx = TransactionCreate(amount_cents=1999, ...)
    assert isinstance(tx.amount_cents, int)
    assert tx.amount_cents == 1999

# [BUSINESS_RULE_PLACEHOLDER]: Soft-delete, never hard-delete
def test_delete_entity_sets_is_deleted_flag():
    uow = FakeUnitOfWork()
    uow.entities.entities[1] = entity_fixture()
    service = EntityService(uow=uow)
    service.delete_entity(1)
    assert uow.entities.entities[1].is_deleted is True  # NOT removed from store

# RBAC: require_permission blocks unauthorised access
def test_endpoint_returns_403_for_insufficient_role(client, token):
    response = client.delete("/entities/1", headers={"Authorization": f"Bearer {token}"})
    assert response.status_code == 403

# Exception handling: broad except must re-raise
def test_service_does_not_swallow_infrastructure_error(mocker):
    uow = FakeUnitOfWork()
    uow.entities.get_by_id = mocker.MagicMock(side_effect=DatabaseError("db down"))
    service = EntityService(uow=uow)
    with pytest.raises(Exception):   # must propagate, not be swallowed
        service.get_entity(1)

---

Mutation Testing (High-Confidence QA)

Mutation testing verifies that tests actually catch bugs. Surviving mutants indicate weak assertions.

Tool: mutmut

# Target critical business logic only (fast feedback)
mutmut run --paths-to-mutate src/application/services/some_service.py

# View surviving mutants
mutmut results

# Inspect a specific survivor
mutmut show 42

Target: mutation score ≥ 80% on src/application/services/. If a mutant survives, write a new test case specifically targeting the mutated logic before marking the feature complete.

---

Test Structure (Pytest)

import pytest
from tests.utils.fake_unit_of_work import FakeUnitOfWork

class TestUserService:
    @pytest.fixture(autouse=True)
    def setup(self):
        self.uow = FakeUnitOfWork()
        self.service = UserService(uow=self.uow)

    def test_get_user_not_found_raises_error(self):
        self.uow.users.entities = {}   # empty store
        with pytest.raises(UserNotFoundError):
            self.service.get_user(999)

    def test_create_user_commits_and_returns_dto(self):
        result = self.service.create_user(
            UserCreate(first_name="Jo", last_name="Doe", email="[e-mail]", ...)
        )
        assert result.email == "[e-mail]"
        assert self.uow.committed is True

---

Test Type Selection

Type	When to use	Speed
Unit (FakeUoW)	Service-layer logic, business rules, state transitions	Fast
Unit (mock)	Adapter boundaries (email, payment gateway, S3)	Fast
Integration	Repository → DB round-trips, Alembic migrations, multi-service flows	Medium
API / TestClient	FastAPI router wiring, auth header propagation, status codes	Medium
BDD / Gherkin	High-value user journeys (checkout flow, user signup)	Medium
Performance	p95 latency benchmarks (≥ weekly, not on every commit)	Slow

---

Best Practices

1. Arrange-Act-Assert — keep steps visually distinct.
2. One behaviour per test — avoid god tests that assert many unrelated things.
3. Stateful verification — prefer FakeUnitOfWork state assertions over mock call counts.
4. Always assert uow.committed after write operations.
5. No time.sleep() — use anyio timeouts or condition-based waiting (see systematic-debugging/condition-based-waiting.md).
6. No production data — use factories and fixtures; never seed from a real database.
7. Enum types in factories — use UserRole.MEMBER, not "member".
8. Mutation score target — ≥80% on critical services.

Running Tests

# Full suite
pytest

# With coverage report
pytest --cov=src --cov-report=term-missing

# Specific test file
pytest tests/unit/services/test_user_service.py -v

# Mutation tests (critical services only)
mutmut run --paths-to-mutate src/application/services/some_service.py