testmap 0.2.0__tar.gz

testmap-0.2.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.3
+Name: testmap
+Version: 0.2.0
+Summary: Understand your test suite: a feature x test-kind validation matrix.
+Author: Tyler Riccio
+Author-email: Tyler Riccio <tylerriccio8@gmail.com>
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# testmap
+
+Standalone core + CLI for testmap. Ingests test metadata (emitted by
+`pytest-testmap`) and renders the feature x test-kind matrix and the report of
+required-but-missing test kinds.

testmap-0.2.0/README.md

@@ -0,0 +1,5 @@
+# testmap
+
+Standalone core + CLI for testmap. Ingests test metadata (emitted by
+`pytest-testmap`) and renders the feature x test-kind matrix and the report of
+required-but-missing test kinds.

testmap-0.2.0/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "testmap"
+version = "0.2.0"
+description = "Understand your test suite: a feature x test-kind validation matrix."
+readme = "README.md"
+authors = [{ name = "Tyler Riccio", email = "tylerriccio8@gmail.com" }]
+requires-python = ">=3.14"
+dependencies = []
+
+[project.scripts]
+testmap = "testmap.cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.18,<0.12.0"]
+build-backend = "uv_build"

testmap-0.2.0/src/testmap/__init__.py

@@ -0,0 +1 @@
+"""testmap: a feature x test-kind validation matrix for your test suite."""

testmap-0.2.0/src/testmap/__main__.py

@@ -0,0 +1,6 @@
+"""Enable `python -m testmap` (and `uvx testmap`) to run the CLI."""
+
+from testmap.cli import main
+
+if __name__ == "__main__":
+    main()

testmap-0.2.0/src/testmap/cli.py

@@ -0,0 +1,53 @@
+"""`testmap report` — render the matrix, discovering tagged tests or ingesting JSON."""
+
+import argparse
+import json
+import tomllib
+from pathlib import Path
+
+from testmap.discover import discover
+from testmap.report import build_report, load_config, render
+
+
+def _default_paths(pyproject: Path) -> list[Path]:
+    """Testpaths from `[tool.pytest.ini_options]`, falling back to the cwd."""
+    if pyproject.is_file():
+        ini = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        testpaths = ini.get("tool", {}).get("pytest", {}).get("ini_options", {}).get("testpaths")
+        if testpaths:
+            return [Path(p) for p in testpaths]
+    return [Path(".")]
+
+
+def _load_records(path: Path | None, config_path: Path) -> list[dict[str, str]]:
+    """A JSON file is ingested as-is; a directory (or nothing) is scanned for @testmap."""
+    if path is not None and path.is_file() and path.suffix == ".json":
+        return json.loads(path.read_text(encoding="utf-8"))["tests"]
+    paths = [path] if path is not None else _default_paths(config_path)
+    return discover(paths)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="testmap")
+    sub = parser.add_subparsers(dest="command", required=True)
+    report = sub.add_parser("report", help="render a testmap report from source or a JSON file")
+    report.add_argument(
+        "path",
+        type=Path,
+        nargs="?",
+        help="a JSON file emitted by --testmap-json, or a dir to scan "
+        "(default: scan testpaths from pyproject.toml)",
+    )
+    report.add_argument("--json", action="store_true", help="emit machine-readable JSON")
+    report.add_argument(
+        "--config",
+        type=Path,
+        default=Path("pyproject.toml"),
+        help="pyproject.toml holding [tool.testmap] (default: ./pyproject.toml)",
+    )
+    args = parser.parse_args()
+
+    config = load_config(args.config)
+    tests = _load_records(args.path, args.config)
+    result = build_report(tests, config)
+    print(json.dumps(result, indent=2) if args.json else render(result, config))

testmap-0.2.0/src/testmap/discover.py

