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.

12.4 KB
Raw Blame
"""Shared helpers for research-service worker tests.

These previously lived in ``test_research_service_coverage_gaps.py``. The
FastAPI migration deleted that module because its *assertions* targeted the
Flask-era worker, but its *helpers* are still needed by
``test_research_service_search_limit_precedence.py``. Keeping them in a plain
sibling module (the pattern used by ``tests/notes/helpers.py``) means they no
longer disappear when a test module is retired.
"""

from contextlib import contextmanager, ExitStack
from functools import wraps
from unittest.mock import MagicMock, create_autospec, patch

from local_deep_research.web.services import research_service

# Module paths used as ``unittest.mock.patch`` targets.
MODULE = "local_deep_research.web.services.research_service"
RESEARCH_STATE_MOD = "local_deep_research.web.research_state"
GLOBALS_MOD = "local_deep_research.web.routes.globals"
THREAD_SETTINGS_MOD = "local_deep_research.config.thread_settings"
SETTINGS_LOGGER_MOD = "local_deep_research.settings.logger"
QUEUE_PROC_MOD = "local_deep_research.web.queue.processor_v2"


def _fake_session_ctx(session=None):
    """Return a context manager factory that yields a mock session."""
    if session is None:
        session = MagicMock()

    @contextmanager
    def ctx(username=None):
        yield session

    return ctx


def _make_mock_research(status=None, research_meta=None):
    """Build a minimal ResearchHistory mock."""
    r = MagicMock()
    r.status = status
    r.research_meta = research_meta
    r.created_at = "2024-01-01T00:00:00"
    r.report_content = None
    return r


def _get_raw_run_research_process():
    """Run the unwrapped worker while restoring the caller's egress context.

    These tests intentionally skip thread_cleanup, which normally clears
    the worker's active context. Preserve any enclosing context and prevent
    a mocked run from contaminating policy checks later in the same process.
    """
    from local_deep_research.security.egress.audit_hook import (
        clear_active_context,
        get_active_context,
        set_active_context,
    )
    from local_deep_research.web.services.research_service import (
        run_research_process,
    )

    # @log_for_research and @thread_cleanup, outermost first.
    raw_worker = run_research_process.__wrapped__.__wrapped__

    @wraps(raw_worker)
    def isolated_worker(*args, **kwargs):
        previous = get_active_context()
        try:
            return raw_worker(*args, **kwargs)
        finally:
            if previous is None:
                clear_active_context()
            else:
                set_active_context(previous)

    return isolated_worker


