quadkit-testing 0.0.41__tar.gz → 0.0.43__tar.gz

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: quadkit-testing
-Version: 0.0.41
+Version: 0.0.43
 Summary: Centralized testing infrastructure for Quadkit Framework - Fixtures, factories, and utilities
 Project-URL: Homepage, https://dbtinoy-.github.io/quadkit/
 Project-URL: Repository, https://github.com/dbtinoy-/quadkit
@@ -234,10 +234,10 @@ vulnerabilities privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/
 
 ## Stability
 
-Version `0.0.3` in the `0.x` series, released in lockstep with the
+Version `0.0.43` in the `0.x` series, released in lockstep with the
 other four distributions; APIs may change between minor versions until
-1.0 — pin an exact version (`quadkit-testing==0.0.3`) or a tight range
-(`>=0.0.3,<0.1.0`). Full policy:
+1.0 — pin an exact version (`quadkit-testing==0.0.43`) or a tight range
+(`>=0.0.43,<0.1.0`). Full policy:
 [stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
 
 ## Links

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/README.md

@@ -178,10 +178,10 @@ vulnerabilities privately per [SECURITY.md](https://github.com/dbtinoy-/quadkit/
 
 ## Stability
 
-Version `0.0.3` in the `0.x` series, released in lockstep with the
+Version `0.0.43` in the `0.x` series, released in lockstep with the
 other four distributions; APIs may change between minor versions until
-1.0 — pin an exact version (`quadkit-testing==0.0.3`) or a tight range
-(`>=0.0.3,<0.1.0`). Full policy:
+1.0 — pin an exact version (`quadkit-testing==0.0.43`) or a tight range
+(`>=0.0.43,<0.1.0`). Full policy:
 [stability and compatibility](https://dbtinoy-.github.io/quadkit/reference/stability/).
 
 ## Links

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "quadkit-testing"
-version = "0.0.41"
+version = "0.0.43"
 description = "Centralized testing infrastructure for Quadkit Framework - Fixtures, factories, and utilities"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -164,6 +164,9 @@ workspace = true
 [tool.uv.sources.quadkit-contracts]
 workspace = true
 
+[tool.uv.sources.quadkit-sql]
+workspace = true
+
 [tool.pytest.ini_options]
 asyncio_mode = "auto"
 addopts = ["--cov=quadkit.testing", "--cov-report=html", "--cov-report=term", "--cov-fail-under=66"]

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/fakes/redis.py

@@ -11,7 +11,7 @@ __all__ = ["FakeRedisClient"]
 class FakeRedisClient:
     """In-memory async client compatible with the ``redis.asyncio`` surface used by tests.
 
-    Supports the subset of Redis commands exercised by the optional provider tests:
+    Supports the subset of Redis commands exercised by quadkit-cache tests:
     ``ping``, ``set`` (with ``ex``/``px``/``nx``/``xx``), ``get``, ``delete``,
     ``exists``, ``expire``, ``ttl``, ``flushdb``, and ``close``.  All data is
     kept in process, so tests never touch the network or a pre-started

quadkit_testing-0.0.43/src/quadkit/testing/fixtures/db.py

@@ -0,0 +1,279 @@
+"""Database-specific test fixtures"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator
+from typing import Any
+from unittest.mock import AsyncMock, Mock
+
+import pytest
+
+pytest_asyncio: Any | None = None
+try:
+    import pytest_asyncio
+except ImportError:
+    pytest_asyncio = None
+
+from collections.abc import Callable
+from typing import Any as _Any
+
+# Explicitly type the chosen fixture decorator so mypy treats decorated functions as typed
+fixture_decorator: Callable[..., _Any] = (
+    pytest.fixture if pytest_asyncio is None else pytest_asyncio.fixture
+)
+
+try:
+    from quadkit.sql.abstractions.connection import (  # type: ignore[attr-defined]
+        ConnectionPool,
+        DatabaseConnection,
+    )
+except ImportError:
+    # Fallback if quadkit-sql is not available
+    ConnectionPool: Any = Any  # type: ignore[no-redef]
+    DatabaseConnection: Any = Any  # type: ignore[no-redef]
+from quadkit.testing.clients.db import (
+    DatabaseTestBed,
+    DatabaseTestClient,
+)
+
+
+@fixture_decorator
+async def db_test_bed() -> AsyncGenerator[DatabaseTestBed, None]:
+    """Fixture for DatabaseTestBed with automatic cleanup"""
+    test_bed = DatabaseTestBed()
+    async with test_bed as tb:
+        yield tb
+
+
+@fixture_decorator
+async def test_database_client() -> AsyncGenerator[DatabaseTestClient, None]:
+    """Fixture for DatabaseTestClient"""
+    client = DatabaseTestClient()
+    async with client as c:
+        yield c
+
+
+@pytest.fixture
+def mock_connection() -> DatabaseConnection:
+    """Fixture for mock database connection"""
+    mock_conn = Mock(spec=DatabaseConnection)
+
+    # Mock async methods
+    mock_conn.execute = AsyncMock()
+    mock_conn.execute_many = AsyncMock()
+    mock_conn.fetch_one = AsyncMock()
+    mock_conn.fetch_all = AsyncMock()
+    mock_conn.close = AsyncMock()
+
+    # Additional methods expected by tests
+    mock_conn.fetchone = AsyncMock()
+    mock_conn.fetchall = AsyncMock()
+
+    # Mock transaction context manager
+    mock_transaction = AsyncMock()
+    mock_transaction.__aenter__ = AsyncMock(return_value=mock_conn)
+    mock_transaction.__aexit__ = AsyncMock(return_value=None)
+    mock_conn.transaction = Mock(return_value=mock_transaction)
+
+    return mock_conn
+
+
+@pytest.fixture
+def mock_connection_pool() -> ConnectionPool:
+    """Fixture for mock connection pool"""
+    mock_pool = Mock(spec=ConnectionPool)
+
+    # Mock async methods
+    mock_pool.get_connection = AsyncMock()
+    mock_pool.close = AsyncMock()
+    mock_pool.health_check = Mock(return_value={"status": "healthy"})
+    mock_pool.get_stats = Mock(return_value={"connections": 5})
+
+    # Additional methods expected by tests
+    mock_pool.acquire = AsyncMock()
+    mock_pool.release = AsyncMock()
+
+    return mock_pool
+
+
+@fixture_decorator
+async def seeded_database(
+    db_test_bed: DatabaseTestBed,
+    sample_user_data: list[dict[str, Any]],
+    sample_order_data: list[dict[str, Any]],
+    sample_product_data: list[dict[str, Any]],
+) -> DatabaseTestBed:
+    """Fixture for database with sample data"""
+    # Create users table
+    await db_test_bed.create_test_table(
+        "users",
+        "id INTEGER PRIMARY KEY, name TEXT, email TEXT, role TEXT",
+    )
+
+    # Create orders table
+    await db_test_bed.create_test_table(
+        "orders",
+        "id INTEGER PRIMARY KEY, user_id INTEGER, total REAL, status TEXT, items TEXT",
+    )
+
+    # Create products table
+    await db_test_bed.create_test_table(
+        "products",
+        "id INTEGER PRIMARY KEY, name TEXT, price REAL, category TEXT",
+    )
+
+    # Seed sample data
+    await db_test_bed.seed_test_data("users", sample_user_data)
+    await db_test_bed.seed_test_data("orders", sample_order_data)
+    await db_test_bed.seed_test_data("products", sample_product_data)
+
+    return db_test_bed
+
+
+@fixture_decorator
+async def clean_database(db_test_bed: DatabaseTestBed) -> DatabaseTestBed:
+    """Fixture for clean database with tables but no data"""
+    # Create users table
+    await db_test_bed.create_test_table(
+        "users",
+        "id INTEGER PRIMARY KEY, name TEXT NOT NULL, email TEXT",
+    )
+
+    # Create orders table
+    await db_test_bed.create_test_table(
+        "orders",
+        "id INTEGER PRIMARY KEY, user_id INTEGER, total REAL, status TEXT",
+    )
+
+    return db_test_bed
+
+
+@pytest.fixture
+def sample_user_data() -> list[dict[str, Any]]:
+    """Sample user data for testing"""
+    return [
+        {
+            "id": 1,
+            "name": "Alice Johnson",
+            "email": "alice@example.com",
+            "role": "user",
+        },
+        {"id": 2, "name": "Bob Smith", "email": "bob@example.com", "role": "admin"},
+        {
+            "id": 3,
+            "name": "Charlie Brown",
+            "email": "charlie@example.com",
+            "role": "user",
+        },
+    ]
+
+
+@pytest.fixture
+def sample_order_data() -> list[dict[str, Any]]:
+    """Sample order data for testing"""
+    return [
+        {"id": 1, "user_id": 1, "total": 99.99, "status": "completed", "items": 3},
+        {"id": 2, "user_id": 2, "total": 149.50, "status": "pending", "items": 5},
+        {"id": 3, "user_id": 1, "total": 75.25, "status": "shipped", "items": 2},
+    ]
+
+
+@pytest.fixture
+def sample_product_data() -> list[dict[str, Any]]:
+    """Sample product data for testing"""
+    return [
+        {"id": 1, "name": "Widget A", "price": 29.99, "category": "electronics"},
+        {"id": 2, "name": "Widget B", "price": 49.99, "category": "tools"},
+        {"id": 3, "name": "Widget C", "price": 19.99, "category": "accessories"},
+    ]
+
+
+@pytest.fixture
+def database_provider() -> Any:
+    """Placeholder fixture for a real DatabaseProviderProtocol instance.
+
+    Returns ``None`` by default so that ``db_transaction`` skips gracefully
+    in test suites that do not configure a live database.
+
+    Override this in your ``conftest.py`` to connect ``db_transaction`` to
+    the real database provider resolved from the application container::
+
+        from quadkit.contracts.data import DatabaseProviderProtocol
+
+        @pytest.fixture
+        async def database_provider(container: Container):
+            return await container.resolve(DatabaseProviderProtocol)
+
+    Where ``container`` is whatever fixture you use to provide the booted DI
+    container for your integration tests.
+    """
+    return None
+
+
+@fixture_decorator
+async def db_transaction(
+    database_provider: Any,
+) -> AsyncGenerator[Any, None]:
+    """Wrap an integration test in a database transaction that always rolls back.
+
+    Opens a scoped database context, begins a transaction, and yields the
+    active :class:`~quadkit.contracts.data.ConnectionProtocol` so that the
+    test can run queries.  The transaction is *always* rolled back during
+    teardown regardless of test outcome, keeping the database state clean and
+    making tests fully order-independent.
+
+    Requires the ``database_provider`` fixture to be overridden in the test
+    suite's ``conftest.py`` (see :func:`database_provider` for instructions).
+    When ``database_provider`` returns ``None`` (the default), the test is
+    skipped with an informative message.
+
+    Example::
+
+        # conftest.py
+        from quadkit.contracts.data import DatabaseProviderProtocol
+
+        @pytest.fixture
+        async def database_provider(container):
+            return await container.resolve(DatabaseProviderProtocol)
+
+        # test_users.py
+        @pytest.mark.asyncio
+        async def test_create_user(db_transaction) -> None:
+            await db_transaction.execute(
+                "INSERT INTO users(name, email) VALUES($1, $2)",
+                "Alice", "alice@example.com",
+            )
+            row = await db_transaction.fetch_one(
+                "SELECT name FROM users WHERE email = $1", "alice@example.com"
+            )
+            assert row["name"] == "Alice"
+            # No teardown needed — the transaction is automatically rolled back.
+    """
+    if database_provider is None:
+        pytest.skip(
+            "db_transaction requires a 'database_provider' fixture. "
+            "Override it in conftest.py with a real DatabaseProviderProtocol instance."
+        )
+
+    async with database_provider.scoped_context():
+        conn = await database_provider.get_scoped_connection()
+        await conn.execute("BEGIN")
+        try:
+            yield conn
+        finally:
+            await conn.execute("ROLLBACK")
+
+
+__all__ = [
+    "clean_database",
+    "database_provider",
+    "db_test_bed",
+    "db_transaction",
+    "mock_connection",
+    "mock_connection_pool",
+    "sample_order_data",
+    "sample_product_data",
+    "sample_user_data",
+    "seeded_database",
+    "test_database_client",
+]

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/generators_contract.py

@@ -8,6 +8,30 @@ from pathlib import Path
 from typing import Any
 
 
+def _assert_marker_convention(py_path: Path, text: str) -> None:
+    """Enforce the generated-stub marker convention on one rendered ``.py``.
+
+    Generated stubs pair ``# @INTENT: <goal>`` directly above ``# @TODO:
+    <action>`` and never ship a bare ``# TODO:`` (the ``@`` prefix keeps both
+    greppable). See ``docs/09-27-2026/GENERATED_CODE_MARKERS.md``.
+    """
+    lines = text.splitlines()
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped.startswith("# TODO"):
+            raise AssertionError(
+                f"{py_path}: bare '# TODO' in generated code must be '# @TODO' "
+                f"-> {line!r}"
+            )
+        if stripped.startswith("# @TODO:"):
+            prev = lines[i - 1].strip() if i > 0 else ""
+            if not prev.startswith("# @INTENT:"):
+                raise AssertionError(
+                    f"{py_path}: '# @TODO' at line {i + 1} is not preceded by "
+                    f"a '# @INTENT:' line (found {prev!r})"
+                )
+
+
 def assert_contributor_generators_render(
     contributor: Any,
     *,
@@ -77,6 +101,15 @@ def assert_contributor_generators_render(
             f"(created={len(created)}, overwritten={len(overwritten)}, "
             f"staged={len(staged)})"
         )
+
+        # Every rendered Python stub must follow the @INTENT/@TODO marker
+        # convention — a single gate so a new generator (or a template at a
+        # deeper package nesting) cannot reintroduce a bare ``# TODO``.
+        for py_file in out.rglob("*.py"):
+            if "__pycache__" in py_file.parts:
+                continue
+            _assert_marker_convention(py_file, py_file.read_text(encoding="utf-8"))
+
         exercised += 1
     return exercised
 

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/integration/probes.py

@@ -51,7 +51,7 @@ class ServiceProbe:
             await client.close()
             return True
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="redis", url=url, error=str(e))
+            logger.debug("probe_failed", dependency="redis", url=url, error=str(e))
             return False
 
     @staticmethod
@@ -66,7 +66,7 @@ class ServiceProbe:
             await conn.close()
             return True
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="postgres", dsn=dsn, error=str(e))
+            logger.debug("probe_failed", dependency="postgres", dsn=dsn, error=str(e))
             return False
 
     @staticmethod
@@ -79,7 +79,9 @@ class ServiceProbe:
                 response = await client.get(url)
                 return response.status_code == 200
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="elasticsearch", url=url, error=str(e))
+            logger.debug(
+                "probe_failed", dependency="elasticsearch", url=url, error=str(e)
+            )
             return False
 
     @staticmethod
@@ -94,7 +96,7 @@ class ServiceProbe:
             await connection.close()
             return True
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="rabbitmq", url=url, error=str(e))
+            logger.debug("probe_failed", dependency="rabbitmq", url=url, error=str(e))
             return False
 
     @staticmethod
