updated unit tests to better communicate outcome

Author: ecrum19

.github/workflows/tests.yml

@@ -15,7 +15,6 @@ jobs:
       matrix:
         os:
           - ubuntu-latest
-          - macos-latest
     steps:
       - name: Checkout
         uses: actions/checkout@v4

README.md

@@ -82,6 +82,8 @@ Test suite notes:
 - Tests live in `test/`.
 - External tools are mocked (Docker, Java/RMLStreamer, gzip, brotli, rdf2hdt).
 - GitHub Actions runs this suite on each push and pull request (`.github/workflows/tests.yml`).
+- A successful run prints `[PASS]` markers for each test and ends with `OK`.
+- See `test/README.md` for an example of successful output.
 
 
 ## Manual Setup (Legacy)

test/README.md

@@ -29,3 +29,31 @@ This repository uses `unittest` (Python standard library) to isolate orchestrati
 - It tests the highest-risk logic in this codebase: orchestration, branching, path wiring, and metrics consistency.
 - It catches regressions in command construction without requiring heavyweight dependencies.
 - It validates that metrics remain comparable across runs by enforcing one shared CSV schema.
+
+## What a successful run looks like
+
+Run:
+
+```bash
+python -m unittest discover -s test -p "test_*_unit.py" -v
+```
+
+Success indicators:
+
+- Each test prints a clear marker:
+  - `[TEST] <description>`
+  - `[PASS] <description>`
+- `unittest` prints `ok` next to each test.
+- Final summary ends with:
+  - `Ran <N> tests ...`
+  - `OK`
+
+Example (truncated):
+
+```text
+[TEST] Wrapper runs all pipeline steps and forwards compression arguments.
+[PASS] Wrapper runs all pipeline steps and forwards compression arguments.
+...
+Ran 10 tests in 0.90s
+OK
+```

test/helpers.py

@@ -1,5 +1,6 @@
 import csv
 import os
+import unittest
 from pathlib import Path
 
 
@@ -82,3 +83,34 @@ def env_with_path(bin_dir: Path) -> dict[str, str]:
     env = os.environ.copy()
     env["PATH"] = f"{bin_dir}:{env['PATH']}"
     return env
+
+
+class VerboseTestCase(unittest.TestCase):
+    """Print explicit test start/end markers to make outcomes easy to scan."""
+
+    def run(self, result=None):
+        label = self.shortDescription() or self.id().split(".")[-1]
+        print(f"\n[TEST] {label}")
+
+        if result is None:
+            result = self.defaultTestResult()
+
+        failures_before = len(result.failures)
+        errors_before = len(result.errors)
+        skips_before = len(result.skipped)
+        unexpected_before = len(result.unexpectedSuccesses)
+
+        super().run(result)
+
+        failed = (len(result.failures) > failures_before) or (len(result.errors) > errors_before)
+        failed = failed or (len(result.unexpectedSuccesses) > unexpected_before)
+        skipped = len(result.skipped) > skips_before
+
+        if skipped:
+            print(f"[SKIP] {label}")
+        elif failed:
+            print(f"[FAIL] {label}")
+        else:
+            print(f"[PASS] {label}")
+
+        return result

test/test_compression_unit.py

@@ -4,7 +4,7 @@
 import unittest
 from pathlib import Path
 
-from test.helpers import env_with_path, make_executable, seed_conversion_metrics_row
+from test.helpers import VerboseTestCase, env_with_path, make_executable, seed_conversion_metrics_row
 
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
@@ -48,8 +48,9 @@ def read_metrics_row(metrics_csv: Path, run_id: str, output_name: str):
     raise AssertionError(f"Metrics row not found for run_id={run_id}, output_name={output_name}")
 
 
-class CompressionUnitTests(unittest.TestCase):
+class CompressionUnitTests(VerboseTestCase):
     def test_compression_updates_existing_metrics_row_with_mocked_tools(self):
+        """Compression mode gzip|brotli|hdt updates existing metrics row and writes artifacts."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             out_root = tmp_path / "out"
@@ -103,6 +104,7 @@ def test_compression_updates_existing_metrics_row_with_mocked_tools(self):
             self.assertGreater(int(row["combined_nq_size_bytes"]), 0)
 
     def test_compression_none_updates_metrics_without_generating_outputs(self):
+        """Compression mode none leaves no compressed artifacts and records zero sizes."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             out_root = tmp_path / "out"

