~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
"""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")