fix: prevent Python 3.12 CI hang by excluding real_providers tests and hardening timeouts (#337)

* fix: prevent Python 3.12 CI hang with timeout coverage for fixtures

- Set timeout_func_only=false in pyproject.toml so pytest timeout covers
  fixture setup/teardown (previously only test body was covered)
- Add asyncio.wait_for(timeout=300) in indexed_test_project fixture to
  catch hangs during model loading or embedding generation
- Add timeout-minutes: 20 to CI test job as safety net
- Use signal timeout method in CI for all tests (can interrupt native code)"

Agent-Logs-Url: https://github.com/knitli/codeweaver/sessions/f35eacec-3469-4488-98b4-b20056964e04

* fix: move asyncio import to top level, revert accidental mise.toml change

Agent-Logs-Url: https://github.com/knitli/codeweaver/sessions/f35eacec-3469-4488-98b4-b20056964e04

* fix: exclude real_providers from CI markers, make signal timeout OS-conditional

- Add `not real_providers` to CI test markers — these heavy tests with
  full model loading/indexing should only run in nightly builds, not on
  every push. This was the actual root cause of the 3.12 hang.
- Make `--timeout-method=signal` conditional on $RUNNER_OS to avoid
  breaking Windows weekly tests (signal not supported on Windows).
- Revert accidental mise.toml hk version change."

Agent-Logs-Url: https://github.com/knitli/codeweaver/sessions/90b7c085-c5bb-419a-bb95-a2a4c8abb04d

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Author: Copilot

.github/workflows/_reusable-test.yml

@@ -71,6 +71,7 @@ jobs:
   test:
     name: Test Python ${{ matrix.python-version }}${{ matrix.experimental && ' (experimental)' || '' }}
     runs-on: ${{ inputs.runner-version }}
+    timeout-minutes: 20
     continue-on-error: ${{ matrix.experimental || false }}
     outputs:
       benchmark-available: ${{ steps.benchmark-compare.outputs.benchmark-available }}
@@ -201,17 +202,19 @@ jobs:
           MISE_PYTHON_VERSION: ${{ steps.setup-mise.outputs.MISE_PYTHON_VERSION }}
           TEST_MARKERS: ${{ inputs.test-markers }}
         run: |
-          # Real-provider tests: bump timeout to 15min per test and switch
-          # the timeout method to `signal` so SIGALRM can interrupt
-          # blocking C code (ONNX runtime inference). The default `thread`
-          # method in pyproject.toml can't kill stuck native code, so a
-          # genuinely hung embedding call would run until the 6h GHA
-          # job limit. `signal` has asyncio interaction caveats but
-          # they're acceptable for the integration suite.
+          # On Linux/macOS, use `signal` timeout method so SIGALRM can
+          # interrupt blocking C code (ONNX runtime, model loading).
+          # On Windows, `signal` is not supported by pytest-timeout —
+          # fall back to the default `thread` method from pyproject.toml.
+          TIMEOUT_ARGS=""
+          if [[ "$RUNNER_OS" != "Windows" ]]; then
+            TIMEOUT_ARGS="--timeout-method=signal"
+          fi
+
           if [[ "${TEST_MARKERS}" == *"real_providers"* ]]; then
-            mise run test-cov -m "${TEST_MARKERS}" --timeout=900 --timeout-method=signal
+            mise run test-cov -m "${TEST_MARKERS}" --timeout=900 ${TIMEOUT_ARGS}
           else
-            mise run test-cov -m "${TEST_MARKERS}"
+            mise run test-cov -m "${TEST_MARKERS}" ${TIMEOUT_ARGS}
           fi
       - name: Upload coverage to Codecov
         if: ${{ inputs.upload-coverage && matrix.python-version == '3.12' && !inputs.benchmark-tests }}

.github/workflows/ci.yml

@@ -49,7 +49,7 @@ jobs:
       QDRANT__SERVICE__API_KEY: ${{ secrets.QDRANT__SERVICE__API_KEY }}
       VOYAGE_API_KEY: ${{ secrets.VOYAGE_API_KEY }}
     with:
-      test-markers: "not docker and not qdrant and not dev_only and not skip_ci and not network and not external_api and not flaky"
+      test-markers: "not docker and not qdrant and not dev_only and not skip_ci and not network and not external_api and not flaky and not real_providers"
       upload-coverage: true
       run-quality-checks: true
 

pyproject.toml

@@ -673,8 +673,12 @@ testpaths = ["tests"]
 asyncio_mode = "auto"
 timeout = "600"
 timeout_method = "thread"
-# Override timeout for specific markers
-timeout_func_only = true  # Only apply timeout to test functions, not setup/teardown
+# Apply timeout to entire test lifecycle (setup + call + teardown) so that
+# fixture hangs (e.g. model loading, indexing) are caught instead of running
+# until the GHA job limit.  Previously `timeout_func_only = true` left
+# fixtures uncovered, causing Python 3.12 CI to hang indefinitely in the
+# `indexed_test_project` fixture during `index_project()`.
+timeout_func_only = false
 
 [tool.ty.environment]
 python-version = "3.12"

scripts/gen_api_docs.py

@@ -54,7 +54,16 @@
     "codeweaver.cli.*.*",
     "codeweaver.data.*",
     "codeweaver.semantic.data.*",
-    "",
+]
+
+FORCE_INCLUDE_PATTERNS: list[str] = [
+    # If any module matches both EXCLUDE_PATTERNS and FORCE_INCLUDE_PATTERNS,
+    # it will be included. This is for modules that are private but still
+    # worth documenting, or that would otherwise be excluded by an overly
+    # broad pattern.
+    "codeweaver.server.agent_api.search.__init__",
+    "codeweaver.providers.embedding.capabilities.base",
+    "codeweaver.providers.reranking.capabilities.base",
 ]
 
 
@@ -185,7 +194,7 @@ def _generate_module_docs(loader: GriffeLoader, mod_name: str, output_path: Path
 
 def _is_excluded(dotted_name: str) -> bool:
     """Return True if `dotted_name` matches any `EXCLUDE_PATTERNS` glob."""
-    return any(fnmatch.fnmatchcase(dotted_name, pat) for pat in EXCLUDE_PATTERNS)
+    return any(fnmatch.fnmatchcase(dotted_name, pat) for pat in EXCLUDE_PATTERNS) and not any(fnmatch.fnmatchcase(dotted_name, pat) for pat in FORCE_INCLUDE_PATTERNS)
 
 
 def _iter_modules(src_path: Path) -> Iterator[tuple[str, Path]]:

tests/integration/conftest.py

@@ -8,6 +8,7 @@
 
 from __future__ import annotations
 
+import asyncio
 import contextlib
 import logging
 import os
@@ -1212,7 +1213,17 @@ async def get_test_settings() -> CodeWeaverSettingsType:
     # Ensure it's using the correct project path
     indexer._project_path = project_path
 
-    await indexer.index_project(force_reindex=True)
+    # Use asyncio.wait_for to prevent indefinite hangs during indexing.
+    # On Python 3.12, model loading or embedding generation can hang in
+    # native code; without this guard the fixture would block forever
+    # since pytest timeout_func_only previously excluded fixtures.
+    try:
+        await asyncio.wait_for(indexer.index_project(force_reindex=True), timeout=300)
+    except TimeoutError:
+        pytest.fail(
+            "indexed_test_project fixture timed out after 300s during index_project(). "
+            "This typically indicates model loading or embedding generation hung in native code."
+        )
 
     yield project_path