def _base_run_patches(mock_session=None):
    """Return a dict of patches needed for run_research_process tests."""
    if mock_session is None:
        mock_session = MagicMock()
        mock_research = _make_mock_research(research_meta={})
        mock_session.query.return_value.filter_by.return_value.first.return_value = mock_research

    return {
        f"{MODULE}.get_user_db_session": _fake_session_ctx(mock_session),
        f"{MODULE}.handle_termination": MagicMock(),
        f"{MODULE}.cleanup_research_resources": MagicMock(),
        f"{MODULE}.set_search_context": MagicMock(),
        # Socket isolation. The Flask-era ``SocketIOService`` class is gone;
        # the FastAPI worker emits through these module-level socketio_asgi
        # aliases plus the ``_socket_emitter`` adapter singleton.
        #
        # autospec, NOT a bare MagicMock: a plain mock accepts ANY signature,
        # so when ``emit_to_subscribers`` gained a required ``owner`` kwarg
        # these patches happily swallowed both the calls that forgot it and
        # the calls that passed it to an adapter that did not accept it. Every
        # such call site sits inside a swallowing ``except``, so the suite
        # stayed green while live progress delivery was silently broken.
        # autospec makes the mock enforce the real signature, turning that
        # class of break into a test failure.
        f"{MODULE}._sio_emit": create_autospec(
            research_service._sio_emit, spec_set=True
        ),
        f"{MODULE}._sio_remove": create_autospec(
            research_service._sio_remove, spec_set=True
        ),
        f"{MODULE}._socket_emitter": create_autospec(
            research_service._socket_emitter, spec_set=True
        ),
        f"{MODULE}.calculate_duration": MagicMock(return_value=5),
        f"{MODULE}.ErrorReportGenerator": MagicMock(
            return_value=MagicMock(
                generate_error_report=MagicMock(return_value="error report")
            )
        ),
        # ``run_research_process`` imports research state straight from
        # ``research_state``; patching the ``routes.globals`` shim does not
        # reach it, because the shim bound its own names at import time.
        f"{RESEARCH_STATE_MOD}.is_termination_requested": MagicMock(
            return_value=False
        ),
        f"{RESEARCH_STATE_MOD}.is_research_active": MagicMock(
            return_value=False
        ),
        f"{RESEARCH_STATE_MOD}.update_progress_and_check_active": MagicMock(
            return_value=(5, True)
        ),
        # ``_make_chat_stream_callback`` still resolves through the shim on
        # purpose (see the comment at its import site), so that target has to
        # be neutralised too.
        f"{GLOBALS_MOD}.is_termination_requested": MagicMock(
            return_value=False
        ),
        f"{SETTINGS_LOGGER_MOD}.log_settings": MagicMock(),
        f"{THREAD_SETTINGS_MOD}.set_settings_context": MagicMock(),
        f"{QUEUE_PROC_MOD}.queue_processor": MagicMock(),
    }


# ---------------------------------------------------------------------------
# Quick-mode error-classification / synthesis-fallback harnesses.
#
# ``run_research_process``'s error handling for a failed search
# (``except Exception as search_error`` around ``system.analyze_topic()``,
# research_service.py ~1670-1730) and for an error-shaped *result*
# (the ``formatted_findings.startswith("Error:")`` branch, ~1736-1900)
# are both several hundred lines deep inside one 2000+ line function and
# are not exposed as standalone symbols. Several test modules used to
# re-implement (a stripped copy of) that logic locally and assert on the
# copy -- see ADR-0010. These two helpers drive the REAL function to the
# real branch and read back an observable side effect instead:
#
#   * ``run_quick_mode_with_search_error`` makes ``analyze_topic`` raise;
#     the classified, user-facing message is read back from the
#     ``ErrorReportGenerator.generate_error_report(error_message=...)``
#     call the outer ``except Exception as e:`` handler makes.
#   * ``run_quick_mode_with_analyze_result`` makes ``analyze_topic``
#     return a results dict; the post-fallback ``clean_markdown`` text is
#     read back from the ``formatter.format_document_split(...)`` call
#     research_service.py makes right before persisting the report. When
#     the fallback logic gives up entirely, ``ErrorReportGenerator`` fires
#     instead (mirroring the first helper), so both are captured.
# ---------------------------------------------------------------------------


def _egress_and_search_patches():
    """Patches shared by both quick-mode harnesses below."""
    return [
        patch(
            "local_deep_research.config.search_config.factory_get_search",
            MagicMock(return_value=MagicMock()),
        ),
        patch(
            "local_deep_research.security.egress.policy.context_from_snapshot",
            return_value=MagicMock(),
        ),
        patch(
            "local_deep_research.security.egress.run_classification.audit_run_from_snapshot",
            return_value=MagicMock(allowed=True),
        ),
    ]


