~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 state-changing flows and realtime paths.
Covers gaps left by test_endpoint_coverage.py (which only tests GET → 200):
- Full CRUD round-trip on settings (mutation actually persists)
- Socket.IO subscription tracking (subscribe/unsubscribe internal state)
- Rate limiting on auth routes (slowapi actually rejects)
- Multi-user isolation (user A cannot read user B's settings)
"""
import asyncio
import uuid
import pytest
from fastapi.testclient import TestClient
# ----------------------------------------------------------------------------
# Shared fixtures
# ----------------------------------------------------------------------------
def _unique_ip() -> str:
"""Generate a unique client IP to avoid sharing rate-limit buckets
with other test files (registration is rate limited per IP)."""
return f"10.{uuid.uuid4().int % 254 + 1}.{uuid.uuid4().int % 254 + 1}.1"
def _register_and_login(
client: TestClient, user: str, pw: str, ip: str | None = None
):
"""Register + login in one step. Returns the login response object.
Passes X-Forwarded-For so each test file gets its own
rate-limit bucket under slowapi. Post-Wave-9, /auth/register and
/auth/login are no longer CSRF-exempt — fetch a real session-bound
token before each form POST.
"""
headers = {"X-Forwarded-For": ip} if ip else {}
def _csrf() -> str:
client.get("/auth/login", headers=headers)
r = client.get("/auth/csrf-token", headers=headers)
return r.json().get("csrf_token", "") if r.status_code == 200 else ""
client.post(
"/auth/register",
data={
"username": user,
"password": pw,
"confirm_password": pw,
"acknowledge": "true",
"csrf_token": _csrf(),
},
headers=headers,
follow_redirects=False,
)
resp = client.post(
"/auth/login",
data={"username": user, "password": pw, "csrf_token": _csrf()},
headers=headers,
follow_redirects=False,
)
return resp
def _attach_csrf_header(client: TestClient) -> None:
"""Fetch the session's CSRF token and add it as a default header
so subsequent state-changing requests pass CSRFMiddleware."""
resp = client.get("/auth/csrf-token")
if resp.status_code == 200:
token = resp.json().get("csrf_token")
if token:
client.headers.update({"X-CSRFToken": token})
@pytest.fixture(scope="module")
def auth_client():
"""Authenticated TestClient for a freshly-created user."""
from local_deep_research.web.fastapi_app import app
c = TestClient(app, raise_server_exceptions=False)
user = f"test_state_{uuid.uuid4().hex[:8]}"
pw = "TestPassword123!" # noqa: S105
login_resp = _register_and_login(c, user, pw, ip=_unique_ip())
if login_resp.status_code != 302:
pytest.fail(
f"Register/login bootstrap failed: expected 302, got "
f"{login_resp.status_code}: {login_resp.text[:500]}"
)
_attach_csrf_header(c)
yield c
c.post("/auth/logout", follow_redirects=False)
# ----------------------------------------------------------------------------
# Settings CRUD round-trip — verifies PUT actually persists via GET-after-PUT
# ----------------------------------------------------------------------------
class TestSettingsCRUDRoundtrip:
"""Full PUT → GET → restore cycle, not just 'did it return 200'."""
def test_put_persists_via_get(self, auth_client):
"""Writing llm.model actually changes what GET returns."""
key = "llm.model"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
new_value = f"roundtrip-{uuid.uuid4().hex[:6]}"
put_resp = auth_client.put(
f"/settings/api/{key}", json={"value": new_value}
)
assert put_resp.status_code == 200
got = auth_client.get(f"/settings/api/{key}").json()
assert got["value"] == new_value, (
f"PUT did not persist: wrote {new_value!r}, read {got['value']!r}"
)
# Restore (best-effort)
if original is not None:
auth_client.put(f"/settings/api/{key}", json={"value": original})
def test_put_rejects_missing_value(self, auth_client):
"""PUT body without 'value' key returns 400."""
resp = auth_client.put("/settings/api/llm.model", json={})
assert resp.status_code == 400
def test_delete_unknown_setting_returns_404(self, auth_client):
"""DELETE on a nonexistent key returns 404 (not 500)."""
resp = auth_client.delete(
f"/settings/api/nonexistent.key.{uuid.uuid4().hex[:6]}"
)
assert resp.status_code == 404
def test_bulk_settings_reflects_put(self, auth_client):
"""Bulk endpoint sees updates made via PUT (no stale cache)."""
# llm.model is in the default bulk key list
key = "llm.model"
new_value = f"bulk-roundtrip-{uuid.uuid4().hex[:6]}"
original = auth_client.get(f"/settings/api/{key}").json().get("value")
put_resp = auth_client.put(
f"/settings/api/{key}", json={"value": new_value}
)
assert put_resp.status_code == 200
# Bulk endpoint uses keys[] (array notation)
bulk = auth_client.get(f"/settings/api/bulk?keys[]={key}").json()
assert bulk.get("success") is True
entry = bulk["settings"].get(key)
assert isinstance(entry, dict), f"expected dict, got {entry!r}"
assert entry.get("value") == new_value, (
f"bulk returned stale value: wrote {new_value!r}, "
f"bulk returned {entry!r}"
)
# Restore
if original is not None:
auth_client.put(f"/settings/api/{key}", json={"value": original})
# ----------------------------------------------------------------------------
# Multi-user isolation — user A cannot read user B's settings
# ----------------------------------------------------------------------------
class TestMultiUserIsolation:
"""Each user has their own encrypted database."""
def test_users_see_independent_setting_values(self):
"""User A sets llm.model to X; user B still sees the default."""
from local_deep_research.web.fastapi_app import app
client_a = TestClient(app, raise_server_exceptions=False)
client_b = TestClient(app, raise_server_exceptions=False)
user_a = f"iso_a_{uuid.uuid4().hex[:8]}"
user_b = f"iso_b_{uuid.uuid4().hex[:8]}"
pw = "TestPassword123!" # noqa: S105
resp_a = _register_and_login(client_a, user_a, pw, ip=_unique_ip())
if resp_a.status_code != 302:
pytest.fail(
f"Register/login bootstrap failed for user A: expected 302, "
f"got {resp_a.status_code}: {resp_a.text[:500]}"
)
resp_b = _register_and_login(client_b, user_b, pw, ip=_unique_ip())
if resp_b.status_code != 302:
pytest.fail(
f"Register/login bootstrap failed for user B: expected 302, "
f"got {resp_b.status_code}: {resp_b.text[:500]}"
)
_attach_csrf_header(client_a)
_attach_csrf_header(client_b)
marker = f"iso-marker-{uuid.uuid4().hex[:6]}"
put_resp = client_a.put(
"/settings/api/llm.model", json={"value": marker}
)
assert put_resp.status_code == 200
# User B should NOT see user A's value
b_value = client_b.get("/settings/api/llm.model").json().get("value")
assert b_value != marker, (
"Cross-user leak: user B read user A's custom llm.model value"
)
def test_research_resources_not_shared_across_users(self):
"""
User B cannot read user A's research resources via
``GET /research/api/resources/{research_id}``.
Pre-fix the route called ``get_resources_for_research(research_id)``
with no username scope. Each user has their own encrypted DB so
a stale contextvar or a future refactor could cross the wires —
this test pins the user-scoped behaviour.
"""
from local_deep_research.web.fastapi_app import app
client_a = TestClient(app, raise_server_exceptions=False)
client_b = TestClient(app, raise_server_exceptions=False)
user_a = f"idor_a_{uuid.uuid4().hex[:8]}"
user_b = f"idor_b_{uuid.uuid4().hex[:8]}"
pw = "TestPassword123!" # noqa: S105
resp_a = _register_and_login(client_a, user_a, pw, ip=_unique_ip())
if resp_a.status_code != 302:
pytest.fail(
f"Register/login bootstrap failed for user A: expected 302, "
f"got {resp_a.status_code}: {resp_a.text[:500]}"
)
resp_b = _register_and_login(client_b, user_b, pw, ip=_unique_ip())
if resp_b.status_code != 302:
pytest.fail(
f"Register/login bootstrap failed for user B: expected 302, "
f"got {resp_b.status_code}: {resp_b.text[:500]}"
)
# User B asks for resources of an arbitrary research_id that, if
# it existed, would belong to user A. The endpoint must respond
# successfully with an empty list (not 5xx, and not user A's data).
# We use a UUID that is not present in either user's DB; the
# important property is that user B's DB scope is consulted, so
# the response is the empty-list payload not a cross-user leak.
fake_research_id = uuid.uuid4().hex
resp = client_b.get(f"/research/api/resources/{fake_research_id}")
assert resp.status_code == 200, (
f"Expected 200 with empty result for unknown research_id; "
f"got {resp.status_code}: {resp.text[:200]}"
)
body = resp.json()
assert body.get("status") == "success"
assert body.get("resources") == [], (
f"Expected empty list for research_id not in user B's DB; "
f"got {body.get('resources')!r}"
)
# ----------------------------------------------------------------------------
# Rate limiting — slowapi actually blocks excessive login attempts
# ----------------------------------------------------------------------------
class TestRateLimiting:
"""Verify slowapi limiter rejects bursts on auth routes."""
def test_login_burst_triggers_429(self):
"""LOGIN_RATE_LIMIT is '5 per 15 minutes' — the 6th is blocked."""
from local_deep_research.web.fastapi_app import app
# Check if rate limiting is enabled in this config
from local_deep_research.settings.env_registry import (
is_rate_limiting_enabled,
)
if not is_rate_limiting_enabled():
pytest.skip("Rate limiting disabled in this environment")
# Use a fresh client with a unique IP to avoid interfering
# with other tests' rate-limit buckets.
client = TestClient(app, raise_server_exceptions=False)
unique_ip = f"10.{uuid.uuid4().int % 254 + 1}.0.1"
headers = {"X-Forwarded-For": unique_ip}
# GET the login page once so the session has a CSRF token —
# post-Wave-9, login is no longer CSRF-exempt.
client.get("/auth/login", headers=headers)
csrf = client.get("/auth/csrf-token", headers=headers).json()[
"csrf_token"
]
post_data = {
"username": "no_such_user",
"password": "wrong",
"csrf_token": csrf,
}
# 5 failed attempts should return 401
for i in range(5):
resp = client.post("/auth/login", data=post_data, headers=headers)
assert resp.status_code in (
400,
401,
), f"Attempt {i + 1}: unexpected {resp.status_code}"
# 6th attempt should be rate-limited
resp = client.post("/auth/login", data=post_data, headers=headers)
assert resp.status_code == 429, (
f"Expected 429 after 5 attempts, got {resp.status_code}"
)
# ----------------------------------------------------------------------------
# Socket.IO subscription tracking
# ----------------------------------------------------------------------------
class TestSocketIOSubscriptions:
"""Internal subscription state is consistent with subscribe/disconnect."""
def test_subscribe_rejects_unauthenticated_sid(self):
"""on_subscribe must refuse subscriptions from sockets with no
associated user — prevents cross-user research spying."""
from local_deep_research.web.services import socketio_asgi
rid = f"test-research-{uuid.uuid4().hex[:8]}"
sid = f"unauth-sid-{uuid.uuid4().hex[:8]}"
async def run():
# init_lock() must run inside the loop so the asyncio.Lock
# binds to the loop the test will await on. In production
# the lifespan hook does this exactly once.
socketio_asgi.init_lock()
await socketio_asgi.on_subscribe(sid, {"research_id": rid})
# Reset module-level _lock between tests so each asyncio.run
# creates a fresh lock bound to its own loop.
socketio_asgi._lock = None
asyncio.run(run())
# sid was never registered in _sid_users, so subscribe must be rejected
assert rid not in socketio_asgi._subscriptions
def test_subscribe_rejects_when_user_does_not_own_research(self):
"""Authenticated socket cannot subscribe to a research_id that
isn't in the user's own encrypted DB."""
from local_deep_research.web.services import socketio_asgi
rid = f"foreign-rid-{uuid.uuid4().hex[:8]}"
sid = f"auth-sid-{uuid.uuid4().hex[:8]}"
socketio_asgi._sid_users[sid] = "nonexistent_user"
async def _run():
socketio_asgi.init_lock()
await socketio_asgi.on_subscribe(sid, {"research_id": rid})
socketio_asgi._lock = None
try:
asyncio.run(_run())
# Ownership check should fail (no DB for that user) and skip subscribe
assert rid not in socketio_asgi._subscriptions
finally:
socketio_asgi._sid_users.pop(sid, None)
def test_subscribe_ignores_missing_research_id(self):
"""Subscribing without research_id is a no-op, not a crash."""
from local_deep_research.web.services import socketio_asgi
before = dict(socketio_asgi._subscriptions)
async def run():
socketio_asgi.init_lock()
await socketio_asgi.on_subscribe("sid-x", {})
await socketio_asgi.on_subscribe("sid-y", None)
socketio_asgi._lock = None
asyncio.run(run())
assert socketio_asgi._subscriptions == before
def test_remove_subscriptions_clears_entry(self):
"""remove_subscriptions_for_research clears the dict entry.
Cleanup is scheduled on the main event loop, so we need a
running loop (which we get via asyncio.run) and must allow the
scheduled coroutine to actually run before asserting.
"""
import asyncio
from local_deep_research.web.services import socketio_asgi
rid = f"test-remove-{uuid.uuid4().hex[:8]}"
socketio_asgi._subscriptions[("owner-user", rid)] = {"sid-1", "sid-2"}
async def run():
# Register the current loop as the main loop so the sync
# wrapper can schedule onto it.
socketio_asgi.set_main_loop(asyncio.get_running_loop())
socketio_asgi.init_lock()
socketio_asgi.remove_subscriptions_for_research(rid, "owner-user")
# Yield to the loop so the scheduled coroutine runs.
await asyncio.sleep(0)
socketio_asgi._lock = None
asyncio.run(run())
# Assert on the ACTUAL key. `rid not in _subscriptions` was
# unconditionally true once the map became keyed by (owner, id):
# a bare string can never be a tuple key, so the test passed even
# with removal replaced by a no-op.
assert ("owner-user", rid) not in socketio_asgi._subscriptions
def test_polling_endpoint_reachable(self):
"""ASGI mount at /ws/socket.io/ responds to the polling handshake."""
from local_deep_research.web.fastapi_app import app
client = TestClient(app, raise_server_exceptions=False)
resp = client.get("/ws/socket.io/?EIO=4&transport=polling")
assert resp.status_code == 200
# Engine.IO handshake packet starts with "0" followed by JSON
assert resp.text.startswith("0") or "sid" in resp.text