~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
"""
API tests for the Follow-up Research feature.
Re-ported from the pre-FastAPI-migration module, which built the app with
``web.app_factory.create_app()`` and authenticated by writing a bare
``username`` into the session via Flask's ``session_transaction()``. Both are
gone, so the file skipped itself whole at collection.
The routes themselves survived intact as ``web/routers/followup.py``
(``POST /api/followup/prepare`` and ``POST /api/followup/start``), so the
five HTTP tests are re-pointed at the real FastAPI routes through the shared
``authenticated_client`` fixture — a genuinely logged-in user with a real
encrypted database, which is stronger than the old session poke.
SURVEY — already covered on this branch, deliberately NOT duplicated
--------------------------------------------------------------------
The three non-HTTP tests in this file never needed Flask at all; they were
collateral damage of the module-level skip, and every one of them has a
direct equivalent already running:
* ``test_followup_service_load_parent`` ->
``tests/followup_research/test_service.py::TestLoadParentResearch``
(``test_load_parent_research_success`` asserts the same
``research_id`` / ``query`` / ``resources`` shape, plus the not-found,
exception, no-sources and null-meta branches).
* ``test_followup_service_prepare_context`` ->
``tests/followup_research/test_service.py::TestPrepareResearchContext``
(``test_prepare_context_success`` asserts ``parent_research_id`` /
``original_query`` / ``past_findings``), plus
``tests/followup_research/test_followup_edge_cases.py``
::TestPrepareResearchContextEdgeCases.
* ``test_followup_request_model`` -> ``tests/followup_research/test_models.py``
::test_to_dict and the 17 cases in ``test_models_behavior.py``.
``tests/web/routers/test_followup_body_contract.py`` covers the malformed /
non-object body branches, and ``test_followup_capacity_reject.py`` the 429s;
neither touches the happy path, the missing-field 400, or the 404 restored
here.
"""
import itertools
from unittest.mock import patch
import pytest
from fastapi.testclient import TestClient
FOLLOWUP_ROUTER = "local_deep_research.web.routers.followup"
PREPARE_URL = "/api/followup/prepare"
START_URL = "/api/followup/start"
PARENT_ID = "11111111-2222-3333-4444-555555555555"
PARENT_QUERY = "What is quantum computing?"
# Monotonic, never random: a random per-client address collides across a long
# session and produces 429s unrelated to the guard under test.
_IP_COUNTER = itertools.count(1)
def _parent_resources():
return [
{
"url": "https://example.com/quantum",
"title": "Introduction to Quantum Computing",
"content_preview": "Quantum computing is a revolutionary...",
"source_type": "web",
},
{
"url": "https://example.com/gates",
"title": "Quantum Gates Explained",
"content_preview": "Quantum gates are the building blocks...",
"source_type": "web",
},
]
@pytest.fixture
def settings_snapshot():
"""The settings the routes read, patched at their import site.
Both handlers do a function-level ``from ...settings.manager import
SettingsManager``, so the attribute is re-read from the source module on
every call and patching there is what the route actually sees.
"""
snapshot = {
"search.search_strategy": {"value": "source-based"},
"search.iterations": {"value": 1},
"search.questions_per_iteration": {"value": 3},
"llm.provider": {"value": "OLLAMA"},
"llm.model": {"value": "gemma3:12b"},
"search.tool": {"value": "searxng"},
}
with patch(
"local_deep_research.settings.manager.SettingsManager"
) as MockSettings:
MockSettings.return_value.get_all_settings.return_value = snapshot
yield snapshot
@pytest.fixture
def followup_service():
"""Mock ``FollowUpResearchService`` as bound on the router module."""
with patch(f"{FOLLOWUP_ROUTER}.FollowUpResearchService") as MockService:
yield MockService.return_value
class TestPrepareFollowUp:
"""``POST /api/followup/prepare``."""
def test_prepare_followup_success(
self, authenticated_client, settings_snapshot, followup_service
):
followup_service.load_parent_research.return_value = {
"query": PARENT_QUERY,
"resources": _parent_resources(),
}
response = authenticated_client.post(
PREPARE_URL,
json={
"parent_research_id": PARENT_ID,
"question": "How do quantum gates work?",
},
)
assert response.status_code == 200, response.text[:400]
data = response.json()
assert data["success"] is True
assert data["parent_summary"] == PARENT_QUERY
assert data["available_sources"] == 2
assert data["suggested_strategy"] == "source-based"
followup_service.load_parent_research.assert_called_once_with(PARENT_ID)
@pytest.mark.parametrize(
"body,case",
[
({"question": "Test question"}, "missing-parent-id"),
({"parent_research_id": PARENT_ID}, "missing-question"),
({}, "missing-both"),
],
)
def test_prepare_followup_missing_params(
self, authenticated_client, settings_snapshot, body, case
):
"""A field-level 400 — not the shape-level 400 of the body guard.
``tests/web/routers/test_followup_body_contract.py`` proves a dict
body gets PAST the ``isinstance`` guard; this proves the handler then
validates the fields inside it. The message assertion is what keeps
the two apart: a regression that reverted to rejecting on shape would
still return 400 here but with the wrong reason.
"""
response = authenticated_client.post(PREPARE_URL, json=body)
assert response.status_code == 400, (
f"{case}: got {response.status_code}: {response.text[:300]}"
)
data = response.json()
assert data["success"] is False
assert "Missing parent_research_id" in data["error"], (
f"{case}: expected the missing-field message, got {data['error']!r}"
)
def test_prepare_followup_not_found(
self, authenticated_client, settings_snapshot, followup_service
):
"""A parent that does not exist is a 404, not a 200 with empty context.
Answering 200 here lets the UI submit a follow-up against a ghost
parent, producing a run with no inherited sources and no way for the
user to tell why.
"""
followup_service.load_parent_research.return_value = None
response = authenticated_client.post(
PREPARE_URL,
json={
"parent_research_id": "non-existent-id",
"question": "Test question",
},
)
assert response.status_code == 404, response.text[:400]
data = response.json()
assert data["success"] is False
assert data["error"] == "Parent research not found"
class TestStartFollowUp:
"""``POST /api/followup/start``."""
def test_start_followup_success(
self, authenticated_client, settings_snapshot, followup_service
):
followup_service.perform_followup.return_value = {
"query": "How do quantum gates work?",
"strategy": "contextual-followup",
"delegate_strategy": "source-based",
"max_iterations": 1,
"questions_per_iteration": 3,
"parent_research_id": PARENT_ID,
"research_context": {
"parent_research_id": PARENT_ID,
"past_links": [],
"past_findings": "",
},
}
with (
patch(
"local_deep_research.web.services.research_service"
".start_research_process"
) as mock_start,
patch(
f"{FOLLOWUP_ROUTER}.resolve_user_password",
return_value=("test-password", False),
),
):
response = authenticated_client.post(
START_URL,
json={
"parent_research_id": PARENT_ID,
"question": "How do quantum gates work?",
"strategy": "source-based",
"max_iterations": 1,
"questions_per_iteration": 3,
},
)
assert response.status_code == 200, response.text[:400]
data = response.json()
assert data["success"] is True
assert "research_id" in data
assert data["message"] == "Follow-up research started"
mock_start.assert_called_once()
def test_start_followup_unauthorized(self, app):
"""An anonymous caller cannot start research on someone's behalf.
The client here holds a REAL CSRF token — ``GET /auth/csrf-token`` is
public, so an attacker mints one in a single request. Asserting the
403 that a token-less POST produces would therefore prove nothing
about authentication, which is what this test is for.
"""
n = next(_IP_COUNTER)
client = TestClient(app, raise_server_exceptions=False)
client.headers.update(
{"X-Forwarded-For": f"10.81.{n // 250 % 250}.{n % 250 + 1}"}
)
client.get("/auth/login")
token = client.get("/auth/csrf-token").json()["csrf_token"]
response = client.post(
START_URL,
json={
"parent_research_id": PARENT_ID,
"question": "Test question",
},
headers={"X-CSRFToken": token},
)
assert response.status_code == 401, (
f"an unauthenticated but CSRF-valid follow-up start returned "
f"{response.status_code}; expected the auth gate's 401: "
f"{response.text[:300]}"
)
def test_start_followup_requires_a_live_session_password(
self, authenticated_client, settings_snapshot, followup_service
):
"""Positive control's counterpart: no usable DB password -> 401.
Without it the run would start and every metric/DB write from the
background thread would be silently dropped (#4457) while the UI
reported success. Also proves the 200 above is a real decision rather
than an unconditional success.
"""
followup_service.perform_followup.return_value = {
"query": "q",
"max_iterations": 1,
"questions_per_iteration": 3,
"parent_research_id": PARENT_ID,
"research_context": {},
}
with (
patch(
"local_deep_research.web.services.research_service"
".start_research_process"
) as mock_start,
patch(
f"{FOLLOWUP_ROUTER}.resolve_user_password",
return_value=(None, True),
),
):
response = authenticated_client.post(
START_URL,
json={
"parent_research_id": PARENT_ID,
"question": "Test question",
},
)
assert response.status_code == 401, response.text[:400]
assert response.json()["success"] is False
mock_start.assert_not_called()
def test_prepare_and_start_are_the_only_followup_routes():
"""Guards the premise of every test above.
If either path moved, the assertions here would run against a 404 and
still look like they were exercising the handler.
"""
from local_deep_research.web.routers.followup import router
paths = {route.path for route in router.routes if hasattr(route, "path")}
assert paths == {PREPARE_URL, START_URL}, paths