From 4bcb33d3b11acfa78a3e615027e81457223fabbe Mon Sep 17 00:00:00 2001
From: Carlos Martinez <carlosjmtz@gmail.com>
Date: Wed, 17 Jun 2026 11:50:57 +0100
Subject: [PATCH] Show test docstrings as names in the HTML report

Add pytest hooks so the published test report uses each test's docstring
as its display name (falling back to the node id where there is none),
and titles the report "Rubie Gateway Tests". Makes the report readable
for the assurance audience.
---
 tests/conftest.py | 38 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 38 insertions(+)

diff --git a/tests/conftest.py b/tests/conftest.py
index e0c4a96c..6a2b35a1 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,3 +1,4 @@
+import inspect
 import shutil
 import sys
 from contextlib import contextmanager
@@ -15,6 +16,43 @@
 sys.path.append(f"{Path(__file__).parent.parent}/src")
 
 
+def pytest_html_report_title(report):
+    report.title = "Rubie Gateway Tests"
+
+
+def _readable_test_name(item):
+    """
+    Build a human-readable name for the test report from the test's
+    docstring. Returns None when there is no docstring, so the default
+    nodeid is kept.
+    """
+    test_fn = getattr(item, "obj", None)
+    docstring = inspect.getdoc(test_fn) if test_fn else None
+    if not docstring:
+        return None
+
+    # First non-empty line, whitespace collapsed — docstrings are often
+    # multi-line and indented, which would render badly as a node id.
+    first_line = next((line.strip() for line in docstring.splitlines() if line.strip()), "")
+    if not first_line:
+        return None
+
+    # Keep parametrised cases distinct (they share one docstring).
+    param_id = getattr(getattr(item, "callspec", None), "id", None)
+    return f"{first_line} [{param_id}]" if param_id else first_line
+
+
+@pytest.hookimpl(hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    """Use the test's docstring as its name in the HTML report, when present."""
+    outcome = yield
+    report = outcome.get_result()
+
+    readable_name = _readable_test_name(item)
+    if readable_name:
+        report.nodeid = readable_name
+
+
 @pytest.fixture(autouse=True)
 def mock_azure_credential():
     mock = MagicMock()