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.

35.8 KB
Raw Blame
"""
Extended tests for notifications/queue_helpers.py — _from_session functions.

The existing test_queue_helpers.py only verifies "function exists" and
"handles None db_session" for the _from_session functions.  These tests
exercise the actual DB-lookup + notification-sending logic (~300 lines).

NOTE: This commit also fixes a bug where the _from_session functions used
3-dot relative imports (from ...settings) instead of 2-dot (from ..settings),
causing all _from_session notifications to silently fail.

Tests cover:
- send_queue_failed_notification_from_session: settings retrieval, success/failure logging
- send_research_completed_notification_from_session: research lookup, report truncation, URL building
- send_research_failed_notification_from_session: error sanitization, research lookup
"""

from unittest.mock import Mock, MagicMock, patch


HELPERS = "local_deep_research.notifications.queue_helpers"

# Patch targets for lazy imports inside _from_session functions.
# These must be patched at their SOURCE module since the functions use
# 'from ..X import Y' which resolves to the source, not the caller module.
SETTINGS_MGR = "local_deep_research.settings.SettingsManager"
NOTIF_MGR = "local_deep_research.notifications.manager.NotificationManager"
URL_BUILDER = (
    "local_deep_research.notifications.url_builder.build_notification_url"
)
REPORT_STORAGE = "local_deep_research.storage.get_report_storage"


# ---------------------------------------------------------------------------
# send_queue_failed_notification_from_session
# ---------------------------------------------------------------------------


class TestSendQueueFailedNotificationFromSession:
    """Tests for send_queue_failed_notification_from_session."""

    @patch(f"{HELPERS}.send_queue_failed_notification")
    def test_success_path_sends_notification(self, mock_send):
        """Success path: creates settings snapshot, calls send."""
        from local_deep_research.notifications.queue_helpers import (
            send_queue_failed_notification_from_session,
        )

        mock_send.return_value = True

        mock_db = MagicMock()
        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {"snap": True}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_queue_failed_notification_from_session(
                username="alice",
                research_id="r-001",
                query="test query",
                error_message="Timeout",
                db_session=mock_db,
            )

        mock_send.assert_called_once_with(
            username="alice",
            research_id="r-001",
            query="test query",
            error_message="Timeout",
            settings_snapshot={"snap": True},
        )

    @patch(f"{HELPERS}.send_queue_failed_notification")
    def test_send_returns_false_logs_warning(self, mock_send):
        """When send returns False, logs warning (doesn't raise)."""
        from local_deep_research.notifications.queue_helpers import (
            send_queue_failed_notification_from_session,
        )

        mock_send.return_value = False

        mock_db = MagicMock()
        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            # Should not raise
            send_queue_failed_notification_from_session(
                username="alice",
                research_id="r-002",
                query="q",
                error_message="err",
                db_session=mock_db,
            )

    def test_settings_manager_raises_caught_silently(self):
        """SettingsManager exception is caught silently."""
        from local_deep_research.notifications.queue_helpers import (
            send_queue_failed_notification_from_session,
        )

        mock_db = MagicMock()

        with patch(SETTINGS_MGR, side_effect=RuntimeError("bad session")):
            # Should not raise
            send_queue_failed_notification_from_session(
                username="alice",
                research_id="r-003",
                query="q",
                error_message="err",
                db_session=mock_db,
            )

    @patch(f"{HELPERS}.send_queue_failed_notification")
    def test_send_returns_true_logs_info(self, mock_send):
        """When send returns True, logs info (success path)."""
        from local_deep_research.notifications.queue_helpers import (
            send_queue_failed_notification_from_session,
        )

        mock_send.return_value = True
        mock_db = MagicMock()
        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_queue_failed_notification_from_session(
                username="alice",
                research_id="r-004",
                query="q",
                error_message="err",
                db_session=mock_db,
            )

        mock_send.assert_called_once()


# ---------------------------------------------------------------------------
# send_research_completed_notification_from_session
# ---------------------------------------------------------------------------