@@ -0,0 +1,73 @@
+"""Discover `@testmap`-tagged tests by scanning source, no pytest required.
+
+The pytest plugin collects the same `{feature, kind}` records at collection time.
+This module reads them statically instead: it parses each Python file and pulls
+the `feature`/`kind` arguments off every `@testmap(...)` (or
+`@pytest.mark.testmap(...)`) decorator, so `testmap report` can build the matrix
+straight from the codebase.
+"""
+
+import ast
+import os
+from collections.abc import Iterable
+from pathlib import Path
+
+
+def _string_arg(call: ast.Call, name: str) -> str | None:
+    for kw in call.keywords:
+        if kw.arg == name and isinstance(kw.value, ast.Constant):
+            value = kw.value.value
+            if isinstance(value, str):
+                return value
+    return None
+
+
+def _is_testmap_decorator(node: ast.expr) -> ast.Call | None:
+    """Return the decorator Call if it targets a `testmap` marker, else None."""
+    if not isinstance(node, ast.Call):
+        return None
+    func = node.func
+    # `@testmap(...)` (bare import) or `@pytest.mark.testmap(...)` / `@x.testmap(...)`.
+    if isinstance(func, ast.Name) and func.id == "testmap":
+        return node
+    if isinstance(func, ast.Attribute) and func.attr == "testmap":
+        return node
+    return None
+
+
+def _records_from_file(path: Path, root: Path) -> list[dict[str, str]]:
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except SyntaxError, UnicodeDecodeError:
+        return []  # not parseable Python; nothing to collect
+
+    records: list[dict[str, str]] = []
+    rel = os.path.relpath(path, root)
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.FunctionDef | ast.AsyncFunctionDef):
+            continue
+        for decorator in node.decorator_list:
+            call = _is_testmap_decorator(decorator)
+            if call is None:
+                continue
+            feature = _string_arg(call, "feature")
+            kind = _string_arg(call, "kind")
+            if feature is None or kind is None:
+                raise ValueError(f"{rel}::{node.name}: @testmap requires string feature and kind")
+            records.append({"nodeid": f"{rel}::{node.name}", "feature": feature, "kind": kind})
+    return records
+
+
+def discover(paths: Iterable[Path], root: Path | None = None) -> list[dict[str, str]]:
+    """Scan `paths` (files or directories) for `@testmap`-tagged tests.
+
+    `root` anchors the reported nodeids (defaults to the current directory).
+    Records are sorted by nodeid so the output is stable across runs.
+    """
+    root = (root or Path.cwd()).resolve()
+    records: list[dict[str, str]] = []
+    for path in paths:
+        files = sorted(path.rglob("*.py")) if path.is_dir() else [path]
+        for file in files:
+            records.extend(_records_from_file(file, root))
+    return sorted(records, key=lambda r: r["nodeid"])

testmap-0.2.0/src/testmap/report.py

