From b6fc64451e23dcddc356ae3a17b3d57baa2b2eb3 Mon Sep 17 00:00:00 2001
From: dimknaf <136385722+dimknaf@users.noreply.github.com>
Date: Fri, 12 Jun 2026 09:07:47 +0100
Subject: [PATCH] fix(test): require the live test stack only for tests that
 use it

The session-wide autouse guard demanded the isolated test stack even for
pure unit tests - including the two files CI runs - so they all errored
when nothing listened on 8002. The guard now hangs off the api fixture:
unit tests run stack-free, integration tests still fail fast with the
start-the-stack instructions.
---
 CHANGELOG.md      | 11 +++++++++++
 tests/README.md   |  2 ++
 tests/conftest.py | 15 +++++++++------
 3 files changed, 22 insertions(+), 6 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index baecc68..1f3e26d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Fixed
+
+- **Unit tests no longer demand the test stack.** The live-API guard in
+  `tests/conftest.py` was session-wide (`autouse`), so even pure unit tests
+  — including the two files CI runs — errored out when the isolated test
+  stack wasn't up. The guard now applies only to tests that actually use
+  the API fixture; unit tests run with no stack, and integration tests
+  still fail fast with the start-the-stack instructions.
+
 ## [0.6.0] — 2026-06-12
 
 ### Added
diff --git a/tests/README.md b/tests/README.md
index 7094ebc..f2a0aaf 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -4,6 +4,8 @@ Integration tests that exercise the real HTTP API against a live PostgreSQL and,
 
 The suite runs against an **isolated test stack** — its own API (port 8002) and its own throwaway Postgres (`braindb_test`, host port 5436). It never touches your personal BrainDB database; tearing the stack down wipes all test data.
 
+Pure unit files (`test_split_chunks.py`, `test_wiki_sections.py`, `test_final_answer_rename.py`, `test_handoff_hooks.py`, `test_runhooks_countdown.py`) need **no stack at all** — only tests that talk to the API or database require the test stack to be up.
+
 ## Prerequisites
 
 Start the test stack:
diff --git a/tests/conftest.py b/tests/conftest.py
index 83c421c..6d0105b 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -54,12 +54,15 @@ def _wait_for_health(url: str, timeout: int = 30) -> bool:
     return False
 
 
-@pytest.fixture(scope="session", autouse=True)
+@pytest.fixture(scope="session")
 def _require_live_api() -> None:
     """Fail fast and loud if the test stack isn't up.
 
-    Deliberately NOT defaulting to the personal stack on :8000 — the suite
-    must never run against a database holding real data.
+    Attached to the `api` fixture (NOT autouse) so pure unit tests — the
+    validator/handoff/chunking files that never touch HTTP — run with no
+    stack at all (that's also what CI runs). Deliberately NOT defaulting
+    to the personal stack on :8000 — the suite must never run against a
+    database holding real data.
     """
     if not _wait_for_health(API_URL):
         pytest.fail(
@@ -72,7 +75,7 @@ def _require_live_api() -> None:
 
 
 @pytest.fixture
-def api() -> str:
+def api(_require_live_api: None) -> str:
     """Base URL for the API — tests append paths like f'{api}/api/v1/...'."""
     return API_URL
 
@@ -86,7 +89,7 @@ def test_tag() -> str:
 
 
 @pytest.fixture
-def created_entities() -> Iterator[list[str]]:
+def created_entities(api: str) -> Iterator[list[str]]:
     """Collector the test appends entity IDs to. Everything in it gets deleted
     at teardown. Ignore 404s (already cleaned up).
     """
@@ -94,7 +97,7 @@ def created_entities() -> Iterator[list[str]]:
     yield ids
     for eid in ids:
         try:
-            requests.delete(f"{API_URL}/api/v1/entities/{eid}", timeout=5)
+            requests.delete(f"{api}/api/v1/entities/{eid}", timeout=5)
         except requests.RequestException:
             pass