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.

19.2 KB
Raw Blame
"""Tests for pure validation functions in local_deep_research.mcp.server."""

from unittest.mock import patch

import pytest

# Skip all tests if MCP package is not installed
from tests.mcp_sdk import is_mcp_installed

MCP_AVAILABLE = is_mcp_installed()

pytestmark = pytest.mark.skipif(
    not MCP_AVAILABLE, reason="MCP package not installed"
)


def _import_server():
    """Lazy import to avoid collection-time failures when mcp is missing."""
    from local_deep_research.mcp.server import (
        ValidationError,
        _COLLECTION_NAME_RE,
        _build_settings_overrides,
        _classify_error,
        _error_result,
        _validate_iterations,
        _validate_max_results,
        _validate_query,
        _validate_questions_per_iteration,
        _validate_range,
        _validate_search_engine,
        _validate_searches_per_section,
        _validate_temperature,
    )

    return {
        "ValidationError": ValidationError,
        "_COLLECTION_NAME_RE": _COLLECTION_NAME_RE,
        "_build_settings_overrides": _build_settings_overrides,
        "_classify_error": _classify_error,
        "_error_result": _error_result,
        "_validate_iterations": _validate_iterations,
        "_validate_max_results": _validate_max_results,
        "_validate_query": _validate_query,
        "_validate_questions_per_iteration": _validate_questions_per_iteration,
        "_validate_range": _validate_range,
        "_validate_search_engine": _validate_search_engine,
        "_validate_searches_per_section": _validate_searches_per_section,
        "_validate_temperature": _validate_temperature,
    }


# ---------------------------------------------------------------------------
# _classify_error
# ---------------------------------------------------------------------------


class TestClassifyError:
    """Tests for _classify_error."""

    @pytest.mark.parametrize(
        "msg, expected",
        [
            ("503 Service Unavailable", "service_unavailable"),
            ("server unavailable", "service_unavailable"),
            ("404 Not Found", "model_not_found"),
            ("resource not found", "model_not_found"),
            ("API key invalid", "auth_error"),
            ("authentication failed", "auth_error"),
            ("unauthorized access", "auth_error"),
            ("401 Unauthorized", "auth_error"),
            ("connection timeout", "timeout"),
            ("request timed out", "timeout"),
            ("rate limit exceeded", "rate_limit"),
            ("429 Too Many", "rate_limit"),
            ("connection refused", "connection_error"),
            ("validation failed", "validation_error"),
            ("invalid parameter", "validation_error"),
            ("some other error", "unknown"),
            ("", "unknown"),
        ],
    )
    def test_classification(self, msg, expected):
        srv = _import_server()
        assert srv["_classify_error"](msg) == expected


# ---------------------------------------------------------------------------
# _error_result
# ---------------------------------------------------------------------------


class TestErrorResult:
    """Tests for the shared MCP tool error response helper."""

    def test_classifies_error_and_uses_complete_operation_wording(self):
        srv = _import_server()
        result = srv["_error_result"](
            RuntimeError("API key invalid"),
            operation="Quick research failed",
        )
        assert result == {
            "status": "error",
            "error": (
                "Quick research failed (auth_error). "
                "Check server logs for details."
            ),
            "error_type": "auth_error",
        }

    def test_preserves_validation_message_and_explicit_type(self):
        srv = _import_server()
        result = srv["_error_result"](
            srv["ValidationError"]("Query cannot be empty"),
            error_type="validation_error",
        )
        assert result == {
            "status": "error",
            "error": "Query cannot be empty",
            "error_type": "validation_error",
        }

    def test_preserves_leading_failed_to_wording(self):
        srv = _import_server()
        result = srv["_error_result"](
            RuntimeError("503 Service Unavailable"),
            operation="Failed to list strategies",
        )
        assert result == {
            "status": "error",
            "error": (
                "Failed to list strategies (service_unavailable). "
                "Check server logs for details."
            ),
            "error_type": "service_unavailable",
        }


# ---------------------------------------------------------------------------
# _validate_range
# ---------------------------------------------------------------------------


class TestValidateRange:
    """Tests for the generic numeric range validator."""

    def test_none_allowed_by_default(self):
        srv = _import_server()
        assert srv["_validate_range"](None, "Value", 1, 10) is None

    def test_none_rejected_when_required(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="Value is required"):
            srv["_validate_range"](None, "Value", 1, 10, allow_none=False)

    def test_bounds_are_inclusive(self):
        srv = _import_server()
        assert srv["_validate_range"](1, "Value", 1, 10) == 1
        assert srv["_validate_range"](10, "Value", 1, 10) == 10

    def test_optional_type_conversion(self):
        srv = _import_server()
        result = srv["_validate_range"](
            1,
            "Value",
            0.0,
            2.0,
            type_check=(int, float),
            convert_to=float,
        )
        assert result == 1.0
        assert isinstance(result, float)


# ---------------------------------------------------------------------------
# _validate_query
# ---------------------------------------------------------------------------


