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.

18.7 KB
Raw Blame
"""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:]}"