@@ -107,7 +109,9 @@ class ServiceProbe:
                 response = await client.get(f"{url}/health")
                 return response.status_code == 200
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="meilisearch", url=url, error=str(e))
+            logger.debug(
+                "probe_failed", dependency="meilisearch", url=url, error=str(e)
+            )
             return False
 
     @staticmethod
@@ -125,7 +129,7 @@ class ServiceProbe:
             return True
         except Exception as e:  # noqa: BLE001
             logger.debug(
-                "probe_failed", service="smtp", host=host, port=port, error=str(e)
+                "probe_failed", dependency="smtp", host=host, port=port, error=str(e)
             )
             return False
 
@@ -152,7 +156,7 @@ class ServiceProbe:
             return True
         except Exception as e:  # noqa: BLE001
             logger.debug(
-                "probe_failed", service="kafka", bootstrap=bootstrap, error=str(e)
+                "probe_failed", dependency="kafka", bootstrap=bootstrap, error=str(e)
             )
             return False
 
@@ -179,7 +183,7 @@ class ServiceProbe:
             return True
         except Exception as e:  # noqa: BLE001
             logger.debug(
-                "probe_failed", service="minio", endpoint=endpoint, error=str(e)
+                "probe_failed", dependency="minio", endpoint=endpoint, error=str(e)
             )
             return False
 
