📘 Technical Design 026 — Integration Test Quality Standards¶

# ❌ FORBIDDEN: Mocking internal components in integration test
def test_di_workflow() -> None:
    """Test DI workflow."""

    # ❌ WRONG: Mocking Container defeats integration test purpose
    mock_container = Mock(spec=Container)
    mock_container.resolve.return_value = MockService()

    bootstrap_runtime = BootstrapRuntime()
    bootstrap_runtime.bootstrap(mock_container, plan)

    # This isn't really testing integration!

# ✅ GOOD: Use real Container
def test_di_bootstrap_workflow() -> None:
    """Test complete DI bootstrap workflow."""

    # Real implementations
    container = Container()
    plan = BootstrapPlanBuilder.create().scan_packages(config).build()

    bootstrap_runtime = BootstrapRuntime()
    bootstrap_runtime.bootstrap(container, plan)  # Real interaction

    # Verify actual behavior
    service = container.resolve(ServiceType)
    assert isinstance(service, ServiceType)

# ✅ OK: Mocking external services
def test_application_with_external_api() -> None:
    """Test application behavior with external API."""

    with patch("requests.get") as mock_api:  # External service: OK to mock
        mock_api.return_value = MockResponse({"status": "ok"})

        app = Application()
        result = app.fetch_data()

        assert result["status"] == "ok"

# ❌ FORBIDDEN: Shared state
global_container = None

def setup_module():
    """Set up shared container for all tests."""
    global global_container
    global_container = Container()
    global_container.register(Service, Service)

def test_workflow_1():
    """Test first workflow."""
    service = global_container.resolve(Service)
    # ❌ Test depends on setup_module state

def test_workflow_2():
    """Test second workflow."""
    # ❌ If test_workflow_1 modifies state, this test is affected

# ✅ GOOD: Each test isolated
def test_workflow_1() -> None:
    """Test first workflow."""

    # Fresh setup for this test only
    container = Container()
    container.register(Service, Service)

    service = container.resolve(Service)
    assert isinstance(service, Service)

def test_workflow_2() -> None:
    """Test second workflow."""

    # Completely independent setup
    container = Container()
    container.register(Service, Service)
    container.register(OtherService, OtherService)

    service = container.resolve(Service)
    other = container.resolve(OtherService)
    assert isinstance(service, Service)
    assert isinstance(other, OtherService)

@pytest.fixture
def bootstrap_container() -> Container:
    """Provide a fresh container for each integration test."""
    container = Container()
    container.register(Service, Service)
    return container

def test_workflow_1(bootstrap_container: Container) -> None:
    """Test workflow 1 with isolated container."""
    service = bootstrap_container.resolve(Service)
    assert isinstance(service, Service)

def test_workflow_2(bootstrap_container: Container) -> None:
    """Test workflow 2 with its own isolated container."""
    service = bootstrap_container.resolve(Service)
    assert isinstance(service, Service)

def test_application_bootstrap_and_execution() -> None:
    """Test complete application lifecycle: bootstrap, resolve, execute."""

    # 1. Setup application configuration
    @application(scan_packages=["test_services"])
    class TestApp(ApplicationBase):
        def run(self) -> None:
            pass

    # 2. Create module
    import sys
    sys.modules["test_app"] = type(sys)("test_app")
    sys.modules["test_app"].TestApp = TestApp

    try:
        # 3. Execute through public API
        ApplicationRuntime.launch("test_app:TestApp")

        # 4. Verify outcome: no exceptions, workflow completed
        # Additional assertions about state after execution
    finally:
        del sys.modules["test_app"]

tests/resources/
├── shared_services/  # ❌ Shared across multiple test suites
├── test_di/          # Uses shared_services
└── test_reflection/  # Also uses shared_services (coupling!)

tests/resources/
├── di/
│   ├── bootstrap/     # Resources for bootstrap tests
│   ├── injection/     # Resources for injection tests
│   └── scanning/      # Resources for scanning tests
└── integration/
    └── di_reflection/ # Resources for DI+Reflection integration

def test_di_with_reflection_integration() -> None:
    """Test DI container integrates correctly with reflection system.

    Validates that the DI container uses reflection to:
    1. Scan packages for annotated services
    2. Inspect service constructors for dependencies
    3. Build dependency graphs correctly
    4. Resolve services with transitive dependencies

    This is an integration test of DI + Reflection subsystems.
    """
    # Implementation