test/test_run_conversion_unit.py

@@ -4,15 +4,16 @@
 import unittest
 from pathlib import Path
 
-from test.helpers import METRICS_HEADER, env_with_path, make_executable
+from test.helpers import METRICS_HEADER, VerboseTestCase, env_with_path, make_executable
 
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SCRIPT = REPO_ROOT / "src" / "run_conversion.sh"
 
 
-class RunConversionUnitTests(unittest.TestCase):
+class RunConversionUnitTests(VerboseTestCase):
     def test_run_conversion_writes_nq_and_metrics_without_real_java(self):
+        """Conversion script writes .nq output and unified metrics using mocked Java."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             fake_bin = tmp_path / "bin"

test/test_vcf_as_tsv_unit.py

@@ -4,13 +4,16 @@
 import unittest
 from pathlib import Path
 
+from test.helpers import VerboseTestCase
+
 
 REPO_ROOT = Path(__file__).resolve().parents[1]
 SCRIPT = REPO_ROOT / "src" / "vcf_as_tsv.sh"
 
 
-class VcfAsTsvUnitTests(unittest.TestCase):
+class VcfAsTsvUnitTests(VerboseTestCase):
     def test_vcf_as_tsv_directory_mode(self):
+        """Directory input: converts VCF and normalizes #CHROM header to CHROM."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             input_dir = tmp_path / "in"
@@ -34,6 +37,7 @@ def test_vcf_as_tsv_directory_mode(self):
             self.assertEqual(lines[1], "1\t10\trs1")
 
     def test_vcf_as_tsv_single_gz_file_mode(self):
+        """Single .vcf.gz input: decompresses and writes expected TSV output."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             input_file = tmp_path / "sample.vcf.gz"
@@ -53,6 +57,7 @@ def test_vcf_as_tsv_single_gz_file_mode(self):
             self.assertIn("CHROM\tPOS", out_file.read_text())
 
     def test_vcf_as_tsv_errors_when_no_vcf_files_found(self):
+        """Empty directory input: exits non-zero with a clear no-files message."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             input_dir = tmp_path / "empty"

test/test_vcf_rdfizer_unit.py

@@ -6,6 +6,7 @@
 from unittest import mock
 
 import vcf_rdfizer
+from test.helpers import VerboseTestCase
 
 
 def invoke_main(argv):
@@ -22,8 +23,9 @@ def prepare_inputs(base: Path):
     return input_dir, rules_path
 
 
-class WrapperUnitTests(unittest.TestCase):
+class WrapperUnitTests(VerboseTestCase):
     def test_main_happy_path_runs_pipeline_and_passes_compression(self):
+        """Wrapper runs all pipeline steps and forwards compression arguments."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             input_dir, rules_path = prepare_inputs(tmp_path)
@@ -67,6 +69,7 @@ def fake_run(cmd, cwd=None, env=None):
             self.assertEqual(commands[2][-2:], ["-m", "none"])
 
     def test_main_errors_when_versioned_image_does_not_exist(self):
+        """Wrapper returns a user error when a requested image version cannot be pulled."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             input_dir, rules_path = prepare_inputs(tmp_path)
@@ -99,6 +102,7 @@ def test_main_errors_when_versioned_image_does_not_exist(self):
             self.assertEqual(rc, 2)
 
     def test_main_no_build_fails_if_local_image_missing(self):
+        """Wrapper fails fast with --no-build when no local image is available."""
         with tempfile.TemporaryDirectory() as td:
             tmp_path = Path(td)
             input_dir, rules_path = prepare_inputs(tmp_path)
@@ -126,6 +130,7 @@ def test_main_no_build_fails_if_local_image_missing(self):
             self.assertEqual(rc, 2)
 
     def test_resolve_image_ref_accepts_repo_plus_version(self):
+        """Image repository and explicit version resolve to a tagged image reference."""
         ref, requested = vcf_rdfizer.resolve_image_ref("vcf-rdfizer", "1.2.3")
         self.assertEqual(ref, "vcf-rdfizer:1.2.3")
         self.assertTrue(requested)