@@ -207,7 +211,7 @@ class ServiceProbe:
             await writer.wait_closed()
             return True
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="mongodb", dsn=dsn, error=str(e))
+            logger.debug("probe_failed", dependency="mongodb", dsn=dsn, error=str(e))
             return False
 
     @staticmethod
@@ -234,7 +238,7 @@ class ServiceProbe:
             await writer.wait_closed()
             return True
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="qdrant", url=url, error=str(e))
+            logger.debug("probe_failed", dependency="qdrant", url=url, error=str(e))
             return False
 
     @staticmethod
@@ -261,5 +265,5 @@ class ServiceProbe:
             await writer.wait_closed()
             return True
         except Exception as e:  # noqa: BLE001
-            logger.debug("probe_failed", service="neo4j", url=url, error=str(e))
+            logger.debug("probe_failed", dependency="neo4j", url=url, error=str(e))
             return False

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/memory/cqrs.py

@@ -2,7 +2,7 @@
 
 Provides minimal in-memory CQRS dispatch for unit tests and local development.
 For production use with middleware pipelines, metrics, and transaction support,
-use the ``the optional provider`` extension.
+use the ``quadkit-events`` extension.
 
 Example::
 

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/memory/event_bus.py

@@ -18,7 +18,7 @@ from quadkit.contracts.events import EventBusProtocol as EventBusProtocol
 from quadkit.contracts.events import EventHandlerProtocol
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Awaitable, Callable
 
     from quadkit.contracts.core import MiddlewarePipelineProtocol
     from quadkit.contracts.domain.events import DomainEvent
