~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
# allow: no-sut-import — shared test-helper module (not a test); provides utilities imported by other tests
"""
Test utilities and helper functions - incorporating scottvr's patterns.
This module provides common utilities for tests.
"""
import json
import sys
import threading
from contextlib import contextmanager
from pathlib import Path
from typing import Any, Dict, List, Optional
from unittest.mock import Mock
from loguru import logger
def add_src_to_path():
"""Add the src directory to Python path for imports."""
src_path = str(Path(__file__).parent.parent / "src")
if src_path not in sys.path:
sys.path.insert(0, src_path)
def mock_api_response(
status_code: int = 200,
json_data: Optional[Dict] = None,
text: Optional[str] = None,
raise_exception: Optional[Exception] = None,
):
"""
Create a mock API response object.
Args:
status_code: HTTP status code
json_data: JSON response data
text: Text response data
raise_exception: Exception to raise when accessed
Returns:
Mock response object
"""
mock_response = Mock()
mock_response.status_code = status_code
if raise_exception:
mock_response.json.side_effect = raise_exception
mock_response.text = str(raise_exception)
else:
if json_data is not None:
mock_response.json.return_value = json_data
mock_response.text = json.dumps(json_data)
elif text is not None:
mock_response.text = text
mock_response.json.side_effect = json.JSONDecodeError(
"Not JSON", text, 0
)
else:
mock_response.json.return_value = {}
mock_response.text = "{}"
return mock_response
def assert_search_result_format(result: Dict[str, Any]):
"""
Assert that a search result has the correct format.
Args:
result: Search result dictionary to validate
"""
assert isinstance(result, dict), "Result should be a dictionary"
assert "title" in result, "Result should have a title"
# Some engines use 'link', others use 'url'
assert "link" in result or "url" in result, (
"Result should have a link or url"
)
assert "snippet" in result, "Result should have a snippet"
assert isinstance(result["title"], str), "Title should be a string"
# Check whichever field is present
if "link" in result:
assert isinstance(result["link"], str), "Link should be a string"
if "url" in result:
assert isinstance(result["url"], str), "URL should be a string"
assert isinstance(result["snippet"], str), "Snippet should be a string"
def assert_findings_format(findings: Dict[str, Any]):
"""
Assert that findings have the correct format.
Args:
findings: Findings dictionary to validate
"""
assert isinstance(findings, dict), "Findings should be a dictionary"
assert "findings" in findings, "Should have findings list"
assert "current_knowledge" in findings, "Should have current_knowledge"
assert "iterations" in findings, "Should have iterations count"
assert "questions_by_iteration" in findings, (
"Should have questions_by_iteration"
)
assert isinstance(findings["findings"], list), "Findings should be a list"
assert isinstance(findings["current_knowledge"], str), (
"Knowledge should be a string"
)
assert isinstance(findings["iterations"], int), (
"Iterations should be an integer"
)
assert isinstance(findings["questions_by_iteration"], dict), (
"Questions should be a dict"
)
def create_test_research_context(query: str = "test query") -> Dict[str, Any]:
"""
Create a test research context with all required fields.
Args:
query: Research query
Returns:
Complete research context dictionary
"""
return {
"query": query,
"search_tool": "searxng",
"llm_provider": "ollama",
"llm_model": "gemma3:12b",
"search_iterations": 3,
"questions_per_iteration": 2,
"temperature": 0.7,
"max_tokens": 4096,
"enable_fact_checking": True,
"search_strategy": "standard",
}
def mock_progress_callback():
"""
Create a mock progress callback that tracks calls.
Returns:
Tuple of (callback function, calls list)
"""
calls = []
def callback(message: str, progress: int, metadata: Optional[Dict] = None):
calls.append(
{
"message": message,
"progress": progress,
"metadata": metadata or {},
}
)
return callback, calls
def assert_progress_callback_called(
calls: List[Dict],
expected_message: str = None,
expected_progress: int = None,
):
"""
Assert that a progress callback was called with expected parameters.
Args:
calls: List of callback calls
expected_message: Expected message (substring match)
expected_progress: Expected progress value
"""
assert len(calls) > 0, "Progress callback should have been called"
if expected_message:
messages = [call["message"] for call in calls]
assert any(expected_message in msg for msg in messages), (
f"Expected message '{expected_message}' not found in calls: {messages}"
)
if expected_progress is not None:
progresses = [call["progress"] for call in calls]
assert expected_progress in progresses, (
f"Expected progress {expected_progress} not found in calls: {progresses}"
)
@contextmanager
def restored_loguru_state():
"""Isolate patcher, namespace activation and handlers, then restore them.
Detach the original handlers without stopping them: logger.remove() in
the wrapped block must only close that block's sinks. Handler IDs remain
monotonic so an existing ID cannot be reused by an isolated sink.
"""
core = logger._core
with core.lock:
saved = (
core.patcher,
core.enabled.copy(),
list(core.activation_list),
core.activation_none,
core.handlers,
core.min_level,
)
core.handlers = {}
core.min_level = float("inf")
try:
yield
finally:
logger.remove()
with core.lock:
(
core.patcher,
core.enabled,
core.activation_list,
core.activation_none,
core.handlers,
core.min_level,
) = saved
class MockCache:
"""Mock cache implementation for testing."""
def __init__(self):
self.cache = {}
self.hits = 0
self.misses = 0
def get(self, key: str) -> Optional[Any]:
if key in self.cache:
self.hits += 1
return self.cache[key]
self.misses += 1
return None
def set(self, key: str, value: Any):
self.cache[key] = value
def clear(self):
self.cache.clear()
self.hits = 0
self.misses = 0
def get_stats(self) -> Dict[str, int]:
return {
"hits": self.hits,
"misses": self.misses,
"size": len(self.cache),
}
def nested_json_past_the_scanner_limit() -> bytes:
"""Arrays nested deeper than ``json.loads`` can follow on this interpreter.
The depth at which CPython's C scanner gives up and raises
``RecursionError`` depends on the running thread's stack size, not on a
language constant, so a hardcoded depth would parse into a valid array on
a machine with a roomier stack and quietly stop testing anything. The
depth is probed on a plain thread, which is where Starlette's test portal
parses a request body, and quadrupled to keep a margin over any
difference between the two stacks. Even on a 64 MB thread stack the body
stays well inside the app's 16 MB JSON cap.
"""
refused: List[int] = []
def probe():
depth = 10_000
for _ in range(8):
try:
json.loads(b"[" * depth + b"]" * depth)
except RecursionError:
refused.append(depth)
return
depth *= 2
thread = threading.Thread(target=probe)
thread.start()
thread.join()
assert refused, (
"no nesting depth up to 1 280 000 made json.loads raise "
"RecursionError, so a test built on it would no longer test anything"
)
depth = refused[0] * 4
return b"[" * depth + b"]" * depth