Add pytest foundation with Testcontainers and reusable fixtures

backend/app/schemas/response.py

@@ -53,8 +53,8 @@ class ErrorResponse(BaseModel):
         description="Error information containing code, message, http_status, details, and request_id",
     )
 
-    class Config:
-        json_schema_extra = {
+    model_config = {
+        "json_schema_extra": {
             "example": {
                 "error": {
                     "code": "VALIDATION_FAILED",
@@ -65,3 +65,4 @@ class Config:
                 }
             }
         }
+    }

backend/pyproject.toml

@@ -18,9 +18,12 @@ dependencies = [
 [dependency-groups]
 dev = [
     "pytest<8.0.0,>=7.4.3",
+    "pytest-asyncio>=0.23.0",
+    "testcontainers[postgres]>=4.0.0",
     "ruff<1.0.0,>=0.2.2",
     "prek>=0.2.24,<1.0.0",
     "coverage<8.0.0,>=7.4.3",
+    "pytest-xdist>=3.5.0,<4.0.0", # tracked in ISSUE-1 (see backend/ISSUE-1.md)
 ]
 
 [build-system]
@@ -29,3 +32,14 @@ build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
 packages = ["app"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = [
+    "unit: Pure unit tests (no external dependencies)",
+    "integration: Integration tests (require database / containers)",
+]
+filterwarnings = [
+    "ignore::DeprecationWarning:pytest_asyncio",
+]

backend/tests/conftest.py

@@ -0,0 +1,159 @@
+"""
+Root conftest - shared fixtures for unit and integration tests.
+
+Key fixtures:
+    postgres_container: Session-scoped Testcontainers PostgreSQL instance.
+    app: FastAPI application wired to the test database.
+    client: httpx.AsyncClient bound to the app.
+    db_session: Per-test psycopg cursor inside a transaction that is
+        rolled back after each test (full isolation).
+"""
+
+from __future__ import annotations
+
+import typing
+from psycopg import Cursor
+
+import logging
+import os
+from collections.abc import Generator
+
+
+import psycopg
+import pytest
+from dotenv import load_dotenv
+from fastapi.testclient import TestClient
+
+
+from testcontainers.postgres import PostgresContainer
+from psycopg import connect
+
+# Load .env before importing app.main to ensure env vars are set
+dotenv_path = os.path.join(os.path.dirname(__file__), "..", ".env")
+load_dotenv(dotenv_path)
+
+# noqa: E402 to allow imports after env setup
+from app.main import app  # noqa: E402
+from app.api.deps import get_db  # noqa: E402
+
+logger = logging.getLogger(__name__)
+
+
+def _make_dsn(container: PostgresContainer) -> str:
+    dsn = container.get_connection_url()
+    # Patch SQLAlchemy/Testcontainers DSN to psycopg3-compatible
+    if dsn.startswith("postgresql+psycopg2://"):
+        dsn = dsn.replace("postgresql+psycopg2://", "postgresql://", 1)
+    return dsn
+
+
+# ---------------------------------------------------------------------------
+# 1. Testcontainers - session-scoped Postgres
+# ---------------------------------------------------------------------------
+@pytest.fixture(scope="session")
+def postgres_container() -> Generator[PostgresContainer, None, None]:
+    """Start a PostgreSQL container once for the entire test session.
+
+    The container is stopped automatically when the session ends.
+
+    Yields:
+        A running PostgresContainer instance.
+    """
+    container = PostgresContainer("postgres:16-alpine")
+    container.start()
+    try:
+        yield container
+    finally:
+        container.stop()
+
+
+# ---------------------------------------------------------------------------
+# 2. Environment variables for the test session
+# ---------------------------------------------------------------------------
+@pytest.fixture(scope="session", autouse=True)
+def _set_test_env(postgres_container: PostgresContainer) -> None:
+    """Override environment variables for the test session.
+
+    Sets connection details so that ``app.core.config.Settings`` picks up
+    the Testcontainers Postgres instance instead of a real database.
+
+    Args:
+        postgres_container: The running Testcontainers Postgres instance.
+    """
+    os.environ["POSTGRES_SERVER"] = postgres_container.get_container_host_ip()
+    os.environ["POSTGRES_PORT"] = str(postgres_container.get_exposed_port(5432))
+    os.environ["POSTGRES_USER"] = postgres_container.username
+    os.environ["POSTGRES_PASSWORD"] = postgres_container.password
+    os.environ["POSTGRES_DB"] = postgres_container.dbname
+    os.environ["SECRET_KEY"] = "test-secret-key-for-testing-only"
+    os.environ["PROJECT_NAME"] = "permit-test"
+
+
+# ---------------------------------------------------------------------------
+# 3. Run migrations against the container
+# ---------------------------------------------------------------------------
+@pytest.fixture(scope="session", autouse=True)
+def _run_migrations(
+    postgres_container: PostgresContainer,
+    _set_test_env: None,  # ensure env is set first
+) -> None:
+    """Apply SQL migration files from the ``migrations/`` directory.
+
+    Reads every ``.sql`` file in alphabetical order and executes it
+    against the Testcontainers Postgres instance.
+
+    Args:
+        postgres_container: The running Testcontainers Postgres instance.
+        _set_test_env: Ensures environment variables are configured first.
+    """
+    import pathlib
+
+    migrations_dir = (
+        pathlib.Path(__file__).resolve().parent.parent.parent / "migrations"
+    )
+    if not migrations_dir.exists():
+        pytest.fail(
+            f"Migrations directory not found: {migrations_dir}. "
+            "Tests require migration SQL files to set up the database schema."
+        )
+
+    dsn = _make_dsn(postgres_container)
+    with psycopg.connect(dsn) as conn:
+        conn.autocommit = True
+        for sql_file in sorted(migrations_dir.glob("*.sql")):
+            conn.execute(sql_file.read_text())
+
+
+# Reuse the session-scoped postgres_container for override_get_db
+
+
+@pytest.fixture(scope="module")
+def override_get_db(postgres_container):
+    dsn = _make_dsn(postgres_container)
+
+    def _get_db() -> typing.Generator[Cursor, None, None]:
+        with connect(dsn) as conn:
+            with conn.cursor() as cursor:
+                yield cursor
+
+    app.dependency_overrides[get_db] = _get_db
+    yield
+    app.dependency_overrides.pop(get_db, None)
+
+
+@pytest.fixture
+def client(override_get_db):
+    with TestClient(app) as c:
+        yield c
+
+
+# Per-test db_session fixture for psycopg cursor with rollback
+@pytest.fixture
+def db_session(postgres_container) -> typing.Generator[Cursor, None, None]:
+    dsn = _make_dsn(postgres_container)
+    with connect(dsn, autocommit=False) as conn:
+        with conn.cursor() as cursor:
+            try:
+                yield cursor
+            finally:
+                conn.rollback()

backend/tests/integration/test_smoke.py

@@ -0,0 +1,66 @@
+"""Integration smoke tests - verify Testcontainers and fixtures work end-to-end."""
+
+import pytest
+import psycopg
+from fastapi.testclient import TestClient
+
+
+@pytest.mark.integration
+def test_db_session_provides_cursor(db_session: psycopg.Cursor) -> None:
+    """Verify that the db_session fixture yields a live database cursor.
+
+    NOTE: This is a trivial test. It only checks the cursor in this module and does
+    not guarantee isolation across modules or test classes. If you use a different
+    isolation strategy for the database fixture, you may need more robust checks.
+
+    Executes a trivial query and asserts that the returned row is valid,
+    confirming the cursor is connected to the Testcontainers Postgres.
+    """
+    db_session.execute("SELECT 1 AS ok")
+    row = db_session.fetchone()
+    assert row is not None
+    assert row[0] == 1
+
+
+@pytest.mark.integration
+def test_db_session_rolls_back_and_isolation(db_session: psycopg.Cursor) -> None:
+    """Verify transactional rollback provides full test isolation.
+
+    NOTE: This test only verifies isolation if run repeatedly. If run in isolation,
+    it will always pass. If run with other tests that create the same table, or if
+    the fixture is broken, it may pass/fail alternately. This can be confusing, so
+    do not rely on this test as a sole indicator of isolation.
+
+    First asserts that ``_test_isolation`` does not exist (proving the
+    fixture rolled back any prior transaction), then creates the table,
+    inserts a row, and confirms it is visible inside the current
+    transaction. The fixture teardown will roll back the transaction
+    so subsequent tests never see these changes.
+    """
+    # The table must not exist at the start (fixture rolled back prior txn)
+    db_session.execute(
+        "SELECT EXISTS ("
+        "  SELECT FROM information_schema.tables "
+        "  WHERE table_name = '_test_isolation'"
+        ")"
+    )
+    assert not db_session.fetchone()[0]
+
+    # Write inside the transactional db_session
+    db_session.execute("CREATE TABLE _test_isolation (id serial PRIMARY KEY, val text)")
+    db_session.execute("INSERT INTO _test_isolation (val) VALUES ('should_be_gone')")
+    db_session.execute("SELECT count(*) FROM _test_isolation")
+    assert db_session.fetchone()[0] == 1  # visible inside this txn
+
+
+@pytest.mark.integration
+def test_client_health(client: TestClient):
+    """Verify that the TestClient fixture can reach the health endpoint in-process.
+
+    Sends a GET request to ``/api/v1/health`` and asserts a 200 response
+    with ``{"data": {"status": "ok"}}``.
+    """
+    resp = client.get("/api/v1/health")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["data"]["status"] == "ok"

backend/tests/unit/test_smoke.py

@@ -0,0 +1,13 @@
+"""Unit smoke tests - verify the test infrastructure works."""
+
+import pytest
+
+
+@pytest.mark.unit
+def test_marker_registered() -> None:
+    """Confirm that the ``unit`` marker is registered and accepted.
+
+    This is a placeholder test that simply passes. Its purpose is to
+    verify that pytest recognises the custom ``unit`` marker without
+    emitting unknown-marker warnings.
+    """

pyproject.toml

@@ -1,2 +1,7 @@
 [tool.uv.workspace]
 members = ["backend"]
+
+[dependency-groups]
+dev = [
+    "python-dotenv>=1.2.1",
+]