Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(tests): stop module-level dotenv loaders from polluting os.environ during pytest collection

chopratejasd5ca50cd038c
diff --git a/headroom/backends/litellm.py b/headroom/backends/litellm.py
index 14ba30658..0faa64b83 100644
--- a/headroom/backends/litellm.py
+++ b/headroom/backends/litellm.py
@@ -23,10 +23,22 @@ from .base import Backend, BackendResponse, StreamEvent
logger = logging.getLogger(__name__)
+# litellm calls `dotenv.load_dotenv()` during its own import, which loads
+# the project `.env` into `os.environ`. We don't want that side effect —
+# importing a backend module should not silently leak API keys into the
+# process. Snapshot `os.environ` around the import and undo any keys
+# litellm added. Same pattern as `headroom/pricing/litellm_pricing.py`.
try:
+ import os as _os
+
+ _env_snapshot = set(_os.environ)
import litellm
from litellm import acompletion
+ for _leaked_key in set(_os.environ) - _env_snapshot:
+ del _os.environ[_leaked_key]
+ del _env_snapshot, _os
+
LITELLM_AVAILABLE = True
except ImportError:
LITELLM_AVAILABLE = False
diff --git a/headroom/pricing/litellm_pricing.py b/headroom/pricing/litellm_pricing.py
index 764adec6a..b87d9dafb 100644
--- a/headroom/pricing/litellm_pricing.py
+++ b/headroom/pricing/litellm_pricing.py
@@ -11,9 +11,23 @@ from __future__ import annotations
from dataclasses import dataclass
from typing import Any
+# litellm calls `dotenv.load_dotenv()` during its own import, which loads
+# the project `.env` into `os.environ`. We don't want that side effect —
+# importing a pricing helper should not silently leak API keys into the
+# process. Snapshot `os.environ` around the import and undo any keys
+# litellm added. The module itself is fully imported and cached in
+# `sys.modules`; subsequent `import litellm` calls hit the cache and
+# don't re-run the dotenv side effect.
try:
+ import os as _os
+
+ _env_snapshot = set(_os.environ)
import litellm
+ for _leaked_key in set(_os.environ) - _env_snapshot:
+ del _os.environ[_leaked_key]
+ del _env_snapshot, _os
+
LITELLM_AVAILABLE = True
except ImportError:
litellm = None # type: ignore[assignment]
diff --git a/tests/_dotenv.py b/tests/_dotenv.py
new file mode 100644
index 000000000..d732384f5
--- /dev/null
+++ b/tests/_dotenv.py
@@ -0,0 +1,106 @@
+"""Local-only `.env` loader for tests that need provider API keys.
+
+Why this exists: several test modules (compression-summary evals,
+query-echo, cost-tracker counterfactual) need real API keys and used to
+load the project `.env` at module level via `os.environ.setdefault(...)`.
+That ran during pytest collection and *globally* mutated `os.environ`,
+which caused unrelated tests (e.g. `test_proxy_passthrough_integration`)
+to flip from cleanly skipped to running-live-and-failing — their
+`@pytest.mark.skipif(not os.environ.get(...))` guards saw the leaked
+key and decided not to skip.
+
+Usage from a test module that needs `.env`:
+
+ from tests._dotenv import load_env_overrides, autouse_apply_env
+
+ _env = load_env_overrides()
+ ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY") or _env.get(
+ "ANTHROPIC_API_KEY", ""
+ )
+
+ pytestmark = pytest.mark.skipif(
+ not ANTHROPIC_KEY,
+ reason="ANTHROPIC_API_KEY not set",
+ )
+
+ apply_dotenv = autouse_apply_env(_env)
+
+The `apply_dotenv` autouse fixture sets the values via `monkeypatch.setenv`,
+which auto-restores at function-scope teardown — no cross-module leak.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import pytest
+
+
+def load_env_overrides() -> dict[str, str]:
+ """Read the project `.env` file (if present) into a plain dict.
+
+ Returns an empty dict when `.env` is missing — CI runs with real
+ secrets in the environment and no `.env`, so the per-test fixture
+ becomes a no-op there.
+ """
+ env_path = Path(__file__).parent.parent / ".env"
+ out: dict[str, str] = {}
+ if not env_path.exists():
+ return out
+ for raw in env_path.read_text().splitlines():
+ line = raw.strip()
+ if not line or line.startswith("#") or "=" not in line:
+ continue
+ key, _, value = line.partition("=")
+ out[key.strip()] = value.strip()
+ return out
+
+
+def autouse_apply_env(overrides: dict[str, str]) -> pytest.FixtureFunction:
+ """Build an autouse fixture that applies `overrides` for the test
+ function and restores at teardown. Skips keys already set in the real
+ environment so CI/secret-store values take precedence over `.env`.
+ """
+
+ @pytest.fixture(autouse=True)
+ def _apply(monkeypatch: pytest.MonkeyPatch) -> None:
+ for key, value in overrides.items():
+ if not os.environ.get(key):
+ monkeypatch.setenv(key, value)
+
+ return _apply
+
+
+def importorskip_no_env_leak(module_name: str):
+ """`pytest.importorskip` substitute that quarantines `os.environ` mutations.
+
+ Why: `litellm` (and other libraries that bundle `python-dotenv`) call
+ `dotenv.load_dotenv()` at module import time, which loads the project
+ `.env` into the global `os.environ`. When a test module does
+ `pytest.importorskip("litellm")` at module-level, that pollution
+ happens during pytest's collection phase — and any *later-collected*
+ test module whose `@pytest.mark.skipif(not os.environ.get("FOO_API_KEY"))`
+ decorator runs after the leak will see the polluted value and stop
+ skipping. The proxy-passthrough integration tests stop being safely
+ skipped, run live against fake keys, and fail.
+
+ This wrapper snapshots `os.environ`, imports the module, then deletes
+ any keys that the import added. The module is fully imported and
+ cached in `sys.modules` — its functionality (price tables, model
+ metadata) is unaffected. Subsequent `import litellm` calls hit the
+ cache and don't re-run the `dotenv.load_dotenv` side-effect.
+
+ Use as a drop-in replacement for `pytest.importorskip` at the top of
+ test modules that need litellm or any other dotenv-loading library.
+ """
+ import importlib
+
+ snapshot = set(os.environ)
+ try:
+ mod = importlib.import_module(module_name)
+ except ImportError:
+ pytest.skip(f"{module_name} not installed", allow_module_level=True)
+ for key in set(os.environ) - snapshot:
+ del os.environ[key]
+ return mod
diff --git a/tests/test_backend_bugs.py b/tests/test_backend_bugs.py
index 30297ef58..bccbd25bc 100644
--- a/tests/test_backend_bugs.py
+++ b/tests/test_backend_bugs.py
@@ -10,9 +10,11 @@ from unittest.mock import AsyncMock, MagicMock, patch
import pytest
-pytest.importorskip("litellm")
+from tests._dotenv import importorskip_no_env_leak
-from headroom.backends.litellm import (
+importorskip_no_env_leak("litellm")
+
+from headroom.backends.litellm import ( # noqa: E402 (must follow importorskip)
_VERTEX_MODEL_MAP,
LiteLLMBackend,
_convert_anthropic_tool,
diff --git a/tests/test_bedrock_region.py b/tests/test_bedrock_region.py
index a8ef32a9f..8a52d5009 100644
--- a/tests/test_bedrock_region.py
+++ b/tests/test_bedrock_region.py
@@ -7,11 +7,11 @@ AWS API call fails.
from unittest.mock import MagicMock, patch
-import pytest
+from tests._dotenv import importorskip_no_env_leak
-pytest.importorskip("litellm")
+importorskip_no_env_leak("litellm")
-from headroom.backends.litellm import (
+from headroom.backends.litellm import ( # noqa: E402 (must follow importorskip)
LiteLLMBackend,
_bedrock_profiles_cache,
_bedrock_region_prefix,
diff --git a/tests/test_bundled_tools_savings.py b/tests/test_bundled_tools_savings.py
index 234b116be..cc3df204e 100644
--- a/tests/test_bundled_tools_savings.py
+++ b/tests/test_bundled_tools_savings.py
@@ -21,16 +21,17 @@ from pathlib import Path
import pytest
-try:
- from dotenv import load_dotenv
+# See tests/_dotenv.py for why we don't call dotenv.load_dotenv() at module
+# level (it pollutes os.environ during pytest collection and breaks
+# @pytest.mark.skipif evaluation in unrelated test modules).
+from tests._dotenv import autouse_apply_env, load_env_overrides
- load_dotenv(Path(__file__).resolve().parent.parent / ".env")
-except ImportError:
- pass
+_env_overrides = load_env_overrides()
+apply_dotenv = autouse_apply_env(_env_overrides)
-import tiktoken
+import tiktoken # noqa: E402 (must follow .env-overrides setup)
-from headroom import binaries
+from headroom import binaries # noqa: E402 (must follow .env-overrides setup)
# ---------- Fixtures ------------------------------------------------------ #
diff --git a/tests/test_compression_summary_hard_eval.py b/tests/test_compression_summary_hard_eval.py
index e16895eaf..05b47c9fa 100644
--- a/tests/test_compression_summary_hard_eval.py
+++ b/tests/test_compression_summary_hard_eval.py
@@ -13,19 +13,14 @@ from __future__ import annotations
import json
import os
-from pathlib import Path
import pytest
-env_path = Path(__file__).parent.parent / ".env"
-if env_path.exists():
- for line in env_path.read_text().splitlines():
- line = line.strip()
- if line and not line.startswith("#") and "=" in line:
- key, _, value = line.partition("=")
- os.environ.setdefault(key.strip(), value.strip())
+from tests._dotenv import autouse_apply_env, load_env_overrides
-ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+_env_overrides = load_env_overrides()
+ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY") or _env_overrides.get("ANTHROPIC_API_KEY", "")
+apply_dotenv = autouse_apply_env(_env_overrides)
pytestmark = pytest.mark.skipif(
not ANTHROPIC_KEY,
diff --git a/tests/test_compression_summary_integration.py b/tests/test_compression_summary_integration.py
index d72925902..14246ef39 100644
--- a/tests/test_compression_summary_integration.py
+++ b/tests/test_compression_summary_integration.py
@@ -12,20 +12,14 @@ from __future__ import annotations
import json
import os
-from pathlib import Path
import pytest
-# Load .env
-env_path = Path(__file__).parent.parent / ".env"
-if env_path.exists():
- for line in env_path.read_text().splitlines():
- line = line.strip()
- if line and not line.startswith("#") and "=" in line:
- key, _, value = line.partition("=")
- os.environ.setdefault(key.strip(), value.strip())
+from tests._dotenv import autouse_apply_env, load_env_overrides
-ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+_env_overrides = load_env_overrides()
+ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY") or _env_overrides.get("ANTHROPIC_API_KEY", "")
+apply_dotenv = autouse_apply_env(_env_overrides)
pytestmark = pytest.mark.skipif(
not ANTHROPIC_KEY,
diff --git a/tests/test_compression_summary_tool_eval.py b/tests/test_compression_summary_tool_eval.py
index f7a91fdd3..2e7ce3444 100644
--- a/tests/test_compression_summary_tool_eval.py
+++ b/tests/test_compression_summary_tool_eval.py
@@ -16,20 +16,14 @@ from __future__ import annotations
import json
import os
-from pathlib import Path
import pytest
-# Load .env
-env_path = Path(__file__).parent.parent / ".env"
-if env_path.exists():
- for line in env_path.read_text().splitlines():
- line = line.strip()
- if line and not line.startswith("#") and "=" in line:
- key, _, value = line.partition("=")
- os.environ.setdefault(key.strip(), value.strip())
+from tests._dotenv import autouse_apply_env, load_env_overrides
-ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+_env_overrides = load_env_overrides()
+ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY") or _env_overrides.get("ANTHROPIC_API_KEY", "")
+apply_dotenv = autouse_apply_env(_env_overrides)
pytestmark = pytest.mark.skipif(
not ANTHROPIC_KEY,
diff --git a/tests/test_cost_tracker_counterfactual.py b/tests/test_cost_tracker_counterfactual.py
index 2e3ff1c2d..5fb9ce1e4 100644
--- a/tests/test_cost_tracker_counterfactual.py
+++ b/tests/test_cost_tracker_counterfactual.py
@@ -6,22 +6,16 @@ This is simple, monotonic, and transparent.
from __future__ import annotations
-import os
-from pathlib import Path
+from tests._dotenv import (
+ autouse_apply_env,
+ importorskip_no_env_leak,
+ load_env_overrides,
+)
-import pytest
+_env_overrides = load_env_overrides()
+apply_dotenv = autouse_apply_env(_env_overrides)
-# Load .env for live test
-_env_path = Path(__file__).resolve().parent.parent / ".env"
-if _env_path.exists():
- for line in _env_path.read_text().splitlines():
- line = line.strip()
- if line and not line.startswith("#") and "=" in line:
- key, _, value = line.partition("=")
- os.environ.setdefault(key.strip(), value.strip())
-
-
-pytest.importorskip("litellm")
+importorskip_no_env_leak("litellm")
def test_savings_at_list_price():
diff --git a/tests/test_memory_usage_integration.py b/tests/test_memory_usage_integration.py
index 991279a01..2632fde15 100644
--- a/tests/test_memory_usage_integration.py
+++ b/tests/test_memory_usage_integration.py
@@ -19,10 +19,12 @@ import os
import pytest
-# Load .env file
-from dotenv import load_dotenv
+# Load .env values into a local dict and apply per-test (not at module
+# level) — see tests/_dotenv.py for why.
+from tests._dotenv import autouse_apply_env, load_env_overrides
-load_dotenv()
+_env_overrides = load_env_overrides()
+apply_dotenv = autouse_apply_env(_env_overrides)
# Check HNSW availability for skipping tests
try:
diff --git a/tests/test_query_echo.py b/tests/test_query_echo.py
index 34742c10d..9eea8d147 100644
--- a/tests/test_query_echo.py
+++ b/tests/test_query_echo.py
@@ -8,22 +8,15 @@ from __future__ import annotations
import json
import os
-from pathlib import Path
import pytest
from headroom.transforms.query_echo import extract_user_query, inject_query_echo
+from tests._dotenv import autouse_apply_env, load_env_overrides
-# Load .env for integration tests
-env_path = Path(__file__).parent.parent / ".env"
-if env_path.exists():
- for line in env_path.read_text().splitlines():
- line = line.strip()
- if line and not line.startswith("#") and "=" in line:
- key, _, value = line.partition("=")
- os.environ.setdefault(key.strip(), value.strip())
-
-ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY", "")
+_env_overrides = load_env_overrides()
+ANTHROPIC_KEY = os.environ.get("ANTHROPIC_API_KEY") or _env_overrides.get("ANTHROPIC_API_KEY", "")
+apply_dotenv = autouse_apply_env(_env_overrides)
# =============================================================================