kernia-test-utils 0.1.0__py3-none-any.whl

kernia_test_utils/__init__.py

@@ -0,0 +1,56 @@
+"""Shared test fixtures.
+
+Mirrors `reference/packages/test-utils/`. Exposes:
+
+    * `ASGIDriver` / `ASGIResponse` — call an ASGI app like a client.
+    * `MockIdP` — in-process OIDC IdP with signed id_tokens.
+    * `MockSMTP` / `SentEmail` — capture outgoing emails.
+    * `MockSMS` / `SentSMS` — capture outgoing SMS.
+    * `MockStripe` — Stripe REST mock + signed-webhook helper.
+    * `MockSAMLIdP` — minimal signed SAML 2.0 IdP fixture.
+    * Container helpers — lazy testcontainers fixtures behind `requires_docker`.
+    * `all_adapters_param` — pytest parametrize value covering every backend.
+"""
+
+from kernia_test_utils.adapter_fixtures import (
+    AdapterFactory,
+    adapter_cleanup,
+    all_adapters_param,
+)
+from kernia_test_utils.asgi_driver import ASGIDriver, ASGIResponse
+from kernia_test_utils.containers import (
+    docker_available,
+    mongodb_container,
+    mysql_container,
+    postgres_container,
+    redis_container,
+    requires_docker,
+)
+from kernia_test_utils.mock_idp import MockIdP
+from kernia_test_utils.mock_saml_idp import MockSAMLIdP
+from kernia_test_utils.mock_sms import MockSMS, SentSMS
+from kernia_test_utils.mock_smtp import MockSMTP, SentEmail
+from kernia_test_utils.mock_stripe import MockStripe
+from kernia_test_utils.soft_webauthn import SoftAuthenticator
+
+__all__ = [
+    "ASGIDriver",
+    "ASGIResponse",
+    "AdapterFactory",
+    "MockIdP",
+    "MockSAMLIdP",
+    "MockSMS",
+    "MockSMTP",
+    "MockStripe",
+    "SentEmail",
+    "SentSMS",
+    "SoftAuthenticator",
+    "adapter_cleanup",
+    "all_adapters_param",
+    "docker_available",
+    "mongodb_container",
+    "mysql_container",
+    "postgres_container",
+    "redis_container",
+    "requires_docker",
+]

kernia_test_utils/adapter_fixtures.py

