[Fix] Test isolation for agent health checks and documentation test path resolution

Fix agent health check tests failing with 500 errors in parallel CI by
mocking prisma_client to None. Fix documentation validation tests using
CWD-relative paths that break depending on the working directory.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/workflows/test-unit-documentation.yml

@@ -0,0 +1,20 @@
+name: "Unit Tests: Documentation Validation"
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  documentation:
+    uses: ./.github/workflows/_test-unit-base.yml
+    with:
+      test-path: "tests/documentation_tests"
+      workers: 2
+      reruns: 1

tests/documentation_tests/test_exception_types.py

@@ -32,10 +32,12 @@ error_names = {
 
 
 # Parse the documentation to extract documented keys
-# repo_base = "./"
-repo_base = "../../"
+_test_dir = os.path.dirname(os.path.abspath(__file__))
+repo_base = os.path.abspath(os.path.join(_test_dir, "..", ".."))
 print(os.listdir(repo_base))
-docs_path = f"{repo_base}/docs/my-website/docs/exception_mapping.md"  # Path to the documentation
+docs_path = os.path.join(
+    repo_base, "docs", "my-website", "docs", "exception_mapping.md"
+)
 documented_keys = set()
 try:
     with open(docs_path, "r", encoding="utf-8") as docs_file:

tests/documentation_tests/test_general_setting_keys.py

@@ -2,7 +2,9 @@ import os
 import re
 
 # Define the base directory for the litellm repository and documentation path
-repo_base = "./litellm"  # Change this to your actual path
+_test_dir = os.path.dirname(os.path.abspath(__file__))
+_repo_root = os.path.abspath(os.path.join(_test_dir, "..", ".."))
+repo_base = os.path.join(_repo_root, "litellm")
 
 
 # Regular expressions to capture the keys used in general_settings.get() and general_settings[]
@@ -32,10 +34,9 @@ for root, dirs, files in os.walk(repo_base):
                 general_settings_keys.update(bracket_matches)
 
 # Parse the documentation to extract documented keys
-repo_base = "./"
-print(os.listdir(repo_base))
-docs_path = (
-    "./docs/my-website/docs/proxy/config_settings.md"  # Path to the documentation
+print(os.listdir(_repo_root))
+docs_path = os.path.join(
+    _repo_root, "docs", "my-website", "docs", "proxy", "config_settings.md"
 )
 documented_keys = set()
 try:

tests/documentation_tests/test_readme_providers.py

@@ -7,7 +7,9 @@ import re
 from litellm.types.utils import LlmProviders
 
 # Define paths
-readme_path = "./README.md"
+_test_dir = os.path.dirname(os.path.abspath(__file__))
+_repo_root = os.path.abspath(os.path.join(_test_dir, "..", ".."))
+readme_path = os.path.join(_repo_root, "README.md")
 
 # Providers that shouldn't be required in README
 # (specialized tools, observability, database providers that aren't LLM providers)

tests/documentation_tests/test_router_settings.py

@@ -37,14 +37,12 @@ print(router_init_params)
 router_init_params.remove("model_list")
 
 # Parse the documentation to extract documented keys
-repo_base = "./"
-print(os.listdir(repo_base))
-docs_path = (
-    "./docs/my-website/docs/proxy/config_settings.md"  # Path to the documentation
+_test_dir = os.path.dirname(os.path.abspath(__file__))
+_repo_root = os.path.abspath(os.path.join(_test_dir, "..", ".."))
+print(os.listdir(_repo_root))
+docs_path = os.path.join(
+    _repo_root, "docs", "my-website", "docs", "proxy", "config_settings.md"
 )
-# docs_path = (
-#     "../../docs/my-website/docs/proxy/config_settings.md"  # Path to the documentation
-# )
 documented_keys = set()
 try:
     with open(docs_path, "r", encoding="utf-8") as docs_file:

tests/documentation_tests/test_standard_logging_payload.py

@@ -38,7 +38,11 @@ def test_standard_logging_payload_documentation():
         print(_field)
 
     # Read the documentation
-    docs_path = "../../docs/my-website/docs/proxy/logging_spec.md"
+    _test_dir = os.path.dirname(os.path.abspath(__file__))
+    _repo_root = os.path.abspath(os.path.join(_test_dir, "..", ".."))
+    docs_path = os.path.join(
+        _repo_root, "docs", "my-website", "docs", "proxy", "logging_spec.md"
+    )
 
     try:
         with open(docs_path, "r", encoding="utf-8") as docs_file:

tests/test_litellm/proxy/agent_endpoints/test_endpoints.py

@@ -454,6 +454,10 @@ class TestAgentHealthCheck:
         self.admin_client = _make_app_with_role(LitellmUserRoles.PROXY_ADMIN)
         self.mock_registry = MagicMock()
         monkeypatch.setattr(ar_mod, "global_agent_registry", self.mock_registry)
+        # Ensure prisma_client is None so the endpoint skips DB queries.
+        # In CI with parallel workers, a MagicMock can leak from other test
+        # scopes, causing "object MagicMock can't be used in 'await'" errors.
+        monkeypatch.setattr("litellm.proxy.proxy_server.prisma_client", None)
 
     def _make_agent(self, agent_id: str, url: str | None = None) -> AgentResponse:
         card = _sample_agent_card_params()