Export Test Run artifacts in SPDX traceability (#308)

Include on-disk Test Run artifacts as SPDX Files (purpose evidence)
with content MD5 and ExternalIdentifiers, linked from each Test Run
via hasOutput and hasEvidence. Share artifact path/listing helpers
with the Test Run API and document the new graph nodes and relationships.

Signed-off-by: Luigi Pellecchia <pellecchia.luigi@gmail.com>

Author: pellecchialuigi

api/api.py

@@ -83,13 +83,15 @@
     get_html_email_body_from_template,
     get_mapping_comments,
     get_safe_str,
+    get_test_run_artifacts_dir,
     get_user_config_folder_path,
     get_user_html_folder_path,
     get_user_pdf_folder_path,
     get_user_traceability_scanner_config,
     is_safe_local_user_file_path,
     is_safe_user_path,
     is_testing_enabled_by_env,
+    list_test_run_artifacts,
     load_settings,
     parse_int,
     read_file,
@@ -10924,13 +10926,8 @@ def get(
         else:
             log_exec = "File not found."
 
-        # List files in the TMT_PLAN_DATA dir
-        artifacts = []
-        if os.path.exists(os.path.join(TEST_RUNS_BASE_DIR, run.uid, "api", "tmt-plan", "data")):
-            artifacts = os.listdir(os.path.join(TEST_RUNS_BASE_DIR, run.uid, "api", "tmt-plan", "data"))
-
         ret = run.as_dict()
-        ret["artifacts"] = artifacts
+        ret["artifacts"] = list_test_run_artifacts(run.uid)
         ret["log_exec"] = log_exec
         api_response.set_data(ret)
         return api_response.return_ok()
@@ -10974,9 +10971,8 @@ def get(
             api_response.set_message(f"Unable to find the test run id {request_data['id']}")
             return api_response.return_not_found()
 
-        # List files in the TMT_PLAN_DATA dir
-        artifacts_path = os.path.join(TEST_RUNS_BASE_DIR, run.uid, "api", "tmt-plan", "data")
-        artifacts = os.listdir(artifacts_path)
+        artifacts_path = get_test_run_artifacts_dir(run.uid)
+        artifacts = list_test_run_artifacts(run.uid)
         if request_data["artifact"] not in artifacts:
             api_response.set_message(f"Unable to find the artifact {request_data['artifact']}")
             return api_response.return_not_found()
@@ -11022,8 +11018,8 @@ def get(
             api_response.set_message(f"Unable to find the test run id {request_data['id']}")
             return api_response.return_not_found()
 
-        artifacts_path = os.path.join(TEST_RUNS_BASE_DIR, run.uid, "api", "tmt-plan", "data")
-        artifacts = os.listdir(artifacts_path)
+        artifacts_path = get_test_run_artifacts_dir(run.uid)
+        artifacts = list_test_run_artifacts(run.uid)
         if request_data["artifact"] not in artifacts:
             api_response.set_message(f"Unable to find the artifact {request_data['artifact']}")
             return api_response.return_not_found()

api/api_utils.py

@@ -857,3 +857,31 @@ def parse_comma_separated_list(value=None):
 def is_http_url(value: str) -> bool:
     """Return True if value looks like an http(s) URL."""
     return bool(value) and value.lower().startswith(("http://", "https://"))
+
+
+def get_test_run_artifacts_dir(test_run_uid: str) -> str:
+    """Return the on-disk directory where BASIL stores Test Run artifacts."""
+    # Same default as TEST_RUNS_BASE_DIR in api.py / testrun_tmt.py
+    test_runs_base_dir = os.getenv("TEST_RUNS_BASE_DIR", "/var/test-runs")
+    return os.path.join(test_runs_base_dir, test_run_uid, "api", "tmt-plan", "data")
+
+
+def list_test_run_artifacts(test_run_uid: str) -> list:
+    """List artifact file names for a Test Run (sorted, files only).
+
+    Returns an empty list when the artifacts directory is missing or
+    unreadable. Directories inside the artifacts path are ignored.
+    """
+    artifacts_dir = get_test_run_artifacts_dir(test_run_uid)
+    if not os.path.isdir(artifacts_dir):
+        return []
+    try:
+        names = [
+            name
+            for name in os.listdir(artifacts_dir)
+            if os.path.isfile(os.path.join(artifacts_dir, name))
+        ]
+    except OSError as e:
+        logger.warning(f"Unable to list artifacts for test run {test_run_uid}: {e}")
+        return []
+    return sorted(names)

api/spdx_manager.py

@@ -14,7 +14,12 @@
 currentdir = os.path.dirname(os.path.realpath(__file__))
 sys.path.insert(1, os.path.dirname(currentdir))
 
-from api.api_utils import is_http_url, parse_comma_separated_list  # noqa E402
+from api.api_utils import (  # noqa E402
+    get_test_run_artifacts_dir,
+    is_http_url,
+    list_test_run_artifacts,
+    parse_comma_separated_list,
+)
 from db.db_orm import DbInterface  # noqa E402
 from db.models.api import ApiModel  # noqa E402
 from db.models.api_document import ApiDocumentModel  # noqa E402
@@ -76,6 +81,9 @@ class SPDXExternalIdentifier:
     ``identifier`` and, when the value is an http(s) URL, also set
     ``identifierLocator``.
 
+    Test Run artifacts use:
+        basil:test_runs:<id>:artifact:<filename>
+
     Example:
         identifier = "basil:sw_requirements:42"
         comment    = "BASIL Software Requirement 'My Title' with ID 42"
@@ -1135,6 +1143,7 @@ def addJustification(self, justification: JustificationModel = None, dbsession=N
     def addTestRuns(self, spdx_tc: SPDXFile = None, mapping_to: str = "", mapping_id: int = 0, dbsession=None):
         if not self.include_test_runs:
             logger.warning("Skip Test Runs as per export configuration")
+            return
 
         added_test_runs = []
         test_runs_query = (
@@ -1199,6 +1208,7 @@ def addTestRun(self, test_run: TestRunModel = None, dbsession=None):
         self.add_to_sbom(tr_file)
         self.add_to_sbom(tr_annotation)
         self.addTestRunBugAndFixOutputs(spdx_tr=tr_file, test_run=test_run, creation_info=creation_info)
+        self.addTestRunArtifacts(spdx_tr=tr_file, test_run=test_run, creation_info=creation_info)
         return tr_file
 
     def addTestRunBugOrFix(
@@ -1275,6 +1285,101 @@ def addTestRunBugAndFixOutputs(
                     relationship_type=SpdxRelationshipType.HAS_OUTPUT,
                 )
 
+    def addTestRunArtifact(
+        self,
+        test_run: TestRunModel = None,
+        artifact_name: str = "",
+        index: int = 1,
+        creation_info: SPDXCreationInfo = None,
+    ):
+        """Create an SPDX File for one Test Run artifact on disk.
+
+        Artifacts live under ``TEST_RUNS_BASE_DIR/<uid>/api/tmt-plan/data/``.
+        ``verifiedUsing`` prefers an MD5 of the file contents when readable;
+        otherwise a metadata hash is used.
+        """
+        artifacts_dir = get_test_run_artifacts_dir(test_run.uid)
+        artifact_path = os.path.join(artifacts_dir, artifact_name)
+        spdx_id = f"spdx:file:basil:test-run:{test_run.id}:artifact:{index}"
+
+        content_hash = None
+        if os.path.isfile(artifact_path):
+            try:
+                dhash = hashlib.md5()
+                with open(artifact_path, "rb") as artifact_file:
+                    for chunk in iter(lambda: artifact_file.read(1024 * 1024), b""):
+                        dhash.update(chunk)
+                content_hash = SPDXMD5Hash(hash_value=dhash.hexdigest())
+            except OSError as e:
+                logger.warning(f"Unable to hash artifact {artifact_path}: {e}")
+
+        if content_hash is None:
+            content_hash = self.make_hash_object(
+                data_dict={
+                    "artifact_name": artifact_name,
+                    "test_run_id": test_run.id,
+                    "index": index,
+                }
+            )
+
+        artifact_file = SPDXFile(
+            spdx_id=spdx_id,
+            name=artifact_name,
+            comment="BASIL Artifact",
+            description=f"Artifact '{artifact_name}' from BASIL Test Run {test_run.id}",
+            purpose="evidence",
+            copyright_text="",
+            verified_using=[content_hash],
+            external_identifiers=[
+                SPDXExternalIdentifier(
+                    identifier=f"basil:{test_run.__tablename__}:{test_run.id}:artifact:{artifact_name}",
+                    comment=f"BASIL Test Run {test_run.id} Artifact '{artifact_name}'",
+                )
+            ],
+            creation_info=creation_info,
+        )
+        self.add_to_sbom(artifact_file)
+        return artifact_file
+
+    def addTestRunArtifacts(
+        self,
+        spdx_tr: SPDXFile = None,
+        test_run: TestRunModel = None,
+        creation_info: SPDXCreationInfo = None,
+    ):
+        """Emit SPDX Files for Test Run artifacts and link them 1-to-many.
+
+        Each on-disk artifact becomes an SPDX File (purpose ``evidence``).
+        The Test Run is linked to all artifacts with both ``hasOutput`` and
+        ``hasEvidence`` relationships (one relationship of each type covering
+        the full artifact list).
+        """
+        artifact_names = list_test_run_artifacts(test_run.uid)
+        if not artifact_names:
+            return
+
+        added_artifacts = []
+        for index, artifact_name in enumerate(artifact_names, start=1):
+            added_artifacts.append(
+                self.addTestRunArtifact(
+                    test_run=test_run,
+                    artifact_name=artifact_name,
+                    index=index,
+                    creation_info=creation_info,
+                )
+            )
+
+        self.addRelationship(
+            from_element=spdx_tr,
+            to=added_artifacts,
+            relationship_type=SpdxRelationshipType.HAS_OUTPUT,
+        )
+        self.addRelationship(
+            from_element=spdx_tr,
+            to=added_artifacts,
+            relationship_type=SpdxRelationshipType.HAS_EVIDENCE,
+        )
+
     def addDocumentsNestedElements(
         self,
         api: ApiModel = None,
@@ -1629,6 +1734,7 @@ def get_file_node_color(node):
                 "test run": "purple",
                 "bug": "salmon",
                 "fix": "olivedrab",
+                "artifact": "khaki",
             }
 
             if hasattr(node, "comment"):
@@ -1744,6 +1850,7 @@ def add_edge(src, dst, label):
         legend.node("test_run", label="Test Run", shape="box", style="filled", fillcolor="purple")
         legend.node("bug", label="Bug", shape="box", style="filled", fillcolor="salmon")
         legend.node("fix", label="Fix", shape="box", style="filled", fillcolor="olivedrab")
+        legend.node("artifact", label="Artifact", shape="box", style="filled", fillcolor="khaki")
 
         # Stack legend nodes vertically
         legend.edge("library", "software_component", style="invis", weight="100")
@@ -1757,6 +1864,7 @@ def add_edge(src, dst, label):
         legend.edge("test_case", "test_run", style="invis", weight="100")
         legend.edge("test_run", "bug", style="invis", weight="100")
         legend.edge("bug", "fix", style="invis", weight="100")
+        legend.edge("fix", "artifact", style="invis", weight="100")
 
         dot.subgraph(legend)
 

docs/source/traceability_export.rst

@@ -78,8 +78,8 @@ BASIL exports the following types of traceability relationships:
 - **hasSpecification**: e.g.:API Reference document Snippet <- Test Specifications or Sw Requirement <- Test Specification
 - **hasTest**: e.g.: Test Specification <- Test Cases or Sw Requirement <- Test Case ...
 - **generates**: e.g.: Test Cases <- Test Runs
-- **hasOutput**: e.g.: Test Run <- Bug or Fix (tracker URL / reference)
-- **hasEvidence**: e.g.: API Reference document Snippet <- Justification
+- **hasOutput**: e.g.: Test Run <- Bug or Fix (tracker URL / reference); Test Run <- Artifacts
+- **hasEvidence**: e.g.: API Reference document Snippet <- Justification; Test Run <- Artifacts
 - **contains**: e.g.: Library <- API
 
 Each relationship includes:
@@ -104,7 +104,7 @@ Graph Structure
 ~~~~~~~~~~~~~~~
 
 The generated graph shows:
-- Work items as nodes (requirements, specifications, test cases, test runs, bugs, fixes)
+- Work items as nodes (requirements, specifications, test cases, test runs, bugs, fixes, artifacts)
 - Relationships as directed edges
 - Color coding for different work item types
 - Hierarchical layout from requirements to test runs
@@ -127,6 +127,15 @@ Test Run Integration
   ``identifierLocator``)
 - Each Test Run is linked to each Bug/Fix with a dedicated 1-to-1
   ``hasOutput`` relationship
+- Artifacts stored under the Test Run artifacts directory
+  (``TEST_RUNS_BASE_DIR/<uid>/api/tmt-plan/data/``) are each exported as an
+  SPDX File with ``purpose="evidence"``
+- Each artifact File carries an ``ExternalIdentifier`` of the form
+  ``basil:test_runs:<id>:artifact:<filename>`` and a content MD5 when the
+  file is readable
+- Each Test Run is linked to its artifacts with 1-to-many ``hasOutput`` and
+  ``hasEvidence`` relationships (both relationship types target the same
+  artifact list)
 
 Test Run Limitations
 ~~~~~~~~~~~~~~~~~~~~