@@ -0,0 +1,143 @@
+"""Cross-adapter parametrization helper.
+
+Plugin integration tests do:
+
+    @pytest.mark.parametrize(*all_adapters_param())
+    async def test_thing(adapter_factory):
+        adapter = await adapter_factory()
+        ...
+
+The factory returns a fresh adapter with a fresh DB. Schema is created
+per-test; for SQLAlchemy the engine is disposed after the test runs.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+import pytest
+
+from kernia_test_utils.containers import docker_available, postgres_container
+
+AdapterFactory = Callable[[], Awaitable[Any]]
+
+
+async def _memory_factory() -> Any:
+    from kernia_memory_adapter import memory_adapter
+
+    return memory_adapter()
+
+
+async def _sqlite_factory() -> Any:
+    # Each call gets its own in-memory database — they're isolated even when
+    # several tests run concurrently because the URL contains a fresh secret.
+    import secrets
+
+    from kernia_sqlalchemy import sqlalchemy_adapter
+
+    url = f"sqlite+aiosqlite:///file:{secrets.token_hex(8)}?mode=memory&cache=shared&uri=true"
+    return await sqlalchemy_adapter(url=url)
+
+
+def _postgres_url_factory() -> Callable[[], Awaitable[Any]]:
+    """Return an adapter-factory bound to a single Postgres container.
+
+    The container is started lazily on first use and stopped via an atexit
+    handler. Each adapter call gets a fresh database name on that container.
+    """
+    state: dict[str, Any] = {}
+
+    async def factory() -> Any:
+        from kernia_sqlalchemy import sqlalchemy_adapter
+
+        if "url" not in state:
+            import atexit
+
+            ctx = postgres_container()
+            url = ctx.__enter__()
+            state["ctx"] = ctx
+            state["url"] = url
+            atexit.register(lambda: ctx.__exit__(None, None, None))
+        # NOTE: tests share the same database; rely on per-test transactional
+        # rollback at the adapter layer. For now we just hand out adapters
+        # against the shared URL — schema is idempotent (CREATE IF NOT EXISTS).
+        return await sqlalchemy_adapter(url=state["url"])
+
+    return factory
+
+
+def all_adapters_param() -> tuple[str, list[Any]]:
+    """Return `("adapter_factory", [...])` for pytest.mark.parametrize.
+
+    Each entry is a `pytest.param(factory, id=..., marks=...)`. Containers
+    that need Docker are wrapped in `pytest.mark.skipif` when Docker is
+    unavailable.
+    """
+    has_docker = docker_available()
+
+    return (
+        "adapter_factory",
+        [
+            pytest.param(_memory_factory, id="memory"),
+            pytest.param(_sqlite_factory, id="sqlalchemy-sqlite"),
+            pytest.param(
+                _postgres_url_factory(),
+                id="sqlalchemy-postgres",
+                marks=pytest.mark.skipif(not has_docker, reason="Docker required"),
+            ),
+            pytest.param(
+                _mongo_url_factory(),
+                id="mongo",
+                marks=pytest.mark.skipif(not has_docker, reason="Docker required for mongo"),
+            ),
+        ],
+    )
+
+
+def _mongo_url_factory() -> Callable[[], Awaitable[Any]]:
+    """Return an adapter-factory bound to a single MongoDB container.
+
+    Mirrors `_postgres_url_factory`: the container starts lazily on first use
+    and is stopped via an atexit handler, so it outlives each test body (a
+    `with` block here would tear the container down before the test runs).
+    Each call gets a fresh database name on the shared container, keeping
+    parametrized tests isolated.
+    """
+    state: dict[str, Any] = {}
+
+    async def factory() -> Any:
+        try:
+            from kernia_mongo import mongo_adapter
+        except ImportError:
+            pytest.skip("kernia_mongo is not installed")
+
+        if "url" not in state:
+            import atexit
+
+            from kernia_test_utils.containers import mongodb_container
+
+            ctx = mongodb_container()
+            state["ctx"] = ctx
+            state["url"] = ctx.__enter__()
+            atexit.register(lambda: ctx.__exit__(None, None, None))
+
+        import secrets
+
+        return await mongo_adapter(url=state["url"], db_name=f"kernia_test_{secrets.token_hex(4)}")
+
+    return factory
+
+
+@pytest.fixture(autouse=False)
+async def adapter_cleanup() -> Any:
+    """Per-test cleanup hook.
+
+    Tests that use the parametrized factory can opt in by adding this fixture.
+    It currently just yields — adapter teardown is the factory's
+    responsibility — but it's the seam where future global cleanup will live.
+    """
+    return
+
+
+__all__ = ["AdapterFactory", "adapter_cleanup", "all_adapters_param"]

kernia_test_utils/asgi_driver.py

@@ -0,0 +1,107 @@
+"""ASGIDriver — calls an ASGI app like a client without a real server.
+
+Maintains a cookie jar between calls so tests can chain sign-up → get-session.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Awaitable, Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ASGIResponse:
+    status: int
+    headers: tuple[tuple[str, str], ...]
+    body: bytes
+
+    def json(self) -> Any:
+        if not self.body:
+            return None
+        return json.loads(self.body.decode("utf-8"))
+
+    def set_cookies(self) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for k, v in self.headers:
+            if k.lower() != "set-cookie":
+                continue
+            name, _, rest = v.partition("=")
+            value, _, _attrs = rest.partition(";")
+            out[name.strip()] = value
+        return out
+
+
+@dataclass
+class ASGIDriver:
+    app: Callable[..., Awaitable[None]]
+    cookies: dict[str, str] = field(default_factory=dict)
+
+    async def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: Any = None,
+        headers: Mapping[str, str] | None = None,
+        query: str = "",
+    ) -> ASGIResponse:
+        body_bytes = b""
+        req_headers: list[tuple[bytes, bytes]] = []
+        for k, v in (headers or {}).items():
+            req_headers.append((k.lower().encode("latin-1"), v.encode("latin-1")))
+        if json_body is not None:
+            body_bytes = json.dumps(json_body).encode("utf-8")
+            if not any(k == b"content-type" for k, _ in req_headers):
+                req_headers.append((b"content-type", b"application/json"))
+        if self.cookies:
+            cookie_header = "; ".join(f"{k}={v}" for k, v in self.cookies.items())
+            req_headers.append((b"cookie", cookie_header.encode("latin-1")))
+
+        scope = {
+            "type": "http",
+            "method": method,
+            "path": path,
+            "query_string": query.encode("utf-8"),
+            "headers": req_headers,
+        }
+
+        sent_body = b""
+        more = True
+
+        async def receive() -> dict:
+            nonlocal more
+            if more:
+                more = False
+                return {"type": "http.request", "body": body_bytes, "more_body": False}
+            return {"type": "http.disconnect"}
+
+        captured: dict[str, Any] = {"status": None, "headers": [], "body": b""}
+
+        async def send(msg: dict) -> None:
+            nonlocal sent_body
+            if msg["type"] == "http.response.start":
+                captured["status"] = msg["status"]
+                captured["headers"] = msg.get("headers", [])
+            elif msg["type"] == "http.response.body":
+                sent_body += msg.get("body") or b""
+
+        await self.app(scope, receive, send)
+
+        captured["body"] = sent_body
+        decoded_headers = tuple(
+            (k.decode("latin-1"), v.decode("latin-1")) for k, v in captured["headers"]
+        )
+        response = ASGIResponse(
+            status=captured["status"],
+            headers=decoded_headers,
+            body=sent_body,
+        )
+        # Update cookie jar
+        for name, value in response.set_cookies().items():
+            if value:
+                self.cookies[name] = value
+            elif name in self.cookies:
+                del self.cookies[name]
+        return response

