Skip to content

~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.

8.5 KB
Raw Blame
# 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