@@ -76,11 +76,14 @@ class InMemoryEventBus(EventBusProtocol):
                 the originating request context.
         """
         # handlers stored as (priority, handler) tuples, sorted by priority
-        self._handlers: dict[type | str, list[tuple[int, EventHandlerProtocol]]] = (
-            defaultdict(list)
-        )
+        self._handlers: dict[
+            type | str,
+            list[tuple[int, EventHandlerProtocol | Callable[..., Awaitable[Any]]]],
+        ] = defaultdict(list)
         # wildcard subscriptions receive every published event regardless of type
-        self._wildcard_handlers: list[tuple[int, EventHandlerProtocol]] = []
+        self._wildcard_handlers: list[
+            tuple[int, EventHandlerProtocol | Callable[..., Awaitable[Any]]]
+        ] = []
         from quadkit.app.pipeline import (
             MiddlewarePipeline as _MiddlewarePipeline,
         )
@@ -98,7 +101,7 @@ class InMemoryEventBus(EventBusProtocol):
     def subscribe(
         self,
         event_type: type | str,
-        handler: EventHandlerProtocol,
+        handler: EventHandlerProtocol | Callable[..., Awaitable[Any]],
         *,
         priority: int = 0,
     ) -> None:
@@ -121,7 +124,9 @@ class InMemoryEventBus(EventBusProtocol):
             self._handlers[event_type].sort(key=lambda entry: entry[0])
 
     def unsubscribe(
-        self, event_type: type | str, handler: EventHandlerProtocol
+        self,
+        event_type: type | str,
+        handler: EventHandlerProtocol | Callable[..., Awaitable[Any]],
     ) -> None:
         """Remove a previously registered handler for an event type.
 
