pytest-verifies 1.1.0__py3-none-any.whl

pytest_verifies/__init__.py

@@ -0,0 +1,13 @@
+"""pytest-verifies: Enterprise requirements traceability plugin for pytest.
+
+Enables automated linking between test executions and formal engineering
+requirements, producing comprehensive Requirements Traceability Matrix (RTM) artefacts.
+"""
+
+from __future__ import annotations
+
+from pytest_verifies.context import step, verifies
+
+__version__ = "1.1.0"
+
+__all__ = ["step", "verifies", "__version__"]

pytest_verifies/baseline.py

@@ -0,0 +1,156 @@
+"""Loader and validator for baseline requirement manifests.
+
+Supports loading requirement manifests from JSON, CSV, and YAML formats with
+comprehensive schema validation and consistent British English error reporting.
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any
+
+from pytest_verifies.models import BaselineRequirement
+
+
+def load_baseline(path: str | Path) -> dict[str, BaselineRequirement]:
+    """Load and validate a baseline requirement manifest from disk.
+
+    Args:
+        path: Path to the requirement manifest file (.json, .csv, .yaml, or .yml).
+
+    Returns:
+        dict[str, BaselineRequirement]: Mapping of requirement ID to requirement details.
+
+    Raises:
+        FileNotFoundError: If the manifest file does not exist.
+        ValueError: If the file format is unsupported or the schema is invalid.
+        RuntimeError: If PyYAML is required but not installed.
+    """
+    manifest_path = Path(path)
+    if not manifest_path.is_file():
+        raise FileNotFoundError(f"Baseline requirements manifest not found: '{manifest_path}'")
+
+    suffix = manifest_path.suffix.lower()
+    if suffix == ".json":
+        return _load_json_baseline(manifest_path)
+    elif suffix == ".csv":
+        return _load_csv_baseline(manifest_path)
+    elif suffix in (".yaml", ".yml"):
+        return _load_yaml_baseline(manifest_path)
+    else:
+        raise ValueError(
+            f"Unsupported baseline file format '{suffix}'. "
+            "Supported formats are .json, .csv, and .yaml / .yml."
+        )
+
+
+def _load_json_baseline(path: Path) -> dict[str, BaselineRequirement]:
+    """Load baseline requirements from a JSON file."""
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Malformed JSON in baseline manifest '{path}': {exc}") from exc
+
+    return _parse_baseline_data(data, path)
+
+
+def _load_csv_baseline(path: Path) -> dict[str, BaselineRequirement]:
+    """Load baseline requirements from a CSV file."""
+    requirements: dict[str, BaselineRequirement] = {}
+    with path.open("r", encoding="utf-8-sig", newline="") as f:
+        reader = csv.DictReader(f)
+        if not reader.fieldnames or "id" not in [
+            name.strip().lower() for name in reader.fieldnames
+        ]:
+            raise ValueError(f"CSV baseline manifest '{path}' must contain an 'id' header column.")
+
+        for line_no, row in enumerate(reader, start=2):
+            if not any((v or "").strip() for k, v in row.items() if k and isinstance(v, str)):
+                continue
+
+            # Normalise keys to lowercase
+            norm_row = {k.strip().lower(): (v.strip() if v else "") for k, v in row.items() if k}
+            req_id = norm_row.get("id", "").strip()
+            if not req_id:
+                raise ValueError(
+                    f"Line {line_no} in CSV baseline manifest '{path}' contains an empty requirement ID."
+                )
+
+            requirements[req_id] = BaselineRequirement.from_dict(norm_row)
+
+    return requirements
+
+
+def _load_yaml_baseline(path: Path) -> dict[str, BaselineRequirement]:
+    """Load baseline requirements from a YAML file."""
+    try:
+        import yaml  # type: ignore[import-untyped]
+    except ImportError as exc:
+        raise RuntimeError(
+            "PyYAML is required to parse YAML baseline files. Please install pyyaml."
+        ) from exc
+
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except Exception as exc:
+        raise ValueError(f"Malformed YAML in baseline manifest '{path}': {exc}") from exc
+
+    return _parse_baseline_data(data, path)
+
+
+def _parse_baseline_data(data: Any, path: Path) -> dict[str, BaselineRequirement]:
+    """Parse dictionary or list data structures into a validated requirement mapping."""
+    requirements: dict[str, BaselineRequirement] = {}
+
+    if isinstance(data, dict):
+        if "requirements" in data and isinstance(data["requirements"], list):
+            items = data["requirements"]
+            for idx, item in enumerate(items):
+                if (
+                    not isinstance(item, dict)
+                    or item.get("id") is None
+                    or not str(item["id"]).strip()
+                ):
+                    raise ValueError(
+                        f"Item {idx} in 'requirements' list of '{path}' must be a dictionary with an 'id'."
+                    )
+                req = BaselineRequirement.from_dict(item)
+                requirements[req.id] = req
+        else:
+            # Format: {"REQ-1": {"title": "..."}, "REQ-2": {...}}
+            for key, val in data.items():
+                req_id = str(key).strip() if key is not None else ""
+                if not req_id:
+                    raise ValueError(
+                        f"Baseline manifest '{path}' contains an empty requirement ID."
+                    )
+                if isinstance(val, dict):
+                    item_dict = dict(val)
+                    if item_dict.get("id") is None or not str(item_dict["id"]).strip():
+                        item_dict["id"] = req_id
+                    req = BaselineRequirement.from_dict(item_dict)
+                elif val is None:
+                    req = BaselineRequirement(id=req_id, text="")
+                else:
+                    # Could be scalar description: {"REQ-1": "Requirement text"}
+                    req = BaselineRequirement(id=req_id, text=str(val).strip())
+                requirements[req.id] = req
+
+    elif isinstance(data, list):
+        for idx, item in enumerate(data):
+            if not isinstance(item, dict) or item.get("id") is None or not str(item["id"]).strip():
+                raise ValueError(
+                    f"Item {idx} in '{path}' must be a dictionary containing a non-empty 'id'."
+                )
+            req = BaselineRequirement.from_dict(item)
+            requirements[req.id] = req
+    else:
+        raise ValueError(
+            f"Unexpected data format in baseline manifest '{path}'. Expected dict or list."
+        )
+
+    return requirements

pytest_verifies/cli.py

@@ -0,0 +1,205 @@
+"""Command-line interface for pytest-verifies.
+
+Provides the standalone `pytest-verifies combine` command to merge execution shards,
+validate against baseline manifests, evaluate quality gates, and output reports.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from typing import Sequence
+
+from pytest_verifies.baseline import load_baseline
+from pytest_verifies.models import BaselineRequirement, RTMReport
+from pytest_verifies.reporters import (
+    generate_csv_report,
+    generate_html_report,
+    generate_json_report,
+    generate_markdown_report,
+    render_console_summary,
+)
+from pytest_verifies.storage import consolidate_requirements, read_shards
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Construct command-line argument parser with subcommands."""
+    parser = argparse.ArgumentParser(
+        prog="pytest-verifies",
+        description="Enterprise requirements traceability matrix tool for pytest.",
+    )
+    subparsers = parser.add_subparsers(dest="subcommand", help="Available subcommands")
+
+    # `combine` subcommand
+    combine_parser = subparsers.add_parser(
+        "combine",
+        help="Combine multiple execution shards and generate traceability reports.",
+    )
+    combine_parser.add_argument(
+        "shards",
+        nargs="+",
+        help="One or more shard file paths (.jsonl) or directories containing shards.",
+    )
+    combine_parser.add_argument(
+        "--baseline",
+        "-b",
+        type=str,
+        default=None,
+        help="Path to baseline requirements manifest (.json, .csv, .yaml).",
+    )
+    combine_parser.add_argument(
+        "--json",
+        type=str,
+        default=None,
+        help="Path to generate structured JSON report.",
+    )
+    combine_parser.add_argument(
+        "--csv",
+        type=str,
+        default=None,
+        help="Path to generate tabular CSV report.",
+    )
+    combine_parser.add_argument(
+        "--md",
+        type=str,
+        default=None,
+        help="Path to generate Markdown summary report.",
+    )
+    combine_parser.add_argument(
+        "--html",
+        type=str,
+        default=None,
+        help="Path to generate interactive HTML5 report.",
+    )
+    combine_parser.add_argument(
+        "--disallow-orphans",
+        action="store_true",
+        default=False,
+        help="Fail quality gate if observed requirements are not in the baseline.",
+    )
+    combine_parser.add_argument(
+        "--fail-under",
+        type=float,
+        default=None,
+        help="Minimum required verified requirement coverage percentage (0.0 to 100.0).",
+    )
+    combine_parser.add_argument(
+        "--color",
+        choices=["yes", "no", "auto"],
+        default="auto",
+        help="Control colour formatting in terminal output (default: auto).",
+    )
+
+    return parser
+
+
+def combine_command(args: argparse.Namespace) -> int:
+    """Execute the combine subcommand to merge shards and verify quality gates.
+
+    Returns:
+        int: Exit status code (0 for success, 1 for quality gate failure).
+    """
+    if args.disallow_orphans and not args.baseline:
+        print(
+            "Error: --disallow-orphans requires --baseline to be specified.",
+            file=sys.stderr,
+        )
+        return 1
+
+    baseline_map: dict[str, BaselineRequirement] | None = None
+    if args.baseline:
+        try:
+            baseline_map = load_baseline(args.baseline)
+        except Exception as exc:
+            print(f"Error loading baseline manifest '{args.baseline}': {exc}", file=sys.stderr)
+            return 1
+
+    runs, records = read_shards(args.shards)
+    if not records and not runs:
+        print(
+            f"Warning: No valid verification records found in specified paths: {args.shards}",
+            file=sys.stderr,
+        )
+
+    report: RTMReport = consolidate_requirements(records, baseline=baseline_map, runs=runs)
+
+    # Output requested reports
+    if args.json:
+        generate_json_report(report, args.json)
+        print(f"Generated JSON report: {args.json}")
+    if args.csv:
+        generate_csv_report(report, args.csv)
+        print(f"Generated CSV report: {args.csv}")
+    if args.md:
+        generate_markdown_report(report, args.md)
+        print(f"Generated Markdown report: {args.md}")
+    if args.html:
+        generate_html_report(report, args.html)
+        print(f"Generated HTML report: {args.html}")
+
+    # Display console summary using TerminalWriter
+    from _pytest._io.terminalwriter import TerminalWriter
+
+    tw = TerminalWriter(sys.stdout)
+    if getattr(args, "color", "auto") == "yes":
+        tw.hasmarkup = True
+    elif getattr(args, "color", "auto") == "no":
+        tw.hasmarkup = False
+
+    render_console_summary(report, tw)
+
+    # Quality Gate Checks
+    exit_code = 0
+
+    # 1. Any requirement with consolidated status FAILED
+    failed_reqs = [r.req_id for r in report.requirements if r.status == "FAILED"]
+    if failed_reqs:
+        print(
+            f"Quality gate failure: {len(failed_reqs)} requirement(s) failed: {', '.join(failed_reqs)}",
+            file=sys.stderr,
+        )
+        exit_code = 1
+
+    # 2. Disallow orphans check
+    if args.disallow_orphans and report.orphan_count > 0:
+        orphan_ids = [r.req_id for r in report.requirements if r.is_orphan]
+        print(
+            f"Quality gate failure: Found {len(orphan_ids)} orphaned requirement(s) not in baseline: {', '.join(orphan_ids)}",
+            file=sys.stderr,
+        )
+        exit_code = 1
+
+    # 3. Minimum coverage percentage threshold
+    if args.fail_under is not None:
+        if report.coverage_percentage < args.fail_under:
+            print(
+                f"Quality gate failure: Coverage {report.coverage_percentage:.1f}% is below threshold of {args.fail_under:.1f}%",
+                file=sys.stderr,
+            )
+            exit_code = 1
+
+    return exit_code
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Main CLI entry point."""
+    parser = build_parser()
+    args_list = list(argv if argv is not None else sys.argv[1:])
+
+    # Ergonomic fallback: if first argument is not a known subcommand and not help, default to combine
+    if args_list and args_list[0] not in ("combine", "-h", "--help"):
+        args_list.insert(0, "combine")
+    elif not args_list:
+        parser.print_help()
+        return 0
+
+    args = parser.parse_args(args_list)
+    if args.subcommand == "combine":
+        return combine_command(args)
+    else:
+        parser.print_help()
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())