def test_container_with_empty_service() -> None:
    """Test container with minimal service."""

    class EmptyService:
        pass

    container = Container()
    container.register(EmptyService, EmptyService)
    service = container.resolve(EmptyService)

    # Too simple, doesn't reflect real usage

def test_di_resolves_service_with_transitive_dependencies() -> None:
    """Test container resolves service with multiple levels of dependencies.

    Realistic scenario: API service depends on database service and logger,
    database depends on connection pool. Tests that all levels resolve correctly.
    """

    class ConnectionPool:
        pass

    class DatabaseService:
        def __init__(self, pool: ConnectionPool) -> None:
            self.pool = pool

    class LoggerService:
        pass

    class ApiService:
        def __init__(self, db: DatabaseService, logger: LoggerService) -> None:
            self.db = db
            self.logger = logger

    container = Container()
    container.register_singleton(ConnectionPool, ConnectionPool)
    container.register_singleton(DatabaseService, DatabaseService)
    container.register_singleton(LoggerService, LoggerService)
    container.register_transient(ApiService, ApiService)

    # Resolve complete tree
    api = container.resolve(ApiService)

    assert isinstance(api, ApiService)
    assert isinstance(api.db, DatabaseService)
    assert isinstance(api.db.pool, ConnectionPool)
    assert isinstance(api.logger, LoggerService)

def test_bootstrap_runtime_integrates_with_container() -> None:
    """Test bootstrap runtime correctly initializes container."""

    # Real components
    container = Container()
    plan = BootstrapPlanBuilder.create().with_validation(True).build()
    runtime = BootstrapRuntime()

    # Execute integration
    runtime.bootstrap(container, plan)

    # Verify interaction: metrics recorded
    assert runtime.metrics.total_registrations >= 0
    assert runtime.metrics.preparation_time_ms >= 0

def test_application_launch_workflow() -> None:
    """Test complete application launch workflow.

    Validates: module resolution → config reading → bootstrap → execution
    """

    @application(scan_packages=["test_packages"])
    class TestApp(ApplicationBase):
        executed = False

        def run(self) -> None:
            TestApp.executed = True

    # Setup module
    import sys
    sys.modules["app_module"] = type(sys)("app_module")
    sys.modules["app_module"].TestApp = TestApp

    try:
        # Execute workflow through public API
        ApplicationRuntime.launch("app_module:TestApp")

        # Verify all steps succeeded
        assert TestApp.executed is True
    finally:
        del sys.modules["app_module"]

def test_bootstrap_failure_propagates_through_container() -> None:
    """Test that bootstrap errors are properly propagated.

    When bootstrap fails (e.g., validation error), error should
    propagate through container and be available to caller.
    """

    container = Container()

    # Create plan with validation enabled
    plan = BootstrapPlanBuilder.create().with_validation(True).build()

    # Create runtime that will detect issues
    runtime = BootstrapRuntime()

    # If plan has dependency issues, should raise
    # (Exact behavior depends on plan content)
    try:
        runtime.bootstrap(container, plan)
        # Verify bootstrap completed
    except BootstrapError as e:
        # Verify error is properly propagated
        assert "dependency" in str(e).lower()

def test_singleton_lifecycle_integration() -> None:
    """Test singleton services are created once and reused.

    Verifies the full singleton lifecycle: creation on first resolution,
    reuse on subsequent resolutions, cleanup when container closes.
    """

    class SingletonService:
        instance_count = 0

        def __init__(self) -> None:
            SingletonService.instance_count += 1

    container = Container()
    container.register_singleton(SingletonService, SingletonService)

    # First resolution creates instance
    service1 = container.resolve(SingletonService)
    assert SingletonService.instance_count == 1

    # Second resolution reuses
    service2 = container.resolve(SingletonService)
    assert service1 is service2
    assert SingletonService.instance_count == 1

tests/integration/
├── conftest.py                           # Shared integration fixtures
├── di/
│   ├── test_bootstrap_di_workflow.py     # Bootstrap workflows
│   ├── test_container_integration.py     # Container interactions
│   └── test_di_lifecycle.py              # Service lifecycle
├── reflection/
│   ├── test_reflection_workflow.py       # Reflection workflows
│   └── test_scanning_integration.py      # Package scanning
└── cross_system/
    ├── test_di_reflection_integration.py # DI + Reflection
    └── test_annotation_integration.py    # Annotation processing

test_bootstrap_with_container_integration()
test_di_resolves_transitive_dependencies()
test_application_launch_workflow()
test_reflection_scanning_with_filtering()