kernia-test-utils 0.1.0__tar.gz

kernia_test_utils-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+.uv/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Docs build output
+/site/
+docs/site/
+
+# Internal tooling (not part of the public repo)
+scripts/audit_layout.py
+scripts/setup_kernia_dns.sh
+spec/
+
+# Local
+
+.projects/cache
+.projects/vault
+.projects/state.test.json
+.projects/state.local.test.json
+.env
+.env.local
+.env.test

kernia_test_utils-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Advantch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

kernia_test_utils-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: kernia-test-utils
+Version: 0.1.0
+Summary: Shared test utilities for Kernia
+Project-URL: Homepage, https://kernia.dev
+Project-URL: Documentation, https://kernia.dev/docs
+Project-URL: Source, https://github.com/advantch/kernia
+Project-URL: Issues, https://github.com/advantch/kernia/issues
+Project-URL: Changelog, https://github.com/advantch/kernia/releases
+Author: Advantch
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asgi,authentication,authorization,django,fastapi,oauth,passkeys,security,sessions,sso,starlette
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: WWW/HTTP :: Session
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: cbor2>=5
+Requires-Dist: cryptography>=42
+Requires-Dist: httpx>=0.27
+Requires-Dist: kernia>=0.1.0
+Requires-Dist: lxml>=5
+Requires-Dist: webauthn>=2.7
+Provides-Extra: pytest
+Requires-Dist: pytest>=8; extra == 'pytest'
+Provides-Extra: testcontainers
+Requires-Dist: testcontainers>=4; extra == 'testcontainers'
+Description-Content-Type: text/markdown
+
+# kernia-test-utils
+
+Shared test utilities for Kernia: an ASGI driver, mock OIDC/SAML identity providers, SMTP/SMS capture, a Stripe REST mock, a software WebAuthn authenticator, and lazy testcontainers fixtures.
+
+Part of [Kernia](https://kernia.dev), a framework-agnostic authentication library for Python.
+
+## Installation
+
+    pip install kernia-test-utils
+
+## Usage
+
+```python
+from kernia_test_utils import ASGIDriver, MockSMTP
+
+# Drive an ASGI app like an HTTP client, no server needed.
+driver = ASGIDriver(app=auth.router.mount())
+response = await driver.post("/api/auth/sign-up/email", json={
+    "email": "user@example.com",
+    "password": "correct-horse",
+    "name": "User",
+})
+
+# Capture outgoing email in tests.
+smtp = MockSMTP()
+```
+
+Also provides `MockIdP`, `MockSAMLIdP`, `MockStripe`, `MockSMS`, `SoftAuthenticator`, and container fixtures behind `requires_docker`.
+
+## Documentation
+
+Full documentation at [kernia.dev/docs](https://kernia.dev/docs). Source at [github.com/advantch/kernia](https://github.com/advantch/kernia).
+
+## License
+
+MIT

kernia_test_utils-0.1.0/README.md

@@ -0,0 +1,36 @@
+# kernia-test-utils
+
+Shared test utilities for Kernia: an ASGI driver, mock OIDC/SAML identity providers, SMTP/SMS capture, a Stripe REST mock, a software WebAuthn authenticator, and lazy testcontainers fixtures.
+
+Part of [Kernia](https://kernia.dev), a framework-agnostic authentication library for Python.
+
+## Installation
+
+    pip install kernia-test-utils
+
+## Usage
+
+```python
+from kernia_test_utils import ASGIDriver, MockSMTP
+
+# Drive an ASGI app like an HTTP client, no server needed.
+driver = ASGIDriver(app=auth.router.mount())
+response = await driver.post("/api/auth/sign-up/email", json={
+    "email": "user@example.com",
+    "password": "correct-horse",
+    "name": "User",
+})
+
+# Capture outgoing email in tests.
+smtp = MockSMTP()
+```
+
+Also provides `MockIdP`, `MockSAMLIdP`, `MockStripe`, `MockSMS`, `SoftAuthenticator`, and container fixtures behind `requires_docker`.
+
+## Documentation
+
+Full documentation at [kernia.dev/docs](https://kernia.dev/docs). Source at [github.com/advantch/kernia](https://github.com/advantch/kernia).
+
+## License
+
+MIT

kernia_test_utils-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "kernia-test-utils"
+version = "0.1.0"
+description = "Shared test utilities for Kernia"
+requires-python = ">=3.11"
+dependencies = [
+    "kernia>=0.1.0",
+    "cryptography>=42",
+    "httpx>=0.27",
+    "cbor2>=5",
+    "webauthn>=2.7",
+    "lxml>=5",
+]
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+]
+authors = [
+    {name = "Advantch"},
+]
+keywords = [
+    "authentication",
+    "authorization",
+    "sessions",
+    "oauth",
+    "passkeys",
+    "sso",
+    "asgi",
+    "fastapi",
+    "starlette",
+    "django",
+    "security",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP :: Session",
+    "Topic :: Security",
+    "Typing :: Typed",
+]
+
+[project.optional-dependencies]
+testcontainers = ["testcontainers>=4"]
+pytest = ["pytest>=8"]
+
+[project.urls]
+Homepage = "https://kernia.dev"
+Documentation = "https://kernia.dev/docs"
+Source = "https://github.com/advantch/kernia"
+Issues = "https://github.com/advantch/kernia/issues"
+Changelog = "https://github.com/advantch/kernia/releases"
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kernia_test_utils"]

kernia_test_utils-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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",
+]