def run_quick_mode_with_search_error(error_message: str) -> str:
    """Drive run_research_process('quick') with analyze_topic raising
    ``Exception(error_message)`` and return the classified, user-facing
    message research_service builds for it (via ErrorReportGenerator).

    This exercises the REAL two-stage classification in
    research_service.py: the inner ``except Exception as search_error``
    turns the raw message into ``RuntimeError("... (Error type: X)")``,
    and the outer ``except Exception as e`` turns that into the final
    user-facing string, which is what gets persisted via
    ``ErrorReportGenerator.generate_error_report(error_message=...)``.
    """
    system = MagicMock()
    system.analyze_topic.side_effect = Exception(error_message)
    error_gen_instance = MagicMock(
        generate_error_report=MagicMock(return_value="error report")
    )
    patches = _base_run_patches()
    patches[f"{MODULE}.get_llm"] = MagicMock(return_value=MagicMock())
    patches[f"{MODULE}.AdvancedSearchSystem"] = MagicMock(return_value=system)
    patches[f"{MODULE}.ErrorReportGenerator"] = MagicMock(
        return_value=error_gen_instance
    )
    snapshot = {
        "llm.provider": "ollama",
        "llm.model": "m",
        "search.tool": "searxng",
    }
    with ExitStack() as stack:
        for cm in _egress_and_search_patches():
            stack.enter_context(cm)
        for target, mock_obj in patches.items():
            stack.enter_context(patch(target, mock_obj))
        _get_raw_run_research_process()(
            1,
            "test query",
            "quick",
            username="user1",
            settings_snapshot=snapshot,
            search_engine="searxng",
        )

    assert error_gen_instance.generate_error_report.called, (
        "ErrorReportGenerator.generate_error_report was never called -- "
        "the search-error path did not run as expected"
    )
    return error_gen_instance.generate_error_report.call_args.kwargs[
        "error_message"
    ]


def run_quick_mode_with_analyze_result(results: dict) -> dict:
    """Drive run_research_process('quick') with analyze_topic returning
    ``results`` and report back what happened to it.

    Returns a dict with exactly one of:
      * ``{"error_report_message": <str>}`` -- the fallback logic could
        not recover; ErrorReportGenerator ran. Checked first because,
        when it fires, its (mocked) return value is what
        ``clean_markdown`` ends up holding too -- so this branch must
        take priority over the formatter-call check below or a fully-
        exhausted-fallback case would be misreported as recovered.
      * ``{"clean_markdown": <str>}`` -- the fallback logic recovered
        (or there was no error to begin with) and this is the text handed
        to the citation formatter for the final report.
    """
    system = MagicMock()
    system.analyze_topic.return_value = results
    system.all_links_of_system = []
    formatter = MagicMock()
    formatter.format_document_split.return_value = ("answer", [], False)
    formatter.apply_inline_hyperlinks.return_value = "answer"
    error_gen_instance = MagicMock(
        generate_error_report=MagicMock(return_value="error report")
    )
    patches = _base_run_patches()
    patches[f"{MODULE}.get_llm"] = MagicMock(return_value=MagicMock())
    patches[f"{MODULE}.AdvancedSearchSystem"] = MagicMock(return_value=system)
    patches[f"{MODULE}.get_citation_formatter"] = MagicMock(
        return_value=formatter
    )
    patches[f"{MODULE}.ErrorReportGenerator"] = MagicMock(
        return_value=error_gen_instance
    )
    snapshot = {
        "llm.provider": "ollama",
        "llm.model": "m",
        "search.tool": "searxng",
    }
    with ExitStack() as stack:
        for cm in _egress_and_search_patches():
            stack.enter_context(cm)
        for target, mock_obj in patches.items():
            stack.enter_context(patch(target, mock_obj))
        _get_raw_run_research_process()(
            1,
            "test query",
            "quick",
            username="user1",
            settings_snapshot=snapshot,
            search_engine="searxng",
        )

    if error_gen_instance.generate_error_report.called:
        return {
            "error_report_message": (
                error_gen_instance.generate_error_report.call_args.kwargs[
                    "error_message"
                ]
            )
        }
    if formatter.format_document_split.called:
        return {
            "clean_markdown": formatter.format_document_split.call_args[0][0]
        }
    raise AssertionError(
        "neither the citation formatter nor ErrorReportGenerator ran -- "
        "the quick-mode output path did not complete as expected"
    )