test(api): make default test run DB-free via integration marker

- auto-mark tests using db fixtures (client/db_session/rate_limit_client) as
  integration; mark test_rls_migration (direct engine use) explicitly
- gate setup_database/cleanup autouse fixtures on the integration marker so a
  default run never opens a DB connection
- deselect integration + e2e by default; run with -m integration + a real Postgres

Author: gracefullight

apps/api/pyproject.toml

@@ -59,9 +59,11 @@ testpaths = ["tests"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "session"
 asyncio_default_test_loop_scope = "session"
-# Skip e2e tests by default — they require a live server (E2E_API_URL).
-# Run them explicitly with: uv run pytest -m e2e
-addopts = "-m 'not e2e'"
+# Default run is DB-free: e2e (live server) and integration (real Postgres) are
+# deselected. Run them explicitly: uv run pytest -m e2e  /  uv run pytest -m integration
+# (integration needs TEST_DATABASE_URL pointing at a real Postgres).
+addopts = "-m 'not e2e and not integration'"
 markers = [
     "e2e: end-to-end smoke tests against a running API instance (requires E2E_API_URL)",
+    "integration: tests that hit a real database (auto-applied to tests using db fixtures)",
 ]

apps/api/tests/conftest.py

@@ -195,9 +195,32 @@ async def create_test_experience(
 # ---------------------------------------------------------------------------
 
 
+_DB_FIXTURES = {"client", "rate_limit_client", "db_session"}
+
+
+@pytest.hookimpl(tryfirst=True)
+def pytest_collection_modifyitems(config, items):
+    """Auto-mark any test that requests a DB-backed fixture as ``integration``.
+
+    Runs tryfirst so the marker is in place before pytest evaluates the ``-m``
+    deselection expression. Keeps the default run DB-free without per-file edits.
+    """
+    for item in items:
+        if _DB_FIXTURES & set(getattr(item, "fixturenames", ())):
+            item.add_marker("integration")
+
+
 @pytest.fixture(scope="session", autouse=True)
-async def setup_database():
-    """Create all tables before tests, drop after."""
+async def setup_database(request):
+    """Create all tables before tests, drop after — integration runs only.
+
+    No-op when no integration test is selected, so a DB-free default run never
+    opens a connection.
+    """
+    if not any(item.get_closest_marker("integration") for item in request.session.items):
+        yield
+        return
+
     # Import all models so SQLAlchemy metadata is complete.
     import src.auth.models  # noqa: F401
     import src.contact_relationships.models  # noqa: F401
@@ -218,8 +241,10 @@ async def setup_database():
 
 
 @pytest.fixture(autouse=True)
-async def cleanup():
-    """Truncate all tables before each test for isolation."""
+async def cleanup(request):
+    """Truncate all tables before each test for isolation — integration only."""
+    if request.node.get_closest_marker("integration") is None:
+        return
     async with test_engine.begin() as conn:
         for table in reversed(Base.metadata.sorted_tables):
             await conn.execute(text(f'TRUNCATE TABLE "{table.name}" CASCADE'))

apps/api/tests/test_rls_migration.py

@@ -15,6 +15,10 @@
 
 from tests.conftest import TestSessionFactory
 
+# Talks to a real Postgres directly via the test engine (not through a fixture),
+# so mark the whole module integration to keep the default run DB-free.
+pytestmark = pytest.mark.integration
+
 
 @pytest.mark.asyncio
 async def test_rls_policy_sql_is_valid():