From 120eb1f31b155e9cd2d27bec71b503ab8c8644a6 Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Wed, 22 Jul 2026 19:35:04 +0200
Subject: [PATCH] test: cover run citation registration

---
 .../shared/citations/test_markers.py          | 12 ++++++
 .../capabilities/access/test_run_citation.py  | 43 +++++++++++++++++++
 2 files changed, 55 insertions(+)
 create mode 100644 surfsense_backend/tests/unit/capabilities/access/test_run_citation.py

diff --git a/surfsense_backend/tests/unit/agents/multi_agent_chat/shared/citations/test_markers.py b/surfsense_backend/tests/unit/agents/multi_agent_chat/shared/citations/test_markers.py
index 53cf058a8..5710bc7a6 100644
--- a/surfsense_backend/tests/unit/agents/multi_agent_chat/shared/citations/test_markers.py
+++ b/surfsense_backend/tests/unit/agents/multi_agent_chat/shared/citations/test_markers.py
@@ -37,6 +37,18 @@ def test_web_result_maps_to_url() -> None:
     assert to_frontend_payload(entry) == "https://example.com/a"
 
 
+def test_run_maps_to_run_handle() -> None:
+    entry = _entry(CitationSourceType.RUN, {"run_id": "run_abc-123"})
+
+    assert to_frontend_payload(entry) == "run_abc-123"
+
+
+def test_run_without_handle_is_dropped() -> None:
+    entry = _entry(CitationSourceType.RUN, {})
+
+    assert to_frontend_payload(entry) is None
+
+
 def test_not_yet_renderable_kind_is_dropped() -> None:
     entry = _entry(CitationSourceType.CHAT_TURN, {"thread_id": 1, "turn": 2})
 
diff --git a/surfsense_backend/tests/unit/capabilities/access/test_run_citation.py b/surfsense_backend/tests/unit/capabilities/access/test_run_citation.py
new file mode 100644
index 000000000..6da9e5f29
--- /dev/null
+++ b/surfsense_backend/tests/unit/capabilities/access/test_run_citation.py
@@ -0,0 +1,43 @@
+"""Unit tests for registering a scraper run as a citation."""
+
+from __future__ import annotations
+
+import pytest
+
+from app.agents.chat.multi_agent_chat.shared.citations import (
+    CitationRegistry,
+    CitationSourceType,
+    to_frontend_payload,
+)
+from app.capabilities.core.access.run_citation import attach_run_citation
+
+pytestmark = pytest.mark.unit
+
+
+def test_attaches_run_and_returns_label_with_ordinal() -> None:
+    registry = CitationRegistry()
+
+    n, label = attach_run_citation(
+        registry, run_external_id="run_abc-123", capability="walmart.scrape"
+    )
+
+    assert n == 1
+    assert f"[{n}]" in label
+    entry = registry.resolve(n)
+    assert entry is not None
+    assert entry.source_type is CitationSourceType.RUN
+    assert to_frontend_payload(entry) == "run_abc-123"
+
+
+def test_same_run_dedups_to_one_label() -> None:
+    registry = CitationRegistry()
+
+    first, _ = attach_run_citation(
+        registry, run_external_id="run_x", capability="walmart.scrape"
+    )
+    again, _ = attach_run_citation(
+        registry, run_external_id="run_x", capability="walmart.reviews"
+    )
+
+    assert first == again
+    assert len(registry.by_n) == 1