@@ -141,6 +146,15 @@ class InMemoryEventBus(EventBusProtocol):
             return
         self._handlers[event_type] = [(p, h) for p, h in handlers if h is not handler]
 
+    async def flush(self) -> None:
+        """Wait until all pending events have been dispatched.
+
+        A no-op here: ``publish`` awaits every handler before it returns, so
+        this engine never has an in-flight dispatch to drain. The member
+        exists because ``EventBusProtocol`` declares it — the flagship bus
+        dispatches in the background and does need it.
+        """
+
     def add_middleware(self, middleware: Any) -> None:
         """Add a middleware function to the event processing chain.
 

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/memory/outbox.py

@@ -2,7 +2,7 @@
 
 Provides an in-memory Outbox for testing and local development.
 For production with database persistence, use the OutboxEventStore
-from the the optional provider extension.
+from the quadkit-events extension.
 
 The Outbox pattern ensures events are stored in the same transaction
 as business data, then relayed asynchronously for publishing.

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/memory/repository.py

@@ -3,7 +3,7 @@
 Provides a generic, async-safe in-memory implementation of the RepositoryProtocol
 pattern backed by :class:`~quadkit.data.repository.base.AbstractRepository`.
 Intended as a zero-infrastructure drop-in for unit tests and local development.
-For production, replace with ``the optional provider``'s SQLRepository or a
+For production, replace with ``quadkit-sql``'s SQLRepository or a
 domain-specific storage backend.
 """
 
