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.

test(zotero): cover client and sync-service edge branches (#6157)

LearningCircuitc96329bc1d8c
diff --git a/tests/research_library/zotero/test_client_edge_failures.py b/tests/research_library/zotero/test_client_edge_failures.py
new file mode 100644
index 0000000000..aaf05be186
--- /dev/null
+++ b/tests/research_library/zotero/test_client_edge_failures.py
@@ -0,0 +1,281 @@
+"""WHY: Lock Zotero client failure and pagination edges without network I/O."""
+
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+from pytest_mock import MockerFixture
+
+from local_deep_research.research_library.zotero.client import (
+ ZoteroClient,
+ ZoteroError,
+ ZoteroTransientError,
+ _html_to_text,
+)
+
+
+def _client(mocker: MockerFixture) -> ZoteroClient:
+ client = ZoteroClient("key", "user", "123")
+ client.session = mocker.MagicMock()
+ return client
+
+
+def _response(mocker: MockerFixture, status: int = 200) -> MagicMock:
+ response = mocker.MagicMock()
+ response.status_code = status
+ response.headers = {}
+ response.content = b""
+ return response
+
+
+def test_html_and_item_properties_handle_empty_values(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ item = mocker.MagicMock(data={"title": None})
+
+ assert _html_to_text("") == ""
+ assert client._library_version(_response(mocker)) == 0
+ from local_deep_research.research_library.zotero.client import ZoteroItem
+
+ assert ZoteroItem("K", 1, "book", item.data).title == ""
+
+
+def test_context_manager_closes_session_even_when_close_raises(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ session = client.session
+ session.close.side_effect = RuntimeError("close failed")
+
+ with client as entered:
+ assert entered is client
+
+ session.close.assert_called_once_with()
+ assert client.session is None
+
+
+def test_context_manager_does_not_suppress_body_error(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+
+ with pytest.raises(RuntimeError, match="body failed"), client:
+ raise RuntimeError("body failed")
+
+
+ "error_type", [requests.Timeout, requests.ConnectionError]
+)
+def test_request_retries_network_errors_then_raises_transient(
+ mocker: MockerFixture, error_type: type[requests.RequestException]
+) -> None:
+ client = _client(mocker)
+ client.session.get.side_effect = error_type("offline")
+ sleep = mocker.patch(
+ "local_deep_research.research_library.zotero.client.time.sleep"
+ )
+
+ with pytest.raises(ZoteroTransientError, match=error_type.__name__):
+ client.test_connection()
+
+ assert client.session.get.call_count == 4
+ assert sleep.call_count == 3
+
+
+def test_request_rejects_unhandled_http_status(mocker: MockerFixture) -> None:
+ client = _client(mocker)
+ client.session.get.return_value = _response(mocker, 418)
+
+ with pytest.raises(ZoteroError, match="HTTP 418"):
+ client.test_connection()
+
+
+def test_library_version_and_key_info_tolerate_malformed_responses(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ response = _response(mocker)
+ response.headers = {"Last-Modified-Version": "not-an-integer"}
+ response.json.side_effect = ValueError("not json")
+ client.session.get.return_value = response
+
+ assert client._library_version(response) == 0
+ assert client.get_current_key_info() == {}
+
+
+def test_groups_support_empty_and_paginated_results(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ key_info = _response(mocker)
+ key_info.json.return_value = {"userID": 9}
+ full = _response(mocker)
+ full.json.return_value = [
+ {"id": index, "data": {"name": f"G{index}"}} for index in range(100)
+ ]
+ empty = _response(mocker)
+ empty.json.return_value = []
+ client.session.get.side_effect = [key_info, full, empty]
+
+ groups = client.get_groups()
+
+ assert len(groups) == 100
+ assert client.session.get.call_args_list[2].kwargs["params"]["start"] == 100
+
+
+def test_groups_pagination_cap_raises(mocker: MockerFixture) -> None:
+ client = _client(mocker)
+ key_info = _response(mocker)
+ key_info.json.return_value = {"userID": 9}
+ full = _response(mocker)
+ full.json.return_value = [{"id": index, "data": {}} for index in range(100)]
+ client.session.get.side_effect = [key_info, full, full]
+ mocker.patch(
+ "local_deep_research.research_library.zotero.client._MAX_PAGES", 1
+ )
+
+ with pytest.raises(ZoteroError, match="safety cap"):
+ client.get_groups()
+
+
+def test_collection_name_returns_name_or_none(mocker: MockerFixture) -> None:
+ client = _client(mocker)
+ response = _response(mocker)
+ response.json.return_value = {"data": {"name": "Reading"}}
+ client.session.get.return_value = response
+ assert client.get_collection_name("A/B") == "Reading"
+
+ client.session.get.return_value = _response(mocker, 404)
+ assert client.get_collection_name("missing") is None
+
+
+def test_versions_handle_invalid_counts_versions_and_total_stop(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ response = _response(mocker)
+ response.headers = {
+ "Total-Results": "invalid",
+ "Last-Modified-Version": "invalid",
+ }
+ response.json.return_value = {"BAD": "invalid"}
+ client.session.get.return_value = response
+ assert client.get_top_item_versions() == ({"BAD": 0}, 0)
+
+ full = _response(mocker)
+ full.headers = {"Total-Results": "100"}
+ full.json.return_value = {f"K{index}": index for index in range(100)}
+ client.session.get.reset_mock()
+ client.session.get.return_value = full
+ versions, _ = client.get_top_item_versions()
+ assert len(versions) == 100
+ client.session.get.assert_called_once()
+
+
+def test_versions_and_children_pagination_caps_raise(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ versions = _response(mocker)
+ versions.json.return_value = {f"K{index}": 1 for index in range(100)}
+ children = _response(mocker)
+ children.json.return_value = [{"key": str(index)} for index in range(100)]
+ mocker.patch(
+ "local_deep_research.research_library.zotero.client._MAX_PAGES", 1
+ )
+
+ client.session.get.return_value = versions
+ with pytest.raises(ZoteroError, match="safety cap"):
+ client.get_top_item_versions()
+ client.session.get.return_value = children
+ with pytest.raises(ZoteroError, match="safety cap"):
+ client.get_children("PARENT")
+
+
+def test_children_paginates_and_annotations_ignore_other_items(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ full = _response(mocker)
+ full.json.return_value = [
+ {"data": {"itemType": "book"}} for _ in range(100)
+ ]
+ short = _response(mocker)
+ short.json.return_value = [{"data": {"itemType": "book"}}]
+ client.session.get.side_effect = [full, short]
+ assert client.get_annotations("ATT") == []
+ assert client.session.get.call_args_list[1].kwargs["params"]["start"] == 100
+
+
+def test_download_redirect_without_location_and_empty_direct_body_return_none(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ client.session.get.side_effect = [_response(mocker, 302), _response(mocker)]
+
+ assert client.download_attachment("A") is None
+ assert client.download_attachment("B") is None
+
+
+def test_local_file_read_handles_missing_and_empty_files(
+ mocker: MockerFixture, tmp_path: Path
+) -> None:
+ missing = tmp_path / "missing.pdf"
+ empty = tmp_path / "empty.pdf"
+ empty.write_bytes(b"")
+
+ assert ZoteroClient._read_local_file(missing.as_uri()) is None
+ assert ZoteroClient._read_local_file(empty.as_uri()) is None
+
+
+ ("outcome", "expected_exception"),
+ [
+ (requests.Timeout("slow"), ZoteroTransientError),
+ (ValueError("blocked"), None),
+ (404, None),
+ (200, None),
+ ],
+)
+def test_unauthenticated_storage_failure_branches(
+ mocker: MockerFixture,
+ outcome: requests.RequestException | ValueError | int,
+ expected_exception: type[ZoteroTransientError] | None,
+) -> None:
+ client = _client(mocker)
+ clean = mocker.MagicMock()
+ clean.__enter__.return_value = clean
+ if isinstance(outcome, BaseException):
+ clean.get.side_effect = outcome
+ else:
+ clean.get.return_value = _response(mocker, outcome)
+ mocker.patch(
+ "local_deep_research.research_library.zotero.client.SafeSession",
+ return_value=clean,
+ )
+
+ if expected_exception:
+ with pytest.raises(expected_exception):
+ client._fetch_file_unauthenticated("https://files.example/file")
+ else:
+ assert (
+ client._fetch_file_unauthenticated("https://files.example/file")
+ is None
+ )
+ clean.get.assert_called_once_with("https://files.example/file", timeout=30)
+
+
+def test_fulltext_handles_invalid_json_and_non_mapping(
+ mocker: MockerFixture,
+) -> None:
+ client = _client(mocker)
+ invalid = _response(mocker)
+ invalid.json.side_effect = ValueError("invalid")
+ sequence = _response(mocker)
+ sequence.json.return_value = ["not", "a", "mapping"]
+ client.session.get.side_effect = [invalid, sequence]
+
+ assert client.get_attachment_fulltext("A") is None
+ assert client.get_attachment_fulltext("B") is None
diff --git a/tests/research_library/zotero/test_sync_service_edge_branches.py b/tests/research_library/zotero/test_sync_service_edge_branches.py
new file mode 100644
index 0000000000..76c2e1091c
--- /dev/null
+++ b/tests/research_library/zotero/test_sync_service_edge_branches.py
@@ -0,0 +1,369 @@
+"""WHY: Exercise Zotero sync recovery branches with isolated stores and clients."""
+
+import uuid
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, contextmanager
+from pathlib import Path
+from typing import Final
+from unittest.mock import MagicMock
+
+import pytest
+from pytest_mock import MockerFixture
+from sqlalchemy.orm import Session
+
+from local_deep_research.database.models.library import (
+ Collection,
+ Document,
+ SourceType,
+)
+from local_deep_research.database.models.zotero import ZoteroItemMap
+from local_deep_research.research_library.zotero.client import (
+ ZoteroAttachment,
+ ZoteroError,
+ ZoteroItem,
+)
+from local_deep_research.research_library.zotero.sync_service import (
+ ZoteroConfig,
+ ZoteroSyncService,
+)
+from local_deep_research.security import UnsafeFilenameError
+
+_SYNC: Final = "local_deep_research.research_library.zotero.sync_service"
+_RAG: Final = (
+ "local_deep_research.research_library.services.library_rag_service"
+)
+
+
+def _session_factory(
+ session: Session,
+) -> Callable[..., AbstractContextManager[Session]]:
+ @contextmanager
+ def _open(*_args: str | None, **_kwargs: str | None) -> Iterator[Session]:
+ yield session
+
+ return _open
+
+
+def _seed_source(session: Session) -> str:
+ source_id = str(uuid.uuid4())
+ session.add(SourceType(id=source_id, name="zotero", display_name="Zotero"))
+ session.commit()
+ return source_id
+
+
+def _patch_session(
+ mocker: MockerFixture, session: Session | MagicMock
+) -> MagicMock:
+ return mocker.patch(
+ f"{_SYNC}.get_user_db_session",
+ side_effect=lambda *_args, **_kwargs: _session_factory(session)(),
+ )
+
+
+def test_get_config_defaults_invalid_interval(mocker: MockerFixture) -> None:
+ settings = mocker.MagicMock()
+ settings.get_setting.side_effect = lambda key, default=None: (
+ "invalid" if key == "zotero.sync_interval_minutes" else default
+ )
+ settings.get_bool_setting.side_effect = lambda _key, default: default
+ session = mocker.MagicMock()
+ _patch_session(mocker, session)
+ mocker.patch(
+ f"{_SYNC}.SettingsManager",
+ return_value=settings,
+ )
+
+ assert ZoteroSyncService("user").get_config().sync_interval_minutes == 360
+
+
+def test_make_client_forwards_config(mocker: MockerFixture) -> None:
+ constructor = mocker.patch(f"{_SYNC}.ZoteroClient")
+ cfg = ZoteroConfig(
+ api_key="key", library_type="group", library_id="7", use_local_api=True
+ )
+
+ ZoteroSyncService("user")._make_client(cfg)
+
+ constructor.assert_called_once_with(
+ api_key="key", library_type="group", library_id="7", local=True
+ )
+
+
+def test_resolve_library_id_caches_probe_error(mocker: MockerFixture) -> None:
+ constructor = mocker.patch(
+ f"{_SYNC}.ZoteroClient",
+ side_effect=ZoteroError("denied"),
+ )
+ service = ZoteroSyncService("user")
+ cfg = ZoteroConfig(api_key="key", library_id="name")
+
+ assert service._resolve_library_id(cfg) is not None
+ assert service._resolve_library_id(cfg) is not None
+ constructor.assert_called_once()
+
+
+def test_public_operations_surface_resolution_and_client_errors(
+ mocker: MockerFixture,
+) -> None:
+ service = ZoteroSyncService("user")
+ mocker.patch.object(
+ service, "get_config", return_value=ZoteroConfig(api_key="key")
+ )
+ mocker.patch.object(service, "_resolve_library_id", return_value="bad id")
+ assert service.test_connection() == {"success": False, "error": "bad id"}
+ with pytest.raises(ZoteroError, match="bad id"):
+ service.list_collections()
+ with pytest.raises(ZoteroError, match="bad id"):
+ service.list_groups()
+
+ mocker.patch.object(service, "_resolve_library_id", return_value=None)
+ client = mocker.MagicMock()
+ client.__enter__.return_value = client
+ mocker.patch.object(service, "_make_client", return_value=client)
+ client.get_collections.return_value = [{"key": "C"}]
+ client.get_groups.return_value = [{"id": "G"}]
+ assert service.list_collections() == [{"key": "C"}]
+ assert service.list_groups() == [{"id": "G"}]
+
+ client.test_connection.side_effect = ZoteroError("secret failure")
+ assert service.test_connection()["success"] is False
+
+
+def test_sync_all_rejects_unconfigured_and_resolution_failure(
+ mocker: MockerFixture,
+) -> None:
+ service = ZoteroSyncService("user")
+ mocker.patch.object(
+ service, "get_config", return_value=ZoteroConfig(enabled=False)
+ )
+ assert service.sync_all()["success"] is False
+
+ mocker.patch.object(
+ service,
+ "get_config",
+ return_value=ZoteroConfig(api_key="key", library_id="7"),
+ )
+ mocker.patch.object(
+ service, "_resolve_library_id", return_value="unresolvable"
+ )
+ assert service.sync_all() == {"success": False, "error": "unresolvable"}
+
+
+def test_sync_one_reindexed_update_cleans_both_indexes_and_contains_auto_index_error(
+ library_session: Session, mocker: MockerFixture, tmp_path: Path
+) -> None:
+ source_id = _seed_source(library_session)
+ default_id = str(uuid.uuid4())
+ library_session.add(
+ Collection(
+ id=default_id,
+ name="Library",
+ collection_type="library",
+ is_default=True,
+ )
+ )
+ library_session.commit()
+ _patch_session(mocker, library_session)
+ mocker.patch(
+ f"{_SYNC}.get_source_type_id",
+ return_value=source_id,
+ )
+ mocker.patch(
+ "local_deep_research.web.routers.rag.trigger_auto_index",
+ side_effect=RuntimeError("queue unavailable"),
+ )
+ service = ZoteroSyncService("user", "password")
+ mocker.patch.object(service, "_library_root", return_value=tmp_path)
+ cleanup = mocker.patch.object(service, "_cleanup_removed_vectors")
+ cfg = ZoteroConfig(
+ api_key="key", library_id="7", import_items_without_pdf=True
+ )
+ client = mocker.MagicMock()
+ client.get_children.return_value = []
+ client.get_top_item_versions.side_effect = [({"A": 1}, 1), ({"A": 2}, 2)]
+ client.get_items.side_effect = [
+ [ZoteroItem("A", 1, "book", {"title": "First"})],
+ [ZoteroItem("A", 2, "book", {"title": "Second"})],
+ ]
+
+ assert service._sync_one(client, cfg, "")["imported"] == 1
+ cleanup.reset_mock()
+ assert service._sync_one(client, cfg, "")["updated"] == 1
+
+ cleaned_collection_ids = {call.args[1] for call in cleanup.call_args_list}
+ assert default_id in cleaned_collection_ids
+ assert len(cleaned_collection_ids) == 2
+
+
+def test_sync_one_contains_unexpected_session_failure(
+ mocker: MockerFixture,
+) -> None:
+ service = ZoteroSyncService("user")
+ state_writer = mocker.patch.object(service, "_mark_failed")
+ broken = mocker.MagicMock()
+ broken.__enter__.side_effect = RuntimeError("database failed")
+ mocker.patch(
+ f"{_SYNC}.get_user_db_session", side_effect=lambda *_a, **_k: broken
+ )
+
+ result = service._sync_one(
+ mocker.MagicMock(), ZoteroConfig(library_id="7"), "C"
+ )
+
+ assert result["status"] == "failed"
+ state_writer.assert_called_once()
+
+
+def test_cleanup_vectors_handles_index_absence_success_and_failure(
+ mocker: MockerFixture,
+) -> None:
+ service = ZoteroSyncService("user", "password")
+ session = mocker.MagicMock()
+ query = session.query.return_value.filter_by.return_value
+ query.first.return_value = None
+ session_patch = _patch_session(mocker, session)
+ rag_class = mocker.patch(f"{_RAG}.LibraryRAGService")
+ service._cleanup_removed_vectors(["D1"], "C1")
+ rag_class.assert_not_called()
+
+ rag_index = mocker.MagicMock(
+ embedding_model="model",
+ embedding_model_type=None,
+ chunk_size=100,
+ chunk_overlap=10,
+ index_type=None,
+ distance_metric=None,
+ normalize_vectors="true",
+ )
+ query.first.return_value = rag_index
+ rag_service = rag_class.return_value.__enter__.return_value
+ rag_service.remove_documents_from_index.return_value = 3
+ pending = {("D1", "C1"): [11], ("D2", "other"): [22]}
+ service._cleanup_removed_vectors(["D1", "D2"], "C1", pending)
+ rag_service.remove_documents_from_index.assert_called_once_with(
+ ["D1", "D2"], "C1", chunk_ids_by_document={"D1": [11]}
+ )
+
+ session_patch.side_effect = RuntimeError("open failed")
+ service._cleanup_removed_vectors(["D1"], "C1")
+
+
+def test_mark_failed_tolerates_database_error(mocker: MockerFixture) -> None:
+ service = ZoteroSyncService("user")
+ failure = mocker.patch(
+ f"{_SYNC}.get_user_db_session", side_effect=RuntimeError
+ )
+
+ service._mark_failed(ZoteroConfig(library_id="7"), "C", "failed")
+
+ failure.assert_called_once()
+
+
+def test_collection_and_helper_failure_edges(
+ library_session: Session, mocker: MockerFixture
+) -> None:
+ service = ZoteroSyncService("user")
+ client = mocker.MagicMock()
+ client.get_collection_name.return_value = None
+ collection_id = service._ensure_ldr_collection(
+ library_session, client, ZoteroConfig(library_id="7"), "KEY"
+ )
+ collection = (
+ library_session.query(Collection).filter_by(id=collection_id).one()
+ )
+ assert collection.name == "Zotero: KEY"
+
+ capture = mocker.patch.object(ZoteroSyncService, "_capture_chunk_ids")
+ delete_chunks = mocker.patch(
+ f"{_SYNC}.CascadeHelper.delete_document_chunks"
+ )
+ fake_session = mocker.MagicMock()
+ links = [mocker.MagicMock(indexed=True), mocker.MagicMock(indexed=True)]
+ fake_session.query.return_value.filter_by.return_value.first.side_effect = (
+ links
+ )
+ pending: dict[tuple[str, str], list[int]] = {}
+ service._purge_collection_chunks(fake_session, "D", "C", "DEFAULT", pending)
+ assert capture.call_args_list == [
+ mocker.call(pending, fake_session, "D", "C"),
+ mocker.call(pending, fake_session, "D", "DEFAULT"),
+ ]
+ assert delete_chunks.call_args_list == [
+ mocker.call(fake_session, "D", collection_name="collection_C"),
+ mocker.call(fake_session, "D", collection_name="collection_DEFAULT"),
+ ]
+ assert all(link.indexed is False for link in links)
+
+
+def test_annotation_extraction_metadata_and_mapping_edges(
+ library_session: Session, mocker: MockerFixture
+) -> None:
+ service = ZoteroSyncService("user")
+ attachment = ZoteroAttachment(
+ "A", 1, "application/pdf", "imported_file", None, None
+ )
+ item = ZoteroItem(
+ "KEY",
+ 3,
+ "book",
+ {
+ "title": "Title",
+ "creators": ["invalid", {"name": "Ada"}],
+ "date": "2020",
+ "publicationTitle": "Journal",
+ "DOI": "10.1/example",
+ "ISBN": "1234567890",
+ "url": "https://example.test",
+ "tags": ["invalid", {"tag": "tag"}],
+ "abstractNote": "Summary",
+ },
+ [attachment],
+ )
+ client = mocker.MagicMock()
+ client.get_annotations.side_effect = RuntimeError("annotations failed")
+ client.get_notes.side_effect = RuntimeError("notes failed")
+ assert service._collect_annotations_text(client, item) == ""
+ client.get_annotations.assert_called_once_with("A")
+ client.get_notes.assert_called_once_with("KEY")
+
+ extractor = mocker.patch(
+ "local_deep_research.document_loaders.extract_text_from_bytes",
+ side_effect=RuntimeError("invalid pdf"),
+ )
+ assert service._safe_extract_text(b"%PDF", item)[1] == "metadata"
+ extractor.side_effect = None
+ extractor.return_value = "PDF text"
+ assert service._safe_extract_text(b"%PDF", item) == (
+ "PDF text",
+ "pdf_extraction",
+ )
+ text = service._metadata_text(item)
+ assert all(
+ value in text for value in ("Ada", "Journal", "10.1/example", "Summary")
+ )
+
+ doc = Document(filename="fallback.txt")
+ service._apply_metadata(doc, item)
+ assert doc.authors == ["Ada"]
+ assert doc.isbn == "1234567890"
+ mocker.patch(
+ f"{_SYNC}.sanitize_filename",
+ side_effect=UnsafeFilenameError("unsafe"),
+ )
+ assert service._filename_for(item, "pdf") == "KEY.pdf"
+
+ source_id = _seed_source(library_session)
+ row = ZoteroItemMap(
+ ldr_collection_id=str(uuid.uuid4()),
+ zotero_item_key="KEY",
+ zotero_version=1,
+ )
+ library_session.add(row)
+ library_session.commit()
+ service._touch_map_version(library_session, row.ldr_collection_id, "KEY", 9)
+ assert row.zotero_version == 9
+ assert (
+ service._release_document(library_session, None, "C", 1, source_id)
+ is None
+ )
+ assert service._document_exists(library_session, None) is False