class TestValidateQuery:
    """Tests for _validate_query."""

    def test_empty_string_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="empty"):
            srv["_validate_query"]("")

    def test_whitespace_only_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="empty"):
            srv["_validate_query"]("   ")

    def test_none_raises(self):
        srv = _import_server()
        with pytest.raises((AttributeError, srv["ValidationError"])):
            srv["_validate_query"](None)

    def test_valid_query_returned(self):
        srv = _import_server()
        assert srv["_validate_query"]("valid query") == "valid query"

    def test_strips_whitespace(self):
        srv = _import_server()
        assert srv["_validate_query"]("  padded  ") == "padded"

    def test_exceeds_max_length(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="exceeds maximum"):
            srv["_validate_query"]("x" * 10001)

    def test_exactly_at_max_length(self):
        srv = _import_server()
        query = "x" * 10000
        assert srv["_validate_query"](query) == query


# ---------------------------------------------------------------------------
# _validate_iterations
# ---------------------------------------------------------------------------


class TestValidateIterations:
    """Tests for _validate_iterations."""

    def test_none_returns_none(self):
        srv = _import_server()
        assert srv["_validate_iterations"](None) is None

    def test_valid_value(self):
        srv = _import_server()
        assert srv["_validate_iterations"](5) == 5

    def test_zero_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="positive integer"):
            srv["_validate_iterations"](0)

    def test_negative_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="positive integer"):
            srv["_validate_iterations"](-1)

    def test_exceeds_default_max(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="cannot exceed 20"):
            srv["_validate_iterations"](21)

    def test_at_default_max(self):
        srv = _import_server()
        assert srv["_validate_iterations"](20) == 20

    def test_minimum_value(self):
        srv = _import_server()
        assert srv["_validate_iterations"](1) == 1

    def test_string_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_iterations"]("5")

    def test_float_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_iterations"](1.5)

    def test_custom_max_val(self):
        srv = _import_server()
        assert srv["_validate_iterations"](10, max_val=10) == 10
        with pytest.raises(srv["ValidationError"], match="cannot exceed 10"):
            srv["_validate_iterations"](11, max_val=10)


# ---------------------------------------------------------------------------
# _validate_questions_per_iteration
# ---------------------------------------------------------------------------


class TestValidateQuestionsPerIteration:
    """Tests for _validate_questions_per_iteration."""

    def test_none_returns_none(self):
        srv = _import_server()
        assert srv["_validate_questions_per_iteration"](None) is None

    def test_valid_value(self):
        srv = _import_server()
        assert srv["_validate_questions_per_iteration"](5) == 5

    def test_zero_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_questions_per_iteration"](0)

    def test_exceeds_max(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="cannot exceed 10"):
            srv["_validate_questions_per_iteration"](11)

    def test_at_max(self):
        srv = _import_server()
        assert srv["_validate_questions_per_iteration"](10) == 10


# ---------------------------------------------------------------------------
# _validate_max_results
# ---------------------------------------------------------------------------