@@ -26,7 +26,7 @@ class InMemoryRepository(AbstractRepository[T, Any], Generic[T]):
     This class lives in ``quadkit-testing`` intentionally — it is not exported
     from ``quadkit`` core.  Production code should depend on the
     ``RepositoryProtocol`` protocol from ``quadkit.contracts.data`` and receive a
-    concrete implementation (e.g. ``SQLRepository`` from ``the optional provider``)
+    concrete implementation (e.g. ``SQLRepository`` from ``quadkit-sql``)
     via dependency injection.
 
     Stores entities in a plain dict keyed by their identity attribute.
@@ -36,7 +36,7 @@ class InMemoryRepository(AbstractRepository[T, Any], Generic[T]):
 
     Extends :class:`~quadkit.data.repository.base.AbstractRepository` and
     implements all required primitives.  For production persistence, use
-    ``the optional provider``'s ``SQLRepository`` or any other storage backend.
+    ``quadkit-sql``'s ``SQLRepository`` or any other storage backend.
 
     Args:
         id_attr: Name of the entity attribute that holds the primary key.

{quadkit_testing-0.0.41 → quadkit_testing-0.0.43}/src/quadkit/testing/memory/uow.py

@@ -6,7 +6,7 @@ Provides a concrete :class:`InMemoryUnitOfWork` that extends
 database persistence is required.
 
 For production, use a backend that overrides :meth:`_flush` to write to a
-database (e.g. ``the optional provider``'s ``SQLUnitOfWork``).
+database (e.g. ``quadkit-sql``'s ``SQLUnitOfWork``).
 """
 
 from __future__ import annotations