class TestSendResearchCompletedNotificationFromSession:
    """Tests for send_research_completed_notification_from_session."""

    @patch(REPORT_STORAGE)
    @patch(URL_BUILDER)
    @patch(NOTIF_MGR)
    def test_research_found_builds_context_with_query_and_url(
        self, mock_nm_class, mock_build_url, mock_get_storage
    ):
        """When research is found, context includes query, URL, summary."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )
        from local_deep_research.notifications.templates import EventType

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "How does AI work?"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )

        mock_build_url.return_value = "https://app.test/research/r-100"

        mock_storage = Mock()
        mock_storage.get_report.return_value = "Short report"
        mock_get_storage.return_value = mock_storage

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_completed_notification_from_session(
                username="alice",
                research_id="r-100",
                db_session=mock_db,
            )

        call_kwargs = mock_nm.send_notification.call_args.kwargs
        assert call_kwargs["event_type"] == EventType.RESEARCH_COMPLETED
        ctx = call_kwargs["context"]
        assert ctx["query"] == "How does AI work?"
        assert ctx["url"] == "https://app.test/research/r-100"
        assert ctx["summary"] == "Short report"

    @patch(REPORT_STORAGE)
    @patch(URL_BUILDER)
    @patch(NOTIF_MGR)
    def test_report_over_200_chars_truncated(
        self, mock_nm_class, mock_build_url, mock_get_storage
    ):
        """Report content >200 chars is truncated with '...'."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "query"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )
        mock_build_url.return_value = "https://app.test/r"

        long_report = "A" * 300
        mock_storage = Mock()
        mock_storage.get_report.return_value = long_report
        mock_get_storage.return_value = mock_storage

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_completed_notification_from_session(
                username="alice", research_id="r-101", db_session=mock_db
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["summary"] == "A" * 200 + "..."
        assert len(ctx["summary"]) == 203

    @patch(REPORT_STORAGE)
    @patch(URL_BUILDER)
    @patch(NOTIF_MGR)
    def test_report_exactly_200_chars_not_truncated(
        self, mock_nm_class, mock_build_url, mock_get_storage
    ):
        """Report content <=200 chars is used as-is."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "query"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )
        mock_build_url.return_value = "https://app.test/r"

        report_200 = "B" * 200
        mock_storage = Mock()
        mock_storage.get_report.return_value = report_200
        mock_get_storage.return_value = mock_storage

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_completed_notification_from_session(
                username="alice", research_id="r-102", db_session=mock_db
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["summary"] == "B" * 200

    @patch(REPORT_STORAGE)
    @patch(URL_BUILDER)
    @patch(NOTIF_MGR)
    def test_report_none_uses_default_summary(
        self, mock_nm_class, mock_build_url, mock_get_storage
    ):
        """Report is None -> summary is 'No summary available'."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "query"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )
        mock_build_url.return_value = "https://app.test/r"

        mock_storage = Mock()
        mock_storage.get_report.return_value = None
        mock_get_storage.return_value = mock_storage

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_completed_notification_from_session(
                username="alice", research_id="r-103", db_session=mock_db
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["summary"] == "No summary available"

    @patch(NOTIF_MGR)
    def test_research_not_found_sends_minimal_context(self, mock_nm_class):
        """Research not found -> sends notification with minimal context."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            None
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_completed_notification_from_session(
                username="alice", research_id="r-999", db_session=mock_db
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["query"] == "Research r-999"
        assert ctx["summary"] == "Research completed but details unavailable"

    def test_exception_caught_silently(self):
        """Top-level exception is caught silently."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.side_effect = RuntimeError("DB gone")

        # Should not raise
        send_research_completed_notification_from_session(
            username="alice", research_id="r-998", db_session=mock_db
        )

    @patch(REPORT_STORAGE)
    @patch(URL_BUILDER)
    @patch(NOTIF_MGR)
    def test_send_returns_false_does_not_raise(
        self, mock_nm_class, mock_build_url, mock_get_storage
    ):
        """send_notification returning False doesn't raise."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "query"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )
        mock_build_url.return_value = "https://app.test/r"
        mock_storage = Mock()
        mock_storage.get_report.return_value = "report"
        mock_get_storage.return_value = mock_storage

        mock_nm = Mock()
        mock_nm.send_notification.return_value = False
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            # Should not raise
            send_research_completed_notification_from_session(
                username="alice", research_id="r-104", db_session=mock_db
            )


# ---------------------------------------------------------------------------
# send_research_failed_notification_from_session
# ---------------------------------------------------------------------------


class TestSendResearchFailedNotificationFromSession:
    """Tests for send_research_failed_notification_from_session."""

    @patch(NOTIF_MGR)
    def test_sanitizes_error_message(self, mock_nm_class):
        """Error message is sanitized to generic 'Check logs' message."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "test"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_failed_notification_from_session(
                username="alice",
                research_id="r-200",
                error_message="SECRET: API key abc123 leaked",
                db_session=mock_db,
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["error"] == "Research failed. Check logs for details."

    @patch(NOTIF_MGR)
    def test_original_error_not_in_notification(self, mock_nm_class):
        """Original error_message is NOT passed to notification context."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "test"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_failed_notification_from_session(
                username="alice",
                research_id="r-201",
                error_message="password=hunter2 connection refused",
                db_session=mock_db,
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert "hunter2" not in str(ctx)
        assert "password" not in str(ctx)

    @patch(NOTIF_MGR)
    def test_research_not_found_sends_minimal(self, mock_nm_class):
        """Research not found -> sends minimal context."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            None
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_failed_notification_from_session(
                username="alice",
                research_id="r-999",
                error_message="not found",
                db_session=mock_db,
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["query"] == "Research r-999"
        assert ctx["error"] == "Research failed. Check logs for details."

    def test_exception_caught_silently(self):
        """Top-level exception is caught silently."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.side_effect = RuntimeError("DB gone")

        # Should not raise
        send_research_failed_notification_from_session(
            username="alice",
            research_id="r-998",
            error_message="error",
            db_session=mock_db,
        )

    @patch(NOTIF_MGR)
    def test_research_found_uses_query_from_db(self, mock_nm_class):
        """When research is found, uses research.query from DB."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "What is quantum computing?"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            send_research_failed_notification_from_session(
                username="alice",
                research_id="r-202",
                error_message="timeout",
                db_session=mock_db,
            )

        ctx = mock_nm.send_notification.call_args.kwargs["context"]
        assert ctx["query"] == "What is quantum computing?"


# ---------------------------------------------------------------------------
# Regression: minimal-details logging path must not double-log
# (see PR #5082 review feedback).
# ---------------------------------------------------------------------------


def _result(sent: bool, reason_value: str = "sent", detail: str = ""):
    """Build a real ``NotificationResult`` with the given outcome so the
    queue-helper code under test sees the same dataclass type that
    ``NotificationManager.send_notification`` actually returns.  We need a
    genuine ``NotificationResult`` (not a duck-typed stub) because
    ``_format_reason`` uses ``isinstance(result, NotificationResult)`` to
    pick the rendering branch.
    """
    from local_deep_research.notifications.manager import (
        NotificationReason,
        NotificationResult,
    )

    return NotificationResult(
        sent=sent,
        reason=NotificationReason(reason_value),
        detail=detail,
    )


class TestMinimalDetailsLoggingRegression:
    """Regression coverage for the duplicate / contradictory log lines that
    the minimal-details (research-not-found) paths used to emit when the
    new conditional logger.info/warning block was added on top of a
    pre-existing unconditional logger.info line.
    """

    @patch(NOTIF_MGR)
    def test_completed_minimal_success_logs_once(
        self, mock_nm_class, loguru_caplog
    ):
        """Minimal-details success: a single 'Sent ...' INFO, no warning."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            None
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=True, reason_value="sent"
        )
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            with loguru_caplog.at_level("INFO"):
                send_research_completed_notification_from_session(
                    username="alice",
                    research_id="r-min",
                    db_session=mock_db,
                )

        sent_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Sent completion notification" in rec.message
        ]
        warning_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Completion notification not sent" in rec.message
        ]
        assert len(sent_lines) == 1, sent_lines
        assert warning_lines == []

    @patch(NOTIF_MGR)
    def test_completed_minimal_failure_logs_warning_only(
        self, mock_nm_class, loguru_caplog
    ):
        """Minimal-details failure: a single WARNING, no contradictory INFO."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            None
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=False,
            reason_value="unconfigured",
            detail="notifications.service_url is not configured",
        )
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            with loguru_caplog.at_level("INFO"):
                send_research_completed_notification_from_session(
                    username="alice",
                    research_id="r-min",
                    db_session=mock_db,
                )

        sent_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Sent completion notification" in rec.message
        ]
        warning_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Completion notification not sent" in rec.message
        ]
        assert sent_lines == [], sent_lines
        assert len(warning_lines) == 1, warning_lines
        assert "unconfigured" in warning_lines[0]
        assert "notifications.service_url" in warning_lines[0]

    @patch(NOTIF_MGR)
    def test_failed_minimal_success_logs_once(
        self, mock_nm_class, loguru_caplog
    ):
        """Failed-research minimal-details success: single INFO, no warning."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            None
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=True, reason_value="sent"
        )
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            with loguru_caplog.at_level("INFO"):
                send_research_failed_notification_from_session(
                    username="alice",
                    research_id="r-min",
                    error_message="boom",
                    db_session=mock_db,
                )

        sent_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Sent failure notification" in rec.message
        ]
        warning_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Failure notification not sent" in rec.message
        ]
        assert len(sent_lines) == 1, sent_lines
        assert warning_lines == []

    @patch(NOTIF_MGR)
    def test_failed_minimal_failure_logs_warning_only(
        self, mock_nm_class, loguru_caplog
    ):
        """Failed-research minimal-details failure: single WARNING."""
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            None
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=False,
            reason_value="egress_denied",
            detail="all configured URLs refused by egress policy",
        )
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            with loguru_caplog.at_level("INFO"):
                send_research_failed_notification_from_session(
                    username="alice",
                    research_id="r-min",
                    error_message="boom",
                    db_session=mock_db,
                )

        sent_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Sent failure notification" in rec.message
        ]
        warning_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Failure notification not sent" in rec.message
        ]
        assert sent_lines == [], sent_lines
        assert len(warning_lines) == 1, warning_lines
        assert "egress_denied" in warning_lines[0]


# ---------------------------------------------------------------------------
# Regression: the found-research warning paths must carry the precise
# reason. These are the PR #5082 headline hunks that previously had no
# coverage — reverting them to the old "(disabled)" literal must fail
# these tests (issue #5110).
# ---------------------------------------------------------------------------


class TestFoundResearchReasonLogging:
    """Log assertions for the found-research (non-minimal) paths."""

    @patch(REPORT_STORAGE)
    @patch(URL_BUILDER)
    @patch(NOTIF_MGR)
    def test_completed_found_failure_warns_with_reason(
        self, mock_nm_class, mock_build_url, mock_get_storage, loguru_caplog
    ):
        from local_deep_research.notifications.queue_helpers import (
            send_research_completed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "How does AI work?"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )
        mock_build_url.return_value = "https://app.test/research/r-found"
        mock_storage = Mock()
        mock_storage.get_report.return_value = "Short report"
        mock_get_storage.return_value = mock_storage

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=False,
            reason_value="unconfigured",
            detail="notifications.service_url is not configured",
        )
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            with loguru_caplog.at_level("INFO"):
                send_research_completed_notification_from_session(
                    username="alice",
                    research_id="r-found",
                    db_session=mock_db,
                )

        warning_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Completion notification not sent" in rec.message
        ]
        assert len(warning_lines) == 1, warning_lines
        assert "unconfigured" in warning_lines[0]
        assert "notifications.service_url" in warning_lines[0]
        assert "(disabled)" not in warning_lines[0]

    @patch(NOTIF_MGR)
    def test_failed_found_failure_warns_with_reason(
        self, mock_nm_class, loguru_caplog
    ):
        from local_deep_research.notifications.queue_helpers import (
            send_research_failed_notification_from_session,
        )

        mock_db = MagicMock()
        mock_research = Mock()
        mock_research.query = "What is quantum computing?"
        mock_db.query.return_value.filter_by.return_value.first.return_value = (
            mock_research
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=False,
            reason_value="egress_denied",
            detail="all configured URLs refused by egress policy",
        )
        mock_nm_class.return_value = mock_nm

        mock_settings = Mock()
        mock_settings.get_settings_snapshot.return_value = {}

        with patch(SETTINGS_MGR, return_value=mock_settings):
            with loguru_caplog.at_level("INFO"):
                send_research_failed_notification_from_session(
                    username="alice",
                    research_id="r-found",
                    error_message="boom",
                    db_session=mock_db,
                )

        warning_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Failure notification not sent" in rec.message
        ]
        assert len(warning_lines) == 1, warning_lines
        assert "egress_denied" in warning_lines[0]
        assert "(disabled)" not in warning_lines[0]


# ---------------------------------------------------------------------------
# Coverage for the send_queue_notification / send_queue_failed_notification
# wrappers: drop-reason logging at DEBUG, bool coercion at the boundary, and
# _format_reason's legacy-bool fallback (issue #5110).
# ---------------------------------------------------------------------------


class TestQueueWrapperHelpers:
    """Behavior of the thin queue wrappers around send_notification."""

    @patch(f"{HELPERS}.NotificationManager")
    def test_queued_drop_returns_false_and_logs_reason_at_debug(
        self, mock_nm_class, loguru_caplog
    ):
        from local_deep_research.notifications.queue_helpers import (
            send_queue_notification,
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=False,
            reason_value="unconfigured",
            detail="notifications.service_url is not configured",
        )
        mock_nm_class.return_value = mock_nm

        with loguru_caplog.at_level("DEBUG"):
            returned = send_queue_notification(
                username="alice",
                research_id="r-q",
                query="q",
                settings_snapshot={"any": "thing"},
            )

        assert returned is False
        reason_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Queue notification not sent" in rec.message
        ]
        assert len(reason_lines) == 1, reason_lines
        assert "unconfigured" in reason_lines[0]

    @patch(f"{HELPERS}.NotificationManager")
    def test_queued_success_returns_true_without_warning(
        self, mock_nm_class, loguru_caplog
    ):
        from local_deep_research.notifications.queue_helpers import (
            send_queue_notification,
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(sent=True)
        mock_nm_class.return_value = mock_nm

        with loguru_caplog.at_level("DEBUG"):
            returned = send_queue_notification(
                username="alice",
                research_id="r-q",
                query="q",
                settings_snapshot={"any": "thing"},
            )

        assert returned is True
        assert not [
            rec.message
            for rec in loguru_caplog.records
            if "Queue notification not sent" in rec.message
        ]

    @patch(f"{HELPERS}.NotificationManager")
    def test_queued_legacy_bool_false_logs_dropped(
        self, mock_nm_class, loguru_caplog
    ):
        """Legacy mocks returning a bare bool must still coerce and log
        via _format_reason's fallback branch."""
        from local_deep_research.notifications.queue_helpers import (
            send_queue_notification,
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = False
        mock_nm_class.return_value = mock_nm

        with loguru_caplog.at_level("DEBUG"):
            returned = send_queue_notification(
                username="alice",
                research_id="r-q",
                query="q",
                settings_snapshot={"any": "thing"},
            )

        assert returned is False
        reason_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Queue notification not sent" in rec.message
        ]
        assert len(reason_lines) == 1, reason_lines
        assert "(dropped)" in reason_lines[0]

    @patch(f"{HELPERS}.NotificationManager")
    def test_queued_legacy_bool_true_returns_true(self, mock_nm_class):
        from local_deep_research.notifications.queue_helpers import (
            send_queue_notification,
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = True
        mock_nm_class.return_value = mock_nm

        returned = send_queue_notification(
            username="alice",
            research_id="r-q",
            query="q",
            settings_snapshot={"any": "thing"},
        )

        assert returned is True

    @patch(f"{HELPERS}.NotificationManager")
    def test_failed_drop_returns_false_and_logs_reason_at_debug(
        self, mock_nm_class, loguru_caplog
    ):
        from local_deep_research.notifications.queue_helpers import (
            send_queue_failed_notification,
        )

        mock_nm = Mock()
        mock_nm.send_notification.return_value = _result(
            sent=False,
            reason_value="server_disabled",
            detail="outbound notifications are disabled at the server level",
        )
        mock_nm_class.return_value = mock_nm

        with loguru_caplog.at_level("DEBUG"):
            returned = send_queue_failed_notification(
                username="alice",
                research_id="r-f",
                query="q",
                error_message="boom",
                settings_snapshot={"any": "thing"},
            )

        assert returned is False
        reason_lines = [
            rec.message
            for rec in loguru_caplog.records
            if "Failed-notification not sent" in rec.message
        ]
        assert len(reason_lines) == 1, reason_lines
        assert "server_disabled" in reason_lines[0]