~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
"""Computation-level tests for ``get_link_analytics`` (FastAPI port).
Ports main's deleted ``tests/test_link_analytics.py`` to the function's new
home in ``local_deep_research.web.routers.metrics``, upgraded from
attribute-permissive MagicMock rows to a REAL seeded in-memory SQLite DB so
the function runs its actual projected query on real ``Row`` objects (the
#4560 guard: dropping a consumed projected column degrades output instead of
auto-vivifying on a mock).
Covered: period parsing / time filtering, per-domain aggregation and
www-normalization, top-10 ordering + distribution, averages, source types,
category distribution from DomainClassification, temporal trend, recent
researches, and the no-session / empty-data / error fallbacks.
"""
from contextlib import contextmanager
from datetime import datetime, timedelta, UTC
from unittest.mock import patch
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from sqlalchemy.pool import StaticPool
from local_deep_research.database.models import (
Base,
ResearchHistory,
ResearchResource,
)
from local_deep_research.domain_classifier import DomainClassification
from local_deep_research.web.routers.metrics import get_link_analytics
SESSION_TARGET = "local_deep_research.web.routers.metrics.get_user_db_session"
@contextmanager
def _seeded_db(*rows):
"""Patch ``get_user_db_session`` with an in-memory SQLite DB seeded with
*rows*, so ``get_link_analytics`` runs its real projected SQL.
StaticPool keeps one shared connection so seed data and the function
under test see the same in-memory DB.
"""
engine = create_engine(
"sqlite://",
connect_args={"check_same_thread": False},
poolclass=StaticPool,
)
try:
Base.metadata.create_all(engine)
Session = sessionmaker(bind=engine)
with Session() as seed:
seed.add_all(rows)
seed.commit()
@contextmanager
def _ctx(username=None, password=None):
with Session() as session:
yield session
with patch(SESSION_TARGET, _ctx):
yield
finally:
engine.dispose()
def _res(
url,
research_id="r1",
days_ago=0,
source_type=None,
title=None,
content_preview=None,
created_at=None,
):
"""Build a ResearchResource with an ISO-string created_at (the column is
Text; the route compares it lexicographically against an ISO cutoff)."""
if created_at is None:
created_at = (datetime.now(UTC) - timedelta(days=days_ago)).isoformat()
return ResearchResource(
research_id=research_id,
url=url,
title=title,
content_preview=content_preview,
source_type=source_type,
created_at=created_at,
)
class TestSessionAndEmptyFallbacks:
"""No-username, empty-DB, and hard-error fallback shapes."""
def test_no_username_returns_error_shape(self):
"""Without a username the function short-circuits to the zeroed
error dict and never opens a DB session."""
result = get_link_analytics(username=None)
assert "link_analytics" in result
analytics = result["link_analytics"]
assert analytics["error"] == "No user session"
assert analytics["total_links"] == 0
assert analytics["total_unique_domains"] == 0
assert analytics["avg_links_per_research"] == 0
assert analytics["top_domains"] == []
def test_empty_data_returns_zeros_without_error(self):
"""An authenticated user with no resources gets zeros — and NO
'error' key (empty is not an error)."""
with _seeded_db():
result = get_link_analytics(username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 0
assert analytics["total_unique_domains"] == 0
assert analytics["avg_links_per_research"] == 0
assert analytics["top_domains"] == []
assert analytics["domain_distribution"] == {}
assert analytics["source_type_analysis"] == {}
assert "error" not in analytics
def test_db_failure_returns_error_fallback(self):
"""A raising session yields the zeroed dict with the failure
message instead of propagating the exception to the route."""
@contextmanager
def _boom(username=None, password=None):
raise RuntimeError("db exploded")
yield # pragma: no cover
with patch(SESSION_TARGET, _boom):
result = get_link_analytics(username="test_user")
analytics = result["link_analytics"]
assert analytics["error"] == "Failed to retrieve link analytics"
assert analytics["total_links"] == 0
assert analytics["top_domains"] == []
class TestDomainAggregation:
"""Per-domain counting, normalization, ordering, and distribution."""
def test_www_prefix_and_case_normalize_into_one_domain(self):
"""www.github.com / github.com / GITHUB.com all aggregate under
'github.com'; percentages use the total resource count."""
rows = [
_res("https://www.github.com/a"),
_res("https://github.com/b"),
_res("https://GITHUB.com/c"),
_res("https://example.com/x"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 4
assert analytics["total_unique_domains"] == 2
by_domain = {d["domain"]: d for d in analytics["top_domains"]}
assert set(by_domain) == {"github.com", "example.com"}
assert by_domain["github.com"]["count"] == 3
assert by_domain["github.com"]["percentage"] == 75.0
assert by_domain["example.com"]["count"] == 1
assert by_domain["example.com"]["percentage"] == 25.0
def test_top_domains_ordered_by_count_desc_with_ranks(self):
"""top_domains is sorted by usage count (not insertion order) and
domain_metrics carries matching 1-based frequency ranks."""
rows = []
# Interleave insertions so insertion order != frequency order.
for i in range(5):
rows.append(_res(f"https://alpha.com/{i}"))
if i < 3:
rows.append(_res(f"https://beta.com/{i}"))
if i < 1:
rows.append(_res(f"https://gamma.com/{i}"))
# Shuffle deterministically: reverse so gamma/beta come first.
rows.reverse()
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
ordered = [(d["domain"], d["count"]) for d in analytics["top_domains"]]
assert ordered == [("alpha.com", 5), ("beta.com", 3), ("gamma.com", 1)]
metrics = analytics["domain_metrics"]
assert metrics["alpha.com"]["frequency_rank"] == 1
assert metrics["beta.com"]["frequency_rank"] == 2
assert metrics["gamma.com"]["frequency_rank"] == 3
assert metrics["alpha.com"]["usage_count"] == 5
def test_top_10_truncation_and_domain_distribution(self):
"""With 12 unique domains only 10 are returned; domain_distribution
splits totals into top-10 vs others."""
rows = [_res(f"https://big.com/{i}") for i in range(3)]
rows += [_res(f"https://d{i:02d}.com/x") for i in range(11)]
# 14 resources, 12 unique domains: big.com(3) + 11 singles.
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
assert analytics["total_unique_domains"] == 12
assert len(analytics["top_domains"]) == 10
assert analytics["top_domains"][0]["domain"] == "big.com"
# top-10 holds big.com's 3 plus nine singles = 12; two left over.
assert analytics["domain_distribution"] == {"top_10": 12, "others": 2}
def test_avg_links_and_per_domain_research_diversity(self):
"""avg_links_per_research = links / unique researches (rounded to 1);
a domain used by both researches reports research_count == 2."""
rows = [
_res("https://example.com/1", research_id="research_1"),
_res("https://other.com/2", research_id="research_1"),
_res("https://example.com/3", research_id="research_2"),
_res("https://example.com/4", research_id="research_2"),
_res("https://other.com/5", research_id="research_2"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 5
assert analytics["total_researches"] == 2
assert analytics["avg_links_per_research"] == 2.5
by_domain = {d["domain"]: d for d in analytics["top_domains"]}
assert by_domain["example.com"]["research_count"] == 2
assert by_domain["other.com"]["research_count"] == 2
assert (
analytics["domain_metrics"]["example.com"]["research_diversity"]
== 2
)
def test_null_and_unparseable_urls_skip_domains_not_totals(self):
"""Rows whose URL is NULL or yields no netloc are excluded from
domain aggregation but still count toward total_links (the
percentage denominator)."""
rows = [
_res(None),
_res("not a url"),
_res("https://real.com/x"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 3
assert analytics["total_unique_domains"] == 1
assert len(analytics["top_domains"]) == 1
entry = analytics["top_domains"][0]
assert entry["domain"] == "real.com"
assert entry["count"] == 1
assert entry["percentage"] == 33.3 # 1/3 of ALL rows
class TestPeriodFiltering:
"""Period string → created_at cutoff applied to the resource scan."""
def test_7d_period_excludes_older_resources(self):
rows = [
_res("https://recent.com/a", days_ago=2),
_res("https://old.com/b", days_ago=20),
]
with _seeded_db(*rows):
result = get_link_analytics(period="7d", username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 1
assert [d["domain"] for d in analytics["top_domains"]] == ["recent.com"]
def test_all_period_includes_everything(self):
rows = [
_res("https://recent.com/a", days_ago=2),
_res("https://old.com/b", days_ago=20),
_res("https://ancient.com/c", days_ago=400),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
assert result["link_analytics"]["total_links"] == 3
def test_unknown_period_defaults_to_30_days(self):
"""Unrecognized period strings fall back to the 30-day window
(get_period_days default) instead of erroring or going unfiltered."""
rows = [
_res("https://recent.com/a", days_ago=5),
_res("https://old.com/b", days_ago=40),
]
with _seeded_db(*rows):
result = get_link_analytics(
period="bogus-period", username="test_user"
)
analytics = result["link_analytics"]
assert analytics["total_links"] == 1
assert [d["domain"] for d in analytics["top_domains"]] == ["recent.com"]
def test_365d_alias_window(self):
"""The link-analytics UI vocabulary ('365d') maps to a year window."""
rows = [
_res("https://thisyear.com/a", days_ago=100),
_res("https://lastyear.com/b", days_ago=400),
]
with _seeded_db(*rows):
result = get_link_analytics(period="365d", username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 1
assert [d["domain"] for d in analytics["top_domains"]] == [
"thisyear.com"
]
def test_omitted_period_defaults_to_30_day_window(self):
"""Calling without a period argument uses the function's own '30d'
default — a 40-day-old resource is filtered out, a 5-day-old one
kept (guards the signature default, not just get_period_days)."""
rows = [
_res("https://recent.com/a", days_ago=5),
_res("https://old.com/b", days_ago=40),
]
with _seeded_db(*rows):
result = get_link_analytics(username="test_user")
analytics = result["link_analytics"]
assert analytics["total_links"] == 1
assert [d["domain"] for d in analytics["top_domains"]] == ["recent.com"]
class TestSourceTypesCategoriesAndTrend:
def test_source_type_analysis_counts_and_skips_null(self):
rows = [
_res("https://a.com/1", source_type="web"),
_res("https://a.com/2", source_type="web"),
_res("https://b.com/3", source_type="academic"),
_res("https://b.com/4", source_type=None),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
assert result["link_analytics"]["source_type_analysis"] == {
"web": 2,
"academic": 1,
}
def test_category_distribution_from_domain_classifications(self):
"""Classified domains count per-resource under their LLM category;
unclassified domains fall into 'Unclassified'; top_domains carries
the classification payload (or None) per domain — all via the
batch-loaded DomainClassification table, no classifier calls."""
rows = [
DomainClassification(
domain="arxiv.org",
category="Academic",
subcategory="Physics",
confidence=0.9,
),
_res("https://arxiv.org/abs/1"),
_res("https://arxiv.org/abs/2"),
_res("https://randomblog.com/post"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
assert analytics["category_distribution"] == {
"Academic": 2,
"Unclassified": 1,
}
# domain_categories mirrors the same generic pie-chart data.
assert (
analytics["domain_categories"] == analytics["category_distribution"]
)
by_domain = {d["domain"]: d for d in analytics["top_domains"]}
assert by_domain["arxiv.org"]["classification"] == {
"category": "Academic",
"subcategory": "Physics",
"confidence": 0.9,
}
assert by_domain["randomblog.com"]["classification"] is None
def test_temporal_trend_daily_counts_sorted_by_date(self):
"""Daily counts come from the created_at date prefix and are sorted
chronologically regardless of row insertion order."""
rows = [
_res("https://a.com/1", created_at="2026-07-30T10:00:00+00:00"),
_res("https://a.com/2", created_at="2026-07-28T09:00:00+00:00"),
_res("https://a.com/3", created_at="2026-07-30T23:59:00+00:00"),
_res("https://a.com/4", created_at="2026-07-29T00:00:00+00:00"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
assert result["link_analytics"]["temporal_trend"] == [
{"date": "2026-07-28", "count": 1},
{"date": "2026-07-29", "count": 1},
{"date": "2026-07-30", "count": 2},
]
class TestRecentResearches:
def test_recent_researches_truncate_query_and_drop_missing_history(self):
"""Each top domain lists its researches with the query truncated to
50 chars; research IDs without a ResearchHistory row are dropped
rather than fabricated."""
long_query = "Q" * 60
now_iso = datetime.now(UTC).isoformat()
rows = [
ResearchHistory(
id="r1",
query=long_query,
mode="quick",
status="completed",
created_at=now_iso,
),
_res("https://example.com/1", research_id="r1"),
# r2 has resources but no history row -> must not appear.
_res("https://example.com/2", research_id="r2"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
analytics = result["link_analytics"]
entry = analytics["top_domains"][0]
assert entry["domain"] == "example.com"
assert entry["research_count"] == 2
recent = entry["recent_researches"]
assert recent == [{"id": "r1", "query": long_query[:50]}]
assert len(recent[0]["query"]) == 50
def test_empty_query_falls_back_to_research_placeholder(self):
"""A history row whose query is empty (falsy) is labeled with the
'Research' placeholder instead of an empty string."""
now_iso = datetime.now(UTC).isoformat()
rows = [
ResearchHistory(
id="rq",
query="",
mode="quick",
status="completed",
created_at=now_iso,
),
_res("https://example.com/1", research_id="rq"),
]
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
entry = result["link_analytics"]["top_domains"][0]
assert entry["recent_researches"] == [{"id": "rq", "query": "Research"}]
def test_recent_researches_capped_at_three_per_domain(self):
"""A domain used by five researches (all with history rows) lists at
most three of them, each carrying its real query text."""
now_iso = datetime.now(UTC).isoformat()
rows = []
for i in range(1, 6):
rows.append(
ResearchHistory(
id=f"r{i}",
query=f"query {i}",
mode="quick",
status="completed",
created_at=now_iso,
)
)
rows.append(_res(f"https://one.com/{i}", research_id=f"r{i}"))
with _seeded_db(*rows):
result = get_link_analytics(period="all", username="test_user")
entry = result["link_analytics"]["top_domains"][0]
assert entry["domain"] == "one.com"
assert entry["research_count"] == 5
recent = entry["recent_researches"]
# Which three is set-order dependent; the cap and payload are not.
assert len(recent) == 3
for item in recent:
assert item["id"] in {f"r{i}" for i in range(1, 6)}
assert item["query"] == f"query {item['id'][1:]}"