Update tr_link to support pattern matching

Author: cuinixam

docs/functions.rst

@@ -33,6 +33,10 @@ Then it goes through **all** other needs and checks if the value of their ``sour
 the ``target_option``.
 If this is the case, their IDs get stored and finally returned.
 
+In case the ``source_option`` contains a ``*`` (e.g. ``sphinxcontrib.test_reports.*``), the function will check if the
+``target_option`` matches the ``source_option``. This is useful if one wants to link multiple test results to one test case.
+
+
 **Example**::
 
    .. spec:: sphinxcontrib.test_reports.test_reports

sphinxcontrib/test_reports/functions/__init__.py

@@ -1,15 +1,28 @@
+import re
+
+
 def tr_link(app, need, needs, test_option, target_option, *args, **kwargs):
     if test_option not in need:
         return ""
-    test_opt = need[test_option]
+    test_option_value = need[test_option]
+    if test_option_value is None or len(test_option_value) <= 0:
+        return []
 
     links = []
+    test_pattern = re.compile(test_option_value)
     for need_target in needs.values():
+        # Skip linking to itself
+        if need_target["id"] == need["id"]:
+            continue
+
         if target_option not in need_target:
             continue
 
+        target_option_value = need_target[target_option]
         if (
-            test_opt == need_target[target_option] and test_opt is not None and len(test_opt) > 0  # fmt: skip
+            target_option_value is not None
+            and len(target_option_value) > 0
+            and test_pattern.match(target_option_value)
         ):
             links.append(need_target["id"])
 

tests/test_tr_link.py

@@ -5,31 +5,113 @@ def test_tr_link_option_not_in_need():
     """
     Return an empty string when the specified test option is missing from the need.
     """
-    assert tr_link(app=None, need={}, needs={}, test_option="a", target_option="b") == ""
+    assert (
+        tr_link(app=None, need={}, needs={}, test_option="a", target_option="b") == ""
+    )
+
 
 def test_tr_link_no_target_option_in_needs():
     """
     Return an empty list when the target option is missing in all items of needs.
     """
-    assert tr_link(app=None, need={"a": "1"}, needs={"x": {"id": "123"}}, test_option="a", target_option="b") == []
+    assert (
+        tr_link(
+            app=None,
+            need={"id": "1", "a": "1"},
+            needs={"x": {"id": "123"}},
+            test_option="a",
+            target_option="b",
+        )
+        == []
+    )
+
 
 def test_tr_link_no_match():
     """
-    Returns an empty list when no matching value for the test option is found in any of the target options within needs.
+    Returns an empty list when no matching value for the test option is found
+    in any of the target options within needs.
     """
-    assert tr_link(app=None, need={"a": "1"}, needs={"x": {"b": "2", "id": "123"}}, test_option="a", target_option="b") == []
+    assert (
+        tr_link(
+            app=None,
+            need={"id": "1", "a": "1"},
+            needs={"x": {"b": "2", "id": "123"}},
+            test_option="a",
+            target_option="b",
+        )
+        == []
+    )
+
 
 def test_tr_link_match():
     """
     Returns a list of ids when there is a matching value in both need and needs.
     """
-    assert tr_link(app=None, need={"a": "1"}, needs={"x": {"b": "1", "id": "123"}}, test_option="a", target_option="b") == ["123"]
+    assert tr_link(
+        app=None,
+        need={"id": "1", "a": "1"},
+        needs={"x": {"b": "1", "id": "123"}},
+        test_option="a",
+        target_option="b",
+    ) == ["123"]
+
 
 def test_tr_link_none_or_empty():
     """
     'None' and empty string values are not considered as valid matches.
     """
-    need = {"a": None, "b": ""}
-    needs = {"x": {"c": None, "id": "111"}, "y": {"c": "valid", "id": "222"}, "z": {"c": "", "id": "333"}}
-    assert tr_link(app=None, need=need, needs=needs, test_option="b", target_option="c") == []
-    assert tr_link(app=None, need=need, needs=needs, test_option="a", target_option="c") == []
+    need = {"id": "1", "a": None, "b": ""}
+    needs = {
+        "x": {"c": None, "id": "111"},
+        "y": {"c": "valid", "id": "222"},
+        "z": {"c": "", "id": "333"},
+    }
+    assert (
+        tr_link(app=None, need=need, needs=needs, test_option="b", target_option="c")
+        == []
+    )
+    assert (
+        tr_link(app=None, need=need, needs=needs, test_option="a", target_option="c")
+        == []
+    )
+
+
+def test_tr_link_regex_match():
+    """
+    Returns a list of ids when the test option value containing an asterisk (*)
+    correctly matches target options using regular expression patterns.
+    """
+    needs = {
+        "x": {"b": "abc123", "id": "111"},
+        "q": {"b": "abc/123", "id": "112"},
+        "y": {"b": "def456", "id": "222"},
+        "z": {"b": "ghi789", "id": "333"},
+    }
+    need = {"id": "1", "a": "abc.*"}
+    assert tr_link(
+        app=None, need=need, needs=needs, test_option="a", target_option="b"
+    ) == ["111", "112"]
+
+
+def test_tr_link_regex_no_match():
+    """
+    Returns an empty list when the test option value containing an asterisk (*)
+    does not match any target options using regular expression patterns.
+    """
+    needs = {"x": {"b": "abc123", "id": "111"}, "y": {"b": "def456", "id": "222"}}
+    need = {"id": "1", "a": "xyz.*"}
+    assert (
+        tr_link(app=None, need=need, needs=needs, test_option="a", target_option="b")
+        == []
+    )
+
+
+def test_tr_link_skip_linking_to_itself():
+    """
+    Returns an empty list when the need and needs have the same 'id'.
+    """
+    needs = {"x": {"b": "abc123", "id": "111"}, "y": {"b": "abc123", "id": "222"}}
+    need = {"id": "111", "a": "abc123"}
+    assert tr_link(
+        app=None, need=need, needs=needs, test_option="a", target_option="b"
+    ) == ["222"]