test(sdk): add unit tests for all SDK layers

Author: KylinMountain

tests/test_agent.py

@@ -0,0 +1,14 @@
+from pageindex.agent import AgentRunner, SYSTEM_PROMPT
+from pageindex.backend.protocol import AgentTools
+
+
+def test_agent_runner_init():
+    tools = AgentTools(function_tools=["mock_tool"])
+    runner = AgentRunner(tools=tools, model="gpt-4o")
+    assert runner._model == "gpt-4o"
+
+
+def test_system_prompt_has_tool_instructions():
+    assert "list_documents" in SYSTEM_PROMPT
+    assert "get_document_structure" in SYSTEM_PROMPT
+    assert "get_page_content" in SYSTEM_PROMPT

tests/test_client.py

@@ -0,0 +1,51 @@
+# tests/sdk/test_client.py
+import pytest
+from pageindex.client import PageIndexClient, LocalClient, CloudClient
+
+
+def test_local_client_is_pageindex_client(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    assert isinstance(client, PageIndexClient)
+
+
+def test_cloud_client_is_pageindex_client():
+    client = CloudClient(api_key="pi-test")
+    assert isinstance(client, PageIndexClient)
+
+
+def test_collection_default_name(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    col = client.collection()
+    assert col.name == "default"
+
+
+def test_collection_custom_name(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    col = client.collection("papers")
+    assert col.name == "papers"
+
+
+def test_list_collections_empty(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    assert client.list_collections() == []
+
+
+def test_list_collections_after_create(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    client.collection("papers")
+    assert "papers" in client.list_collections()
+
+
+def test_delete_collection(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    client.collection("papers")
+    client.delete_collection("papers")
+    assert "papers" not in client.list_collections()
+
+
+def test_register_parser(tmp_path):
+    client = LocalClient(model="gpt-4o", storage_path=str(tmp_path / "pi"))
+    class FakeParser:
+        def supported_extensions(self): return [".txt"]
+        def parse(self, file_path, **kwargs): pass
+    client.register_parser(FakeParser())

tests/test_cloud_backend.py

@@ -0,0 +1,16 @@
+from pageindex.backend.cloud import CloudBackend, API_BASE
+
+
+def test_cloud_backend_init():
+    backend = CloudBackend(api_key="pi-test")
+    assert backend._api_key == "pi-test"
+    assert backend._headers["api_key"] == "pi-test"
+
+
+def test_api_base_url():
+    assert "pageindex.ai" in API_BASE
+
+
+def test_get_retrieve_model_is_none():
+    backend = CloudBackend(api_key="pi-test")
+    assert backend.get_agent_tools("col").function_tools == []

tests/test_collection.py

@@ -0,0 +1,41 @@
+# tests/sdk/test_collection.py
+import pytest
+from unittest.mock import MagicMock
+from pageindex.collection import Collection
+
+
+@pytest.fixture
+def col():
+    backend = MagicMock()
+    backend.list_documents.return_value = [
+        {"doc_id": "d1", "doc_name": "paper.pdf", "doc_type": "pdf"}
+    ]
+    backend.get_document.return_value = {"doc_id": "d1", "doc_name": "paper.pdf"}
+    backend.add_document.return_value = "d1"
+    return Collection(name="papers", backend=backend)
+
+
+def test_add(col):
+    doc_id = col.add("paper.pdf")
+    assert doc_id == "d1"
+    col._backend.add_document.assert_called_once_with("papers", "paper.pdf")
+
+
+def test_list_documents(col):
+    docs = col.list_documents()
+    assert len(docs) == 1
+    assert docs[0]["doc_id"] == "d1"
+
+
+def test_get_document(col):
+    doc = col.get_document("d1")
+    assert doc["doc_name"] == "paper.pdf"
+
+
+def test_delete_document(col):
+    col.delete_document("d1")
+    col._backend.delete_document.assert_called_once_with("papers", "d1")
+
+
+def test_name_property(col):
+    assert col.name == "papers"

tests/test_config.py

@@ -0,0 +1,24 @@
+# tests/sdk/test_config.py
+import pytest
+from pageindex.config import ConfigLoader
+
+
+def test_load_defaults():
+    c = ConfigLoader()
+    opt = c.load()
+    assert opt.model == "gpt-5.4"
+    assert opt.retrieve_model == "gpt-5.4"
+    assert opt.toc_check_page_num == 20
+
+
+def test_load_with_overrides():
+    c = ConfigLoader()
+    opt = c.load({"model": "gpt-5.4", "retrieve_model": "claude-sonnet"})
+    assert opt.model == "gpt-5.4"
+    assert opt.retrieve_model == "claude-sonnet"
+
+
+def test_unknown_key_raises():
+    c = ConfigLoader()
+    with pytest.raises(ValueError, match="Unknown config keys"):
+        c.load({"nonexistent_key": "value"})

tests/test_content_node.py

@@ -0,0 +1,45 @@
+from pageindex.parser.protocol import ContentNode, ParsedDocument, DocumentParser
+
+
+def test_content_node_required_fields():
+    node = ContentNode(content="hello", tokens=5)
+    assert node.content == "hello"
+    assert node.tokens == 5
+    assert node.title is None
+    assert node.index is None
+    assert node.level is None
+
+
+def test_content_node_all_fields():
+    node = ContentNode(content="# Intro", tokens=10, title="Intro", index=1, level=1)
+    assert node.title == "Intro"
+    assert node.index == 1
+    assert node.level == 1
+
+
+def test_parsed_document():
+    nodes = [ContentNode(content="page1", tokens=100, index=1)]
+    doc = ParsedDocument(doc_name="test.pdf", nodes=nodes)
+    assert doc.doc_name == "test.pdf"
+    assert len(doc.nodes) == 1
+    assert doc.metadata is None
+
+
+def test_parsed_document_with_metadata():
+    nodes = [ContentNode(content="page1", tokens=100)]
+    doc = ParsedDocument(doc_name="test.pdf", nodes=nodes, metadata={"author": "John"})
+    assert doc.metadata["author"] == "John"
+
+
+def test_document_parser_protocol():
+    """Verify a class implementing DocumentParser is structurally compatible."""
+    class MyParser:
+        def supported_extensions(self) -> list[str]:
+            return [".txt"]
+        def parse(self, file_path: str, **kwargs) -> ParsedDocument:
+            return ParsedDocument(doc_name="test", nodes=[])
+
+    parser = MyParser()
+    assert parser.supported_extensions() == [".txt"]
+    result = parser.parse("test.txt")
+    assert isinstance(result, ParsedDocument)

tests/test_errors.py

@@ -0,0 +1,27 @@
+from pageindex.errors import (
+    PageIndexError,
+    CollectionNotFoundError,
+    DocumentNotFoundError,
+    IndexingError,
+    CloudAPIError,
+    FileTypeError,
+)
+
+
+def test_all_errors_inherit_from_base():
+    for cls in [CollectionNotFoundError, DocumentNotFoundError, IndexingError, CloudAPIError, FileTypeError]:
+        assert issubclass(cls, PageIndexError)
+        assert issubclass(cls, Exception)
+
+
+def test_error_message():
+    err = FileTypeError("Unsupported: .docx")
+    assert str(err) == "Unsupported: .docx"
+
+
+def test_catch_base_catches_all():
+    for cls in [CollectionNotFoundError, DocumentNotFoundError, IndexingError, CloudAPIError, FileTypeError]:
+        try:
+            raise cls("test")
+        except PageIndexError:
+            pass  # expected

tests/test_events.py

@@ -0,0 +1,26 @@
+from pageindex.events import QueryEvent
+from pageindex.backend.protocol import AgentTools
+
+
+def test_query_event():
+    event = QueryEvent(type="answer_delta", data="hello")
+    assert event.type == "answer_delta"
+    assert event.data == "hello"
+
+
+def test_query_event_types():
+    for t in ["reasoning", "tool_call", "tool_result", "answer_delta", "answer_done"]:
+        event = QueryEvent(type=t, data="test")
+        assert event.type == t
+
+
+def test_agent_tools_default_empty():
+    tools = AgentTools()
+    assert tools.function_tools == []
+    assert tools.mcp_servers == []
+
+
+def test_agent_tools_with_values():
+    tools = AgentTools(function_tools=["tool1"], mcp_servers=["server1"])
+    assert len(tools.function_tools) == 1
+    assert len(tools.mcp_servers) == 1

tests/test_local_backend.py

@@ -0,0 +1,50 @@
+# tests/sdk/test_local_backend.py
+import pytest
+from pathlib import Path
+from pageindex.backend.local import LocalBackend
+from pageindex.storage.sqlite import SQLiteStorage
+from pageindex.errors import FileTypeError
+
+
+@pytest.fixture
+def backend(tmp_path):
+    storage = SQLiteStorage(str(tmp_path / "test.db"))
+    files_dir = tmp_path / "files"
+    return LocalBackend(storage=storage, files_dir=str(files_dir), model="gpt-4o")
+
+
+def test_collection_lifecycle(backend):
+    backend.get_or_create_collection("papers")
+    assert "papers" in backend.list_collections()
+    backend.delete_collection("papers")
+    assert "papers" not in backend.list_collections()
+
+
+def test_list_documents_empty(backend):
+    backend.get_or_create_collection("papers")
+    assert backend.list_documents("papers") == []
+
+
+def test_unsupported_file_type_raises(backend, tmp_path):
+    backend.get_or_create_collection("papers")
+    bad_file = tmp_path / "test.xyz"
+    bad_file.write_text("hello")
+    with pytest.raises(FileTypeError):
+        backend.add_document("papers", str(bad_file))
+
+
+def test_register_custom_parser(backend):
+    from pageindex.parser.protocol import ParsedDocument, ContentNode
+
+    class TxtParser:
+        def supported_extensions(self):
+            return [".txt"]
+        def parse(self, file_path, **kwargs):
+            text = Path(file_path).read_text()
+            return ParsedDocument(doc_name="test", nodes=[
+                ContentNode(content=text, tokens=len(text.split()), title="Content", index=1, level=1)
+            ])
+
+    backend.register_parser(TxtParser())
+    # Now .txt should be supported (won't raise FileTypeError)
+    assert backend._resolve_parser("test.txt") is not None

tests/test_markdown_parser.py

@@ -0,0 +1,55 @@
+import pytest
+from pathlib import Path
+from pageindex.parser.markdown import MarkdownParser
+from pageindex.parser.protocol import ContentNode, ParsedDocument
+
+@pytest.fixture
+def sample_md(tmp_path):
+    md = tmp_path / "test.md"
+    md.write_text("""# Chapter 1
+Some intro text.
+
+## Section 1.1
+Details here.
+
+## Section 1.2
+More details.
+
+# Chapter 2
+Another chapter.
+""")
+    return str(md)
+
+def test_supported_extensions():
+    parser = MarkdownParser()
+    exts = parser.supported_extensions()
+    assert ".md" in exts
+    assert ".markdown" in exts
+
+def test_parse_returns_parsed_document(sample_md):
+    parser = MarkdownParser()
+    result = parser.parse(sample_md)
+    assert isinstance(result, ParsedDocument)
+    assert result.doc_name == "test"
+
+def test_parse_nodes_have_level(sample_md):
+    parser = MarkdownParser()
+    result = parser.parse(sample_md)
+    assert len(result.nodes) == 4
+    assert result.nodes[0].level == 1
+    assert result.nodes[0].title == "Chapter 1"
+    assert result.nodes[1].level == 2
+    assert result.nodes[1].title == "Section 1.1"
+    assert result.nodes[3].level == 1
+
+def test_parse_nodes_have_content(sample_md):
+    parser = MarkdownParser()
+    result = parser.parse(sample_md)
+    assert "Some intro text" in result.nodes[0].content
+    assert "Details here" in result.nodes[1].content
+
+def test_parse_nodes_have_index(sample_md):
+    parser = MarkdownParser()
+    result = parser.parse(sample_md)
+    for node in result.nodes:
+        assert node.index is not None