Explain remote service responses in plain English

backend/tests/test_backend_quality.py

@@ -9,6 +9,9 @@ from fastapi import HTTPException
 from starlette.requests import Request
 
 from backend.app import db
+from backend.app.clients.base import _operation_error_message, _operation_result_message
+from backend.app.clients.jellyfin import _availability_message
+from backend.app.clients.qbittorrent import _torrent_result_message
 from backend.app.auth import require_admin
 from backend.app.config import settings
 from backend.app.network_security import request_trusts_forwarded_headers, validate_notification_target_url
@@ -187,6 +190,80 @@ class OperationProgressTests(unittest.TestCase):
         self.assertEqual(completed["events"][-1]["service"], "Magent")
 
 
+class OperationMessageTests(unittest.TestCase):
+    def test_radarr_lookup_explains_whether_movie_was_found(self) -> None:
+        found = _operation_result_message(
+            "Radarr",
+            "GET",
+            "/api/v3/movie",
+            [{"title": "Arrival"}],
+        )
+        missing = _operation_result_message(
+            "Radarr",
+            "GET",
+            "/api/v3/movie",
+            [],
+        )
+
+        self.assertEqual(found, 'Radarr found "Arrival" in its library list.')
+        self.assertEqual(missing, "This movie is not currently in Radarr.")
+
+    def test_radarr_add_explains_that_download_search_started(self) -> None:
+        message = _operation_result_message(
+            "Radarr",
+            "POST",
+            "/api/v3/movie",
+            {"title": "Arrival", "id": 42},
+            payload={
+                "title": "Arrival",
+                "addOptions": {"searchForMovie": True},
+            },
+        )
+
+        self.assertEqual(message, 'Radarr added "Arrival" and started looking for a download.')
+
+    def test_queue_and_indexer_health_results_are_summarized(self) -> None:
+        queue_message = _operation_result_message(
+            "Sonarr",
+            "GET",
+            "/api/v3/queue",
+            {"totalRecords": 0, "records": []},
+        )
+        health_message = _operation_result_message(
+            "Prowlarr",
+            "GET",
+            "/api/v1/health",
+            [],
+        )
+
+        self.assertEqual(queue_message, "Sonarr has no matching downloads in its queue.")
+        self.assertEqual(health_message, "Prowlarr reports that all configured indexers are healthy.")
+
+    def test_download_and_jellyfin_results_include_actual_state(self) -> None:
+        torrent_message = _torrent_result_message(
+            [{"name": "Arrival.2016", "state": "downloading", "progress": 0.42}]
+        )
+
+        self.assertEqual(
+            torrent_message,
+            'qBittorrent found "Arrival.2016"; it is downloading and 42% complete.',
+        )
+        self.assertEqual(
+            _availability_message({"TotalRecordCount": 0, "Items": []}),
+            "The title is not currently available in Jellyfin.",
+        )
+
+    def test_http_failures_are_translated_without_exposing_stack_traces(self) -> None:
+        self.assertEqual(
+            _operation_error_message("Radarr", 500),
+            "Radarr encountered an internal error while processing the request.",
+        )
+        self.assertEqual(
+            _operation_error_message("Sonarr", 401),
+            "Sonarr rejected Magent's login details.",
+        )
+
+
 class SiteInfoTests(unittest.TestCase):
     def test_site_public_exposes_requests_navigation_toggle(self) -> None:
         runtime = SimpleNamespace(