class TestValidateMaxResults:
    """Tests for _validate_max_results."""

    def test_valid_value(self):
        srv = _import_server()
        assert srv["_validate_max_results"](10) == 10

    def test_zero_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_max_results"](0)

    def test_negative_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_max_results"](-1)

    def test_exceeds_max(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"], match="cannot exceed 100"):
            srv["_validate_max_results"](101)

    def test_at_max(self):
        srv = _import_server()
        assert srv["_validate_max_results"](100) == 100

    def test_string_raises(self):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_max_results"]("10")


# ---------------------------------------------------------------------------
# _validate_searches_per_section
# ---------------------------------------------------------------------------


class TestValidateSearchesPerSection:
    """Tests for _validate_searches_per_section."""

    @pytest.mark.parametrize("value", [1, 10])
    def test_boundaries_are_accepted(self, value):
        srv = _import_server()
        assert srv["_validate_searches_per_section"](value) == value

    @pytest.mark.parametrize("value", [0, -1, "2", 2.5, None])
    def test_invalid_values_raise(self, value):
        srv = _import_server()
        with pytest.raises(srv["ValidationError"]):
            srv["_validate_searches_per_section"](value)


# ---------------------------------------------------------------------------
# _validate_temperature
# ---------------------------------------------------------------------------


class TestValidateTemperature:
    """Tests for temperature bounds, type checks, and normalization."""

    def test_none_returns_none(self):
        srv = _import_server()
        assert srv["_validate_temperature"](None) is None

    @pytest.mark.parametrize("value", [0.0, 2.0])
    def test_boundaries_are_accepted(self, value):
        srv = _import_server()
        assert srv["_validate_temperature"](value) == value

    def test_integer_is_normalized_to_float(self):
        srv = _import_server()
        result = srv["_validate_temperature"](1)
        assert result == 1.0
        assert isinstance(result, float)

    @pytest.mark.parametrize("value", [-0.1, 2.1])
    def test_out_of_range_preserves_combined_message(self, value):
        srv = _import_server()
        with pytest.raises(
            srv["ValidationError"],
            match=r"Temperature must be between 0\.0 and 2\.0",
        ):
            srv["_validate_temperature"](value)

    def test_nan_is_rejected(self):
        srv = _import_server()
        with pytest.raises(
            srv["ValidationError"],
            match=r"Temperature must be between 0\.0 and 2\.0",
        ):
            srv["_validate_temperature"](float("nan"))

    def test_string_raises_number_message(self):
        srv = _import_server()
        with pytest.raises(
            srv["ValidationError"], match="Temperature must be a number"
        ):
            srv["_validate_temperature"]("1.0")


# ---------------------------------------------------------------------------
# _build_settings_overrides
# ---------------------------------------------------------------------------


class TestBuildSettingsOverrides:
    """Tests for _build_settings_overrides."""

    @patch(
        "local_deep_research.mcp.server._validate_strategy",
        return_value="standard",
    )
    @patch(
        "local_deep_research.mcp.server._validate_search_engine",
        return_value="google",
    )
    def test_all_overrides(self, mock_engine, mock_strategy):
        srv = _import_server()
        result = srv["_build_settings_overrides"](
            search_engine="google",
            strategy="standard",
            iterations=5,
            questions_per_iteration=3,
            temperature=0.7,
        )
        assert result["search.tool"] == "google"
        assert result["search.search_strategy"] == "standard"
        assert result["search.iterations"] == 5
        assert result["search.questions_per_iteration"] == 3
        assert result["llm.temperature"] == 0.7

    @patch(
        "local_deep_research.mcp.server._validate_strategy",
        return_value=None,
    )
    @patch(
        "local_deep_research.mcp.server._validate_search_engine",
        return_value=None,
    )
    def test_all_none_returns_empty(self, mock_engine, mock_strategy):
        srv = _import_server()
        result = srv["_build_settings_overrides"]()
        assert result == {}

    @patch(
        "local_deep_research.mcp.server._validate_strategy",
        return_value=None,
    )
    @patch(
        "local_deep_research.mcp.server._validate_search_engine",
        return_value=None,
    )
    def test_only_some_params(self, mock_engine, mock_strategy):
        srv = _import_server()
        result = srv["_build_settings_overrides"](iterations=3, temperature=0.5)
        assert result == {
            "search.iterations": 3,
            "llm.temperature": 0.5,
        }
        assert "search.tool" not in result
        assert "search.search_strategy" not in result
        assert "search.questions_per_iteration" not in result

    @patch(
        "local_deep_research.mcp.server._validate_strategy",
        return_value=None,
    )
    @patch(
        "local_deep_research.mcp.server._validate_search_engine",
        return_value=None,
    )
    def test_engine_validates_to_none_not_added(
        self, mock_engine, mock_strategy
    ):
        srv = _import_server()
        result = srv["_build_settings_overrides"](search_engine="")
        assert "search.tool" not in result

    @patch(
        "local_deep_research.mcp.server._validate_strategy",
        return_value=None,
    )
    @patch(
        "local_deep_research.mcp.server._validate_search_engine",
        return_value=None,
    )
    def test_temperature_is_validated_and_normalized(
        self, mock_engine, mock_strategy
    ):
        srv = _import_server()
        result = srv["_build_settings_overrides"](temperature=1)
        assert result["llm.temperature"] == 1.0
        assert isinstance(result["llm.temperature"], float)


# ---------------------------------------------------------------------------
# _COLLECTION_NAME_RE
# ---------------------------------------------------------------------------


class TestCollectionNameRegex:
    """Tests for _COLLECTION_NAME_RE collection name validation."""

    def test_path_traversal_rejected(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("../etc/passwd") is None

    def test_too_long_rejected(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("a" * 101) is None

    def test_valid_name_with_hyphens_and_underscores(self):
        srv = _import_server()
        assert (
            srv["_COLLECTION_NAME_RE"].match("my-collection_name") is not None
        )

    def test_valid_alphanumeric_with_spaces(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("My Collection 42") is not None

    def test_exactly_100_chars_accepted(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("a" * 100) is not None

    def test_empty_string_rejected(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("") is None

    def test_special_chars_rejected(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("col;drop table") is None

    def test_tab_rejected(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("col\tname") is None

    def test_newline_rejected(self):
        srv = _import_server()
        assert srv["_COLLECTION_NAME_RE"].match("col\nname") is None


# ---------------------------------------------------------------------------
# _validate_search_engine
# ---------------------------------------------------------------------------


class TestValidateSearchEngine:
    """Tests for _validate_search_engine."""

    def test_none_returns_none(self):
        srv = _import_server()
        assert srv["_validate_search_engine"](None) is None

    def test_empty_string_returns_none(self):
        srv = _import_server()
        assert srv["_validate_search_engine"]("") is None

    def test_whitespace_only_returns_none(self):
        srv = _import_server()
        assert srv["_validate_search_engine"]("   ") is None

    @patch(
        "local_deep_research.web_search_engines.search_engines_config.search_config",
        side_effect=RuntimeError("config unavailable"),
    )
    @patch("local_deep_research.mcp.server.create_settings_snapshot")
    def test_config_load_failure_raises_validation_error(
        self, mock_settings, mock_config
    ):
        srv = _import_server()
        with pytest.raises(
            srv["ValidationError"], match="engine configuration unavailable"
        ):
            srv["_validate_search_engine"]("some_engine")