@@ -0,0 +1,142 @@
+"""Core of testmap: load config, aggregate test records, render the report.
+
+The same renderer is used by the standalone CLI and by the pytest plugin, so the
+terminal output is identical no matter how the metadata was produced.
+"""
+
+import tomllib
+from dataclasses import dataclass
+from pathlib import Path
+
+# The Status column symbols, used when [tool.testmap.statuses] is absent. At
+# least one of each state so the table renders without any config.
+DEFAULT_STATUSES = {"complete": "✓", "incomplete": "✗"}
+
+
+@dataclass(frozen=True)
+class Config:
+    """The kind taxonomy and which kinds each feature must have."""
+
+    kinds: list[str]
+    required: list[str]  # global default required kinds
+    features: dict[str, list[str]]  # per-feature required-kind overrides
+    excludes: dict[str, list[str]]  # per-feature kinds dropped from requirements
+    statuses: dict[str, str]  # Status-column symbol per state (complete/incomplete)
+
+    def excluded_for(self, feature: str) -> list[str]:
+        return self.excludes.get(feature, [])
+
+    def required_for(self, feature: str) -> list[str]:
+        # Start from the feature's override (or the global default), then drop
+        # any kinds this feature opts out of, e.g. a feature that needs no perf.
+        base = self.features.get(feature, self.required)
+        excluded = self.excludes.get(feature, ())
+        return [k for k in base if k not in excluded]
+
+    def status_symbol(self, complete: bool) -> str:
+        return self.statuses["complete" if complete else "incomplete"]
+
+
+def load_config(pyproject: Path) -> Config:
+    """Load `[tool.testmap]` from a pyproject.toml.
+
+    A `[tool.testmap.features]` entry is either a list (the required kinds for
+    that feature) or a table taking `required` and/or `exclude`; excluded kinds
+    are dropped from that feature's requirements.
+
+    Invariant: every referenced kind (global, per-feature, excluded) is one of
+    `kinds`; a stray kind is a config bug, so we raise rather than silently drop it.
+    """
+    tool = tomllib.loads(pyproject.read_text(encoding="utf-8")).get("tool", {})
+    if "testmap" not in tool:
+        raise ValueError(f"no [tool.testmap] configuration in {pyproject}")
+    data = tool["testmap"]
+    kinds: list[str] = data["kinds"]
+    required: list[str] = data.get("required", kinds)
+
+    features: dict[str, list[str]] = {}
+    excludes: dict[str, list[str]] = {}
+    for name, entry in data.get("features", {}).items():
+        if isinstance(entry, dict):
+            if "required" in entry:
+                features[name] = entry["required"]
+            if entry.get("exclude"):
+                excludes[name] = entry["exclude"]
+        else:
+            features[name] = entry
+
+    referenced = {"required": required, **features, **excludes}
+    for name, kind_list in referenced.items():
+        unknown = sorted(set(kind_list) - set(kinds))
+        if unknown:
+            raise ValueError(f"[tool.testmap] {name} references unknown kinds {unknown}")
+    # Merge configured status symbols over the defaults so a partial table (e.g.
+    # only overriding "complete") keeps a symbol for the other state.
+    statuses = {**DEFAULT_STATUSES, **data.get("statuses", {})}
+    unknown_states = sorted(set(statuses) - set(DEFAULT_STATUSES))
+    if unknown_states:
+        raise ValueError(
+            f"[tool.testmap.statuses] unknown states {unknown_states} "
+            f"(valid: {sorted(DEFAULT_STATUSES)})"
+        )
+    return Config(
+        kinds=kinds, required=required, features=features, excludes=excludes, statuses=statuses
+    )
+
+
+def build_report(tests: list[dict[str, str]], config: Config) -> dict:
+    """Aggregate `{feature, kind}` records into the feature x kind matrix.
+
+    Raises on a kind not declared in `config.kinds` (no silent fallback). Only
+    features with at least one test appear; a feature is complete when none of
+    its required kinds are missing.
+    """
+    matrix: dict[str, dict[str, int]] = {}
+    for test in tests:
+        feature, kind = test["feature"], test["kind"]
+        if kind not in config.kinds:
+            raise ValueError(f"unknown test kind {kind!r} (declared kinds: {config.kinds})")
+        matrix.setdefault(feature, {k: 0 for k in config.kinds})[kind] += 1
+
+    features = {}
+    for feature in sorted(matrix):
+        counts = matrix[feature]
+        missing = [k for k in config.required_for(feature) if counts[k] == 0]
+        excluded = [k for k in config.kinds if k in config.excluded_for(feature)]
+        features[feature] = {
+            "counts": counts,
+            "missing": missing,
+            "excluded": excluded,
+            "complete": not missing,
+        }
+    return {"features": features}
+
+
+def render(report: dict, config: Config) -> str:
+    """Render the report as the feature x kind table plus the Missing section."""
+    headers = ["Feature", *(k.capitalize() for k in config.kinds), "Status"]
+    rows = [headers]
+    for feature, data in report["features"].items():
+        status = config.status_symbol(data["complete"])
+        # Excluded kinds render as n/a so a blank isn't mistaken for a gap.
+        cells = ["n/a" if k in data["excluded"] else str(data["counts"][k]) for k in config.kinds]
+        rows.append([feature, *cells, status])
+
+    widths = [max(len(row[i]) for row in rows) for i in range(len(headers))]
+
+    def fmt(cells: list[str]) -> str:
+        # Feature left-justified; counts and status right-justified for a clean grid.
+        return "  ".join(
+            [cells[0].ljust(widths[0])] + [c.rjust(widths[i]) for i, c in enumerate(cells[1:], 1)]
+        )
+
+    lines = [fmt(headers), "-" * len(fmt(headers)), *(fmt(row) for row in rows[1:])]
+
+    missing = [
+        f"  • {feature}: {kind}"
+        for feature, data in report["features"].items()
+        for kind in data["missing"]
+    ]
+    if missing:
+        lines += ["", "Missing:", *missing]
+    return "\n".join(lines)