kernia_test_utils/containers.py

@@ -0,0 +1,124 @@
+"""Lazy testcontainers fixtures.
+
+Each helper imports `testcontainers` at call-time so the dep stays optional.
+If Docker is not reachable, the call raises an ImportError / RuntimeError; use
+`requires_docker()` to skip cleanly at the test layer.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import shutil
+import subprocess
+from collections.abc import Iterator
+
+import pytest
+
+
+def _testcontainers_installed() -> bool:
+    """True if the optional `testcontainers` package is importable."""
+    import importlib.util
+
+    return importlib.util.find_spec("testcontainers") is not None
+
+
+def docker_available() -> bool:
+    """Best-effort check that container-backed tests can actually run.
+
+    Requires BOTH a reachable Docker daemon AND the `testcontainers` package.
+    If either is missing, the gated suites skip cleanly instead of erroring —
+    a Docker daemon with no `testcontainers` install is a common local setup.
+    """
+    if not _testcontainers_installed():
+        return False
+    if shutil.which("docker") is None:
+        return False
+    try:
+        result = subprocess.run(
+            ["docker", "info"],
+            check=False,
+            capture_output=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+    return result.returncode == 0
+
+
+def requires_docker() -> pytest.MarkDecorator:
+    """Return a pytest mark that skips when Docker isn't reachable."""
+    return pytest.mark.skipif(not docker_available(), reason="Docker is not available on this host")
+
+
+@contextlib.contextmanager
+def postgres_container(image: str = "postgres:16-alpine") -> Iterator[str]:
+    """Yield a Postgres connection URL (asyncpg-compatible)."""
+    try:
+        from testcontainers.postgres import PostgresContainer  # type: ignore[import-not-found]
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError("testcontainers extra is not installed") from e
+    container = PostgresContainer(image)
+    container.start()
+    try:
+        # Convert default psycopg2 URL to asyncpg-friendly form.
+        url = container.get_connection_url().replace(
+            "postgresql+psycopg2://", "postgresql+asyncpg://"
+        )
+        yield url
+    finally:
+        container.stop()
+
+
+@contextlib.contextmanager
+def mysql_container(image: str = "mysql:8") -> Iterator[str]:
+    try:
+        from testcontainers.mysql import MySqlContainer  # type: ignore[import-not-found]
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError("testcontainers extra is not installed") from e
+    container = MySqlContainer(image)
+    container.start()
+    try:
+        url = container.get_connection_url().replace("mysql+pymysql://", "mysql+aiomysql://")
+        yield url
+    finally:
+        container.stop()
+
+
+@contextlib.contextmanager
+def mongodb_container(image: str = "mongo:7") -> Iterator[str]:
+    try:
+        from testcontainers.mongodb import MongoDbContainer  # type: ignore[import-not-found]
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError("testcontainers extra is not installed") from e
+    container = MongoDbContainer(image)
+    container.start()
+    try:
+        yield container.get_connection_url()
+    finally:
+        container.stop()
+
+
+@contextlib.contextmanager
+def redis_container(image: str = "redis:7-alpine") -> Iterator[str]:
+    try:
+        from testcontainers.redis import RedisContainer  # type: ignore[import-not-found]
+    except ImportError as e:  # pragma: no cover
+        raise RuntimeError("testcontainers extra is not installed") from e
+    container = RedisContainer(image)
+    container.start()
+    try:
+        host = container.get_container_host_ip()
+        port = container.get_exposed_port(6379)
+        yield f"redis://{host}:{port}/0"
+    finally:
+        container.stop()
+
+
+__all__ = [
+    "docker_available",
+    "mongodb_container",
+    "mysql_container",
+    "postgres_container",
+    "redis_container",
+    "requires_docker",
+]

