~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 research_library/utils/__init__.py — utility functions."""
import hashlib # noqa: E402
from unittest.mock import MagicMock, patch # noqa: E402
# ---------------------------------------------------------------------------
# get_url_hash
# ---------------------------------------------------------------------------
class TestGetUrlHash:
"""Tests for get_url_hash()."""
def test_returns_sha256_hex(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
# Golden vector: normalize("https://example.com/page") ==
# "example.com/page" (scheme stripped, lowercased). Computed once
# and pinned so the test fails if the normalization drifts — the
# previous version computed the expectation with the function under
# test and could never fail.
url = "https://example.com/page"
expected = hashlib.sha256(b"example.com/page").hexdigest()
assert expected == (
"d641f3ecfa3d1007cb7e145a76a12b4d969513a43ec173d57480df068534f9b8"
)
assert get_url_hash(url) == expected
def test_case_insensitive(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("HTTPS://EXAMPLE.COM") == get_url_hash(
"https://example.com"
)
def test_different_urls_different_hashes(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("https://a.com") != get_url_hash("https://b.com")
def test_empty_url(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
result = get_url_hash("")
assert isinstance(result, str)
assert len(result) == 64 # SHA256 hex length
# ---------------------------------------------------------------------------
# normalize_url_for_hash / B2 (issue #6758): URL-hash normalization
# ---------------------------------------------------------------------------
class TestNormalizeUrlForHash:
"""B2: the same article with tracking params, fragments, default ports,
userinfo, scheme or www variance must hash alike; genuinely different
URLs must not be merged."""
def test_tracking_params_are_stripped(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash(
"https://example.com/paper?utm_source=newsletter&utm_medium=email"
) == get_url_hash("https://example.com/paper")
assert get_url_hash(
"https://example.com/paper?fbclid=abc123"
) == get_url_hash("https://example.com/paper")
assert get_url_hash(
"https://example.com/paper?gclid=xyz&page=2"
) == get_url_hash("https://example.com/paper?page=2")
def test_fragments_are_stripped(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash(
"https://example.com/paper#section-2"
) == get_url_hash("https://example.com/paper")
def test_default_ports_are_stripped(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("https://example.com:443/paper") == get_url_hash(
"https://example.com/paper"
)
assert get_url_hash("http://example.com:80/paper") == get_url_hash(
"http://example.com/paper"
)
def test_userinfo_is_stripped(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash(
"https://user:[email protected]/paper"
) == get_url_hash("https://example.com/paper")
def test_scheme_and_www_variants_match(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("http://example.com/paper") == get_url_hash(
"https://example.com/paper"
)
assert get_url_hash("https://www.example.com/paper") == get_url_hash(
"https://example.com/paper"
)
def test_query_param_order_does_not_matter(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("https://example.com/s?z=1&a=2") == get_url_hash(
"https://example.com/s?a=2&z=1"
)
def test_meaningful_query_params_are_preserved(self):
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("https://example.com/paper?page=2") != get_url_hash(
"https://example.com/paper?page=3"
)
assert get_url_hash("https://example.com/paper?page=2") != get_url_hash(
"https://example.com/paper"
)
def test_percent_encoding_spellings_stay_distinct(self):
"""B2 review: ``+`` vs ``%20`` and ``;`` vs ``%3B`` must NOT merge.
A server may treat ``+``/``;`` literally, so merging would link a
resource to the wrong document (silent wrong-content link).
``canonical_url_key`` preserves raw query spellings for this reason.
"""
from local_deep_research.research_library.utils import get_url_hash # noqa: E402
assert get_url_hash("https://example.com/s?q=a+b") != get_url_hash(
"https://example.com/s?q=a%20b"
)
assert get_url_hash("https://example.com/s?a=1;b=2") != get_url_hash(
"https://example.com/s?a=1%3Bb=2"
)
# ---------------------------------------------------------------------------
# get_library_storage_path
# ---------------------------------------------------------------------------
class TestGetLibraryStoragePath:
"""Tests for get_library_storage_path()."""
@patch("local_deep_research.utilities.db_utils.get_settings_manager")
@patch("local_deep_research.research_library.utils.get_library_directory")
def test_user_isolation_mode(self, mock_lib_dir, mock_get_sm, tmp_path):
mock_lib_dir.return_value = tmp_path / "library"
mock_sm = MagicMock()
mock_sm.get_setting.side_effect = lambda key, default: {
"research_library.storage_path": str(tmp_path / "library"),
"research_library.shared_library": False,
}.get(key, default)
mock_get_sm.return_value = mock_sm
from local_deep_research.research_library.utils import ( # noqa: E402
get_library_storage_path,
)
result = get_library_storage_path("alice")
assert result == tmp_path / "library" / "alice"
assert result.exists()
@patch("local_deep_research.utilities.db_utils.get_settings_manager")
@patch("local_deep_research.research_library.utils.get_library_directory")
def test_shared_library_mode(
self, mock_lib_dir, mock_get_sm, tmp_path, monkeypatch
):
# Shared mode drops per-user isolation; it only takes effect when the
# operator has enabled the env gate.
monkeypatch.setattr(
"local_deep_research.research_library.utils."
"_shared_library_allowed",
lambda: True,
)
mock_lib_dir.return_value = tmp_path / "library"
mock_sm = MagicMock()
mock_sm.get_setting.side_effect = lambda key, default: {
"research_library.storage_path": str(tmp_path / "library"),
"research_library.shared_library": True,
}.get(key, default)
mock_get_sm.return_value = mock_sm
from local_deep_research.research_library.utils import ( # noqa: E402
get_library_storage_path,
)
result = get_library_storage_path("alice")
# Shared mode: no username subdirectory
assert result == tmp_path / "library"
assert result.exists()
@patch("local_deep_research.utilities.db_utils.get_settings_manager")
@patch("local_deep_research.research_library.utils.get_library_directory")
def test_creates_directory_if_not_exists(
self, mock_lib_dir, mock_get_sm, tmp_path
):
base = tmp_path / "new_dir"
mock_lib_dir.return_value = base
mock_sm = MagicMock()
mock_sm.get_setting.side_effect = lambda key, default: {
"research_library.storage_path": str(base),
"research_library.shared_library": False,
}.get(key, default)
mock_get_sm.return_value = mock_sm
from local_deep_research.research_library.utils import ( # noqa: E402
get_library_storage_path,
)
result = get_library_storage_path("bob")
assert result.exists()
assert result.is_dir()
# ---------------------------------------------------------------------------
# open_file_location
# ---------------------------------------------------------------------------
class TestOpenFileLocation:
"""Tests for open_file_location()."""
@patch("local_deep_research.research_library.utils.PathValidator")
@patch("local_deep_research.research_library.utils.subprocess.run")
@patch("local_deep_research.research_library.utils.sys")
def test_linux_success(self, mock_sys, mock_run, mock_validator, tmp_path):
mock_sys.platform = "linux"
mock_validator.validate_local_filesystem_path.return_value = (
tmp_path / "file.txt"
)
mock_run.return_value = MagicMock(returncode=0)
from local_deep_research.research_library.utils import ( # noqa: E402
open_file_location,
)
assert open_file_location(str(tmp_path / "file.txt")) is True
mock_run.assert_called_once_with(
["xdg-open", str(tmp_path)],
capture_output=True,
text=True,
shell=False,
timeout=10,
)
@patch("local_deep_research.research_library.utils.PathValidator")
@patch("local_deep_research.research_library.utils.subprocess.run")
@patch("local_deep_research.research_library.utils.sys")
def test_linux_failure(self, mock_sys, mock_run, mock_validator, tmp_path):
mock_sys.platform = "linux"
mock_validator.validate_local_filesystem_path.return_value = (
tmp_path / "file.txt"
)
mock_run.return_value = MagicMock(returncode=1, stderr="error")
from local_deep_research.research_library.utils import ( # noqa: E402
open_file_location,
)
assert open_file_location(str(tmp_path / "file.txt")) is False
@patch("local_deep_research.research_library.utils.PathValidator")
@patch("local_deep_research.research_library.utils.subprocess.run")
@patch("local_deep_research.research_library.utils.sys")
def test_macos_success(self, mock_sys, mock_run, mock_validator, tmp_path):
mock_sys.platform = "darwin"
mock_validator.validate_local_filesystem_path.return_value = (
tmp_path / "file.txt"
)
mock_run.return_value = MagicMock(returncode=0)
from local_deep_research.research_library.utils import ( # noqa: E402
open_file_location,
)
assert open_file_location(str(tmp_path / "file.txt")) is True
mock_run.assert_called_once_with(
["open", str(tmp_path)],
capture_output=True,
text=True,
shell=False,
timeout=10,
)
@patch("local_deep_research.research_library.utils.PathValidator")
def test_path_validation_failure(self, mock_validator):
mock_validator.validate_local_filesystem_path.side_effect = ValueError(
"blocked"
)
from local_deep_research.research_library.utils import ( # noqa: E402
open_file_location,
)
assert open_file_location("/etc/passwd") is False
# ---------------------------------------------------------------------------
# get_absolute_library_path
# ---------------------------------------------------------------------------
class TestLibraryPathConversions:
"""Tests for get_absolute_library_path."""
@patch(
"local_deep_research.research_library.utils.get_library_storage_path"
)
def test_absolute_path_from_relative(self, mock_storage, tmp_path):
library_root = tmp_path / "library" / "alice"
mock_storage.return_value = library_root
from local_deep_research.research_library.utils import ( # noqa: E402
get_absolute_library_path,
)
result = get_absolute_library_path("subdir/file.pdf", "alice")
assert result == library_root / "subdir" / "file.pdf"
# ---------------------------------------------------------------------------
# get_absolute_path_from_settings
# ---------------------------------------------------------------------------
class TestGetAbsolutePathFromSettings:
"""Tests for get_absolute_path_from_settings."""
@patch("local_deep_research.utilities.db_utils.get_settings_manager")
@patch("local_deep_research.research_library.utils.get_library_directory")
def test_with_relative_path(self, mock_lib_dir, mock_get_sm, tmp_path):
mock_lib_dir.return_value = tmp_path / "library"
mock_sm = MagicMock()
mock_sm.get_setting.return_value = str(tmp_path / "library")
mock_get_sm.return_value = mock_sm
from local_deep_research.research_library.utils import ( # noqa: E402
get_absolute_path_from_settings,
)
result = get_absolute_path_from_settings("docs/file.pdf", "alice")
assert result == tmp_path / "library" / "alice" / "docs" / "file.pdf"
@patch("local_deep_research.utilities.db_utils.get_settings_manager")
@patch("local_deep_research.research_library.utils.get_library_directory")
def test_empty_relative_path_returns_root(
self, mock_lib_dir, mock_get_sm, tmp_path
):
mock_lib_dir.return_value = tmp_path / "library"
mock_sm = MagicMock()
mock_sm.get_setting.return_value = str(tmp_path / "library")
mock_get_sm.return_value = mock_sm
from local_deep_research.research_library.utils import ( # noqa: E402
get_absolute_path_from_settings,
)
result = get_absolute_path_from_settings("")
assert result == tmp_path / "library"
# ---------------------------------------------------------------------------
# handle_api_error
# ---------------------------------------------------------------------------
class TestHandleApiError:
"""Tests for handle_api_error."""
def test_returns_generic_error_message(self):
import json
from local_deep_research.research_library.utils import handle_api_error # noqa: E402
response = handle_api_error(
"test operation", ValueError("secret details"), 500
)
assert response.status_code == 500
data = json.loads(response.body)
assert data["success"] is False
# Must NOT leak the exception message
assert "secret details" not in data["error"]
assert "internal error" in data["error"].lower()
def test_custom_status_code(self):
from local_deep_research.research_library.utils import handle_api_error # noqa: E402
response = handle_api_error("op", RuntimeError("err"), 503)
assert response.status_code == 503
def test_default_status_code_is_500(self):
from local_deep_research.research_library.utils import handle_api_error # noqa: E402
response = handle_api_error("op", RuntimeError("err"))
assert response.status_code == 500
# ---------------------------------------------------------------------------
# ensure_in_collection
# ---------------------------------------------------------------------------
class TestEnsureInCollection:
"""Tests for ensure_in_collection()."""
def test_returns_existing_row_without_adding(self):
from local_deep_research.research_library.utils import (
ensure_in_collection,
)
existing = MagicMock(name="existing_DocumentCollection")
session = MagicMock()
session.query.return_value.filter_by.return_value.first.return_value = (
existing
)
result = ensure_in_collection(session, "doc-1", "coll-1")
assert result is existing
session.query.return_value.filter_by.assert_called_once_with(
document_id="doc-1", collection_id="coll-1"
)
session.add.assert_not_called()
def test_creates_and_adds_when_missing(self):
from local_deep_research.research_library.utils import (
ensure_in_collection,
)
session = MagicMock()
session.query.return_value.filter_by.return_value.first.return_value = (
None
)
result = ensure_in_collection(session, "doc-2", "coll-2")
session.add.assert_called_once_with(result)
assert result.document_id == "doc-2"
assert result.collection_id == "coll-2"
assert result.indexed is False