kernia_test_utils/mock_idp.py

@@ -0,0 +1,191 @@
+"""In-process OIDC IdP for OAuth/OIDC tests.
+
+Generates an RSA keypair (via `cryptography`), signs id_tokens, and serves a
+JWKS / discovery / token / userinfo surface via `httpx.MockTransport`. Tests can
+plug the transport into an `httpx.AsyncClient` and exercise the full OIDC
+authorization-code flow without a live IdP.
+
+Mirrors what real providers (Google, Microsoft, Apple) expose so the core
+`oauth2.verify_id_token` path is exercised end-to-end.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import secrets
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import padding, rsa
+
+
+def _b64url(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode("ascii")
+
+
+def _b64url_int(i: int) -> str:
+    length = (i.bit_length() + 7) // 8 or 1
+    return _b64url(i.to_bytes(length, "big"))
+
+
+@dataclass(slots=True)
+class _UserProfile:
+    sub: str
+    email: str | None = None
+    name: str | None = None
+    extra: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class MockIdP:
+    """In-memory OpenID Connect provider for tests.
+
+    Usage:
+        idp = MockIdP(issuer="https://test-idp", audience="client-1")
+        idp.create_user(sub="u1", email="a@b.c", name="A")
+        transport = idp.mock_transport()
+        async with httpx.AsyncClient(transport=transport) as client:
+            ...
+    """
+
+    issuer: str = "https://test-idp"
+    audience: str = "client-1"
+    kid: str = "test-key-1"
+    token_ttl: int = 3600
+
+    _key: rsa.RSAPrivateKey = field(init=False)
+    _queue: deque[_UserProfile] = field(init=False, default_factory=deque)
+    _access_tokens: dict[str, _UserProfile] = field(init=False, default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
+
+    # ----- public API -----
+
+    @property
+    def jwks(self) -> dict[str, Any]:
+        pub = self._key.public_key().public_numbers()
+        return {
+            "keys": [
+                {
+                    "kid": self.kid,
+                    "kty": "RSA",
+                    "alg": "RS256",
+                    "use": "sig",
+                    "n": _b64url_int(pub.n),
+                    "e": _b64url_int(pub.e),
+                }
+            ]
+        }
+
+    @property
+    def discovery(self) -> dict[str, Any]:
+        return {
+            "issuer": self.issuer,
+            "authorization_endpoint": f"{self.issuer}/authorize",
+            "token_endpoint": f"{self.issuer}/token",
+            "userinfo_endpoint": f"{self.issuer}/userinfo",
+            "jwks_uri": f"{self.issuer}/.well-known/jwks.json",
+            "response_types_supported": ["code"],
+            "subject_types_supported": ["public"],
+            "id_token_signing_alg_values_supported": ["RS256"],
+        }
+
+    def create_user(
+        self,
+        sub: str,
+        email: str | None = None,
+        name: str | None = None,
+        **extra: Any,
+    ) -> None:
+        """Enqueue a profile for the next sign-in (token exchange)."""
+        self._queue.append(_UserProfile(sub=sub, email=email, name=name, extra=dict(extra)))
+
+    def id_token_for(self, sub: str, **claims: Any) -> str:
+        """Return a signed id_token for direct verification tests."""
+        now = int(time.time())
+        payload: dict[str, Any] = {
+            "iss": self.issuer,
+            "aud": self.audience,
+            "sub": sub,
+            "iat": now,
+            "exp": now + self.token_ttl,
+        }
+        payload.update(claims)
+        return self._sign_jwt(payload)
+
+    def mock_transport(self) -> httpx.MockTransport:
+        return httpx.MockTransport(self._handle)
+
+    # ----- internals -----
+
+    def _sign_jwt(self, claims: dict[str, Any]) -> str:
+        header = {"alg": "RS256", "kid": self.kid, "typ": "JWT"}
+        signing_input = (
+            _b64url(json.dumps(header, separators=(",", ":")).encode())
+            + "."
+            + _b64url(json.dumps(claims, separators=(",", ":")).encode())
+        )
+        sig = self._key.sign(
+            signing_input.encode("ascii"),
+            padding.PKCS1v15(),
+            hashes.SHA256(),
+        )
+        return signing_input + "." + _b64url(sig)
+
+    def _next_profile(self) -> _UserProfile:
+        if self._queue:
+            return self._queue.popleft()
+        # Fallback so the IdP never errors out — tests that don't pre-enqueue
+        # still get a deterministic profile.
+        return _UserProfile(sub="anonymous", email="anonymous@test", name="anonymous")
+
+    def _claims_for(self, profile: _UserProfile) -> dict[str, Any]:
+        claims: dict[str, Any] = {"sub": profile.sub}
+        if profile.email is not None:
+            claims["email"] = profile.email
+            claims["email_verified"] = True
+        if profile.name is not None:
+            claims["name"] = profile.name
+        claims.update(profile.extra)
+        return claims
+
+    def _handle(self, request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if path.endswith("/.well-known/jwks.json"):
+            return httpx.Response(200, json=self.jwks)
+        if path.endswith("/.well-known/openid-configuration"):
+            return httpx.Response(200, json=self.discovery)
+        if path.endswith("/token") and request.method == "POST":
+            profile = self._next_profile()
+            access_token = "at_" + secrets.token_urlsafe(16)
+            self._access_tokens[access_token] = profile
+            extra_claims = self._claims_for(profile)
+            extra_claims.pop("sub", None)
+            id_token = self.id_token_for(profile.sub, **extra_claims)
+            return httpx.Response(
+                200,
+                json={
+                    "access_token": access_token,
+                    "token_type": "Bearer",
+                    "expires_in": self.token_ttl,
+                    "id_token": id_token,
+                    "scope": "openid email profile",
+                },
+            )
+        if path.endswith("/userinfo"):
+            auth = request.headers.get("authorization", "")
+            token = auth.removeprefix("Bearer ").strip()
+            profile = self._access_tokens.get(token)
+            if profile is None:
+                return httpx.Response(401, json={"error": "invalid_token"})
+            return httpx.Response(200, json=self._claims_for(profile))
+        return httpx.Response(404, json={"error": "not_found", "path": path})
+
+
+__all__ = ["MockIdP"]