tesserakit-tests 0.4.0__tar.gz

tesserakit_tests-0.4.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+out/
+.DS_Store

tesserakit_tests-0.4.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: tesserakit-tests
+Version: 0.4.0
+Summary: Tests job pack for Tessera: audit a Python test suite for hygiene (no-assert, skipped, xfail).
+Project-URL: Homepage, https://github.com/ShaileshRawat1403/tessera
+Project-URL: Repository, https://github.com/ShaileshRawat1403/tessera
+Project-URL: Issues, https://github.com/ShaileshRawat1403/tessera/issues
+Author: Shailesh Rawat
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: tesserakit-core>=0.1.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# tesserakit-tests
+
+Audit a Python test suite for hygiene problems.
+
+`tessera-tests` parses test files with `ast` (never imports or runs them), inventories the test functions and methods, and surfaces the tests that aren't really protecting anything: tests with no assertions, and tests that are skipped or expected to fail.
+
+## Audit
+
+```bash
+tessera tests audit --input . --output ./out/tests_pack
+```
+
+Test discovery follows pytest/unittest conventions: files named `test_*.py` / `*_test.py` or under a `tests/` directory; functions named `test*`; methods named `test*` inside `Test*` classes.
+
+Artifacts written:
+
+```text
+tests.jsonl              one TestCase per test (asserts, skip/xfail/param flags)
+index.md                 the test inventory
+validation_report.md     hygiene findings
+coverage_report.md       counts (skipped/xfail/parametrized/no-assert) + per-file
+not_running.md           skipped + xfail tests (present but not protecting anything)
+```
+
+## What it detects
+
+- **Assertions**: `assert` statements, `self.assert*` calls, and `pytest.raises`/`warns` blocks.
+- **Markers**: `@pytest.mark.skip` / `skipif`, `xfail`, `parametrize` (matched on the decorator name).
+
+## Findings
+
+- `no_assertion_test` (warning) — a test with zero assertions that isn't skipped/xfail
+- `skipped_test` (info) — a skipped test
+- `xfail_test` (info) — an expected-failure test
+- `parse_error`, `no_tests_found`

tesserakit_tests-0.4.0/README.md

@@ -0,0 +1,35 @@
+# tesserakit-tests
+
+Audit a Python test suite for hygiene problems.
+
+`tessera-tests` parses test files with `ast` (never imports or runs them), inventories the test functions and methods, and surfaces the tests that aren't really protecting anything: tests with no assertions, and tests that are skipped or expected to fail.
+
+## Audit
+
+```bash
+tessera tests audit --input . --output ./out/tests_pack
+```
+
+Test discovery follows pytest/unittest conventions: files named `test_*.py` / `*_test.py` or under a `tests/` directory; functions named `test*`; methods named `test*` inside `Test*` classes.
+
+Artifacts written:
+
+```text
+tests.jsonl              one TestCase per test (asserts, skip/xfail/param flags)
+index.md                 the test inventory
+validation_report.md     hygiene findings
+coverage_report.md       counts (skipped/xfail/parametrized/no-assert) + per-file
+not_running.md           skipped + xfail tests (present but not protecting anything)
+```
+
+## What it detects
+
+- **Assertions**: `assert` statements, `self.assert*` calls, and `pytest.raises`/`warns` blocks.
+- **Markers**: `@pytest.mark.skip` / `skipif`, `xfail`, `parametrize` (matched on the decorator name).
+
+## Findings
+
+- `no_assertion_test` (warning) — a test with zero assertions that isn't skipped/xfail
+- `skipped_test` (info) — a skipped test
+- `xfail_test` (info) — an expected-failure test
+- `parse_error`, `no_tests_found`

tesserakit_tests-0.4.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "tesserakit-tests"
+version = "0.4.0"
+description = "Tests job pack for Tessera: audit a Python test suite for hygiene (no-assert, skipped, xfail)."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Shailesh Rawat" }]
+dependencies = [
+  "tesserakit-core>=0.1.0",
+  "typer>=0.12",
+  "rich>=13.7",
+  "pydantic>=2.7",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://github.com/ShaileshRawat1403/tessera"
+Repository = "https://github.com/ShaileshRawat1403/tessera"
+Issues = "https://github.com/ShaileshRawat1403/tessera/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.entry-points."tessera.commands"]
+tests = "tessera_tests.cli:register"
+
+[project.entry-points."tessera.jobpacks"]
+tests = "tessera_tests.pack:create_pack"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tessera_tests"]

tesserakit_tests-0.4.0/src/tessera_tests/__init__.py

@@ -0,0 +1,3 @@
+"""Tessera tests pack."""
+
+__version__ = "0.3.1"

tesserakit_tests-0.4.0/src/tessera_tests/cli.py

@@ -0,0 +1,45 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from tessera_core.models import RunContext
+
+from tessera_tests.pack import TestsPack
+
+console = Console()
+tests_app = typer.Typer(help="Audit a Python test suite for hygiene (no-assert, skipped, xfail).")
+
+
+@tests_app.command("audit")
+def audit_cmd(
+    input: Path = typer.Option(Path("."), "--input", "-i", exists=True, readable=True, help="Project directory."),
+    output: Path = typer.Option(Path("tests_pack"), "--output", "-o", help="Output directory."),
+) -> None:
+    """Discover tests and report hygiene issues (no assertions, skipped, xfail)."""
+    ctx = RunContext(job_name="tests", output_dir=output)
+    pack = TestsPack()
+    artifacts = pack.run(input_path=input, ctx=ctx, options={})
+
+    table = Table(title="Tests Pack Created")
+    table.add_column("Artifact")
+    table.add_column("Path")
+    table.add_column("Kind")
+    for art in artifacts:
+        table.add_row(art.name, str(art.path), art.kind)
+    console.print(table)
+
+    summary = Table(title="Run Summary")
+    summary.add_column("Metric")
+    summary.add_column("Value")
+    summary.add_row("run_id", ctx.run_id)
+    summary.add_row("tests", str(ctx.metadata.get("record_count", 0)))
+    summary.add_row("findings", str(ctx.metadata.get("finding_count", 0)))
+    console.print(summary)
+
+
+def register(root_app: typer.Typer) -> None:
+    root_app.add_typer(tests_app, name="tests")

tesserakit_tests-0.4.0/src/tessera_tests/compiler.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from collections import Counter
+from pathlib import Path
+from typing import Any
+
+from tessera_core.artifacts import write_jsonl, write_markdown
+from tessera_core.models import Artifact, RunContext, ValidationFinding
+
+from tessera_tests.loader import load_test_records
+from tessera_tests.schema import TestCase
+from tessera_tests.validator import validate_test_records
+
+
+def load_records(input_path: Path, options: dict[str, Any]) -> list[TestCase]:
+    return load_test_records(input_path, options)
+
+
+def validate_records(cases: list[TestCase], options: dict[str, Any]) -> list[ValidationFinding]:
+    return validate_test_records(cases, options)
+
+
+def write_artifacts(cases: list[TestCase], ctx: RunContext, options: dict[str, Any]) -> list[Artifact]:
+    ctx.output_dir.mkdir(parents=True, exist_ok=True)
+    findings: list[ValidationFinding] = ctx.metadata.get("findings") or validate_records(cases, options)
+
+    tests_jsonl = ctx.output_dir / "tests.jsonl"
+    index_md = ctx.output_dir / "index.md"
+    validation_md = ctx.output_dir / "validation_report.md"
+    coverage_md = ctx.output_dir / "coverage_report.md"
+    not_running_md = ctx.output_dir / "not_running.md"
+
+    write_jsonl(tests_jsonl, [c.model_dump() for c in cases])
+    write_markdown(index_md, _render_index(cases, options))
+    write_markdown(validation_md, _render_validation(cases, findings))
+    write_markdown(coverage_md, _render_coverage(cases))
+    write_markdown(not_running_md, _render_not_running(cases))
+
+    return [
+        Artifact(name="tests.jsonl", path=tests_jsonl, kind="jsonl"),
+        Artifact(name="index.md", path=index_md, kind="markdown"),
+        Artifact(name="validation_report.md", path=validation_md, kind="markdown"),
+        Artifact(name="coverage_report.md", path=coverage_md, kind="markdown"),
+        Artifact(name="not_running.md", path=not_running_md, kind="markdown"),
+    ]
+
+
+def _render_index(cases: list[TestCase], options: dict[str, Any]) -> str:
+    lines = ["# Test Inventory", ""]
+    lines.append(f"- Test files: {options.get('_file_count', 0)}")
+    lines.append(f"- Tests: {len(cases)}")
+    no_assert = sum(1 for c in cases if not c.has_assert and not c.is_skipped and not c.is_xfail)
+    lines.append(f"- Tests with no assertions: {no_assert}")
+    lines.append("")
+    if not cases:
+        lines.append("_No tests found._")
+        return "\n".join(lines) + "\n"
+    lines.append("| Test | Asserts | Skipped | Xfail | Param | Location |")
+    lines.append("|---|---:|:--:|:--:|:--:|---|")
+    for c in cases:
+        lines.append(
+            f"| `{c.qualname}` | {c.assertion_count} "
+            f"| {'yes' if c.is_skipped else '-'} | {'yes' if c.is_xfail else '-'} "
+            f"| {'yes' if c.is_parametrized else '-'} | `{c.file}:{c.lineno}` |"
+        )
+    return "\n".join(lines) + "\n"
+
+
+def _render_validation(cases: list[TestCase], findings: list[ValidationFinding]) -> str:
+    lines = ["# Validation Report", ""]
+    lines.append(f"- Tests: {len(cases)}")
+    lines.append(f"- Findings: {len(findings)}")
+    lines.append("")
+    by_sev = Counter(f.severity for f in findings)
+    lines.append("## Severity Breakdown")
+    lines.append("")
+    for sev in ("error", "warning", "info"):
+        lines.append(f"- {sev}: {by_sev.get(sev, 0)}")
+    lines.append("")
+    if findings:
+        lines.append("## Findings")
+        lines.append("")
+        for f in findings[:300]:
+            lines.append(f"- **{f.severity.upper()}** `{f.code}`: {f.message}")
+    return "\n".join(lines)
+
+
+def _render_coverage(cases: list[TestCase]) -> str:
+    lines = ["# Coverage Report", ""]
+    lines.append(f"- Tests: {len(cases)}")
+    if not cases:
+        return "\n".join(lines) + "\n"
+    skipped = sum(1 for c in cases if c.is_skipped)
+    xfail = sum(1 for c in cases if c.is_xfail)
+    param = sum(1 for c in cases if c.is_parametrized)
+    no_assert = sum(1 for c in cases if not c.has_assert and not c.is_skipped and not c.is_xfail)
+    lines.append(f"- Skipped: {skipped}")
+    lines.append(f"- Xfail: {xfail}")
+    lines.append(f"- Parametrized: {param}")
+    lines.append(f"- No assertions: {no_assert}")
+    lines.append("")
+    by_file = Counter(c.file for c in cases)
+    lines.append("## Tests per file")
+    lines.append("")
+    for path, n in by_file.most_common():
+        lines.append(f"- `{path}`: {n}")
+    return "\n".join(lines) + "\n"
+
+
+def _render_not_running(cases: list[TestCase]) -> str:
+    inactive = [c for c in cases if c.is_skipped or c.is_xfail]
+    lines = ["# Tests Not Effectively Running", ""]
+    lines.append("Skipped and xfail tests — present but not protecting anything right now.")
+    lines.append("")
+    if not inactive:
+        lines.append("_All discovered tests are active._")
+        return "\n".join(lines) + "\n"
+    for c in inactive:
+        tag = "skip" if c.is_skipped else "xfail"
+        lines.append(f"- **{tag}** `{c.qualname}` ({c.file}:{c.lineno})")
+    return "\n".join(lines) + "\n"

tesserakit_tests-0.4.0/src/tessera_tests/loader.py

@@ -0,0 +1,23 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from tessera_tests.scan import discover_test_files, extract_tests
+from tessera_tests.schema import TestCase
+
+
+def load_test_records(input_path: Path, options: dict[str, Any]) -> list[TestCase]:
+    root = input_path if input_path.is_dir() else input_path.parent
+    cases: list[TestCase] = []
+    parse_errors: list[str] = []
+    files = discover_test_files(root)
+    for f in files:
+        found, err = extract_tests(root, f)
+        cases.extend(found)
+        if err:
+            parse_errors.append(err)
+    options["_parse_errors"] = parse_errors
+    options["_file_count"] = len(files)
+    options["_root"] = str(root)
+    return cases

tesserakit_tests-0.4.0/src/tessera_tests/pack.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from tessera_core.jobpack import JobPack
+from tessera_core.models import Artifact, RunContext, ValidationFinding
+
+from tessera_tests.compiler import load_records, validate_records, write_artifacts
+
+
+class TestsPack(JobPack):
+    name = "tests"
+    version = "0.3.1"
+
+    def normalize(self, input_path: Path, options: dict[str, Any]) -> list[Any]:
+        return load_records(input_path, options)
+
+    def validate(
+        self,
+        records: list[Any],
+        options: dict[str, Any],
+    ) -> list[ValidationFinding]:
+        return validate_records(records, options)
+
+    def generate(
+        self,
+        records: list[Any],
+        ctx: RunContext,
+        options: dict[str, Any],
+    ) -> list[Artifact]:
+        return write_artifacts(records, ctx, options)
+
+
+def create_pack() -> TestsPack:
+    return TestsPack()

tesserakit_tests-0.4.0/src/tessera_tests/scan.py

@@ -0,0 +1,97 @@
+"""Discover tests and their hygiene facts via ast (no imports, no execution)."""
+
+from __future__ import annotations
+
+import ast
+from pathlib import Path
+
+from tessera_tests.schema import TestCase
+
+_IGNORE = {
+    ".git", ".venv", "venv", "node_modules", "__pycache__", ".pytest_cache",
+    "dist", "build", ".tox", "target",
+}
+
+
+def is_test_file(rel: Path) -> bool:
+    n = rel.name
+    if not n.endswith(".py"):
+        return False
+    if n.startswith("test_") or n.endswith("_test.py"):
+        return True
+    parts = [p.lower() for p in rel.parts[:-1]]
+    return any(p in ("test", "tests") for p in parts) and n != "__init__.py"
+
+
+def discover_test_files(root: Path) -> list[Path]:
+    out: list[Path] = []
+    for p in sorted(root.rglob("*.py")):
+        rel = p.relative_to(root)
+        if any(part in _IGNORE for part in rel.parts):
+            continue
+        if is_test_file(rel):
+            out.append(p)
+    return out
+
+
+def _decorator_str(node: ast.expr) -> str:
+    if isinstance(node, ast.Call):
+        return _decorator_str(node.func)
+    if isinstance(node, ast.Attribute):
+        return f"{_decorator_str(node.value)}.{node.attr}"
+    if isinstance(node, ast.Name):
+        return node.id
+    return ""
+
+
+def _count_assertions(fn: ast.AST) -> int:
+    count = 0
+    for node in ast.walk(fn):
+        if isinstance(node, ast.Assert):
+            count += 1
+        elif isinstance(node, ast.Call):
+            target = node.func
+            if isinstance(target, ast.Attribute):
+                attr = target.attr.lower()
+                if attr.startswith("assert"):
+                    count += 1
+                elif attr in ("raises", "warns", "deprecated_call"):
+                    count += 1
+    return count
+
+
+def _make_case(fn: ast.AST, rel: str, kind: str, prefix: str) -> TestCase:
+    decorators = [d for d in (_decorator_str(x) for x in fn.decorator_list) if d]
+    lowered = " ".join(decorators).lower()
+    n = _count_assertions(fn)
+    return TestCase(
+        name=fn.name,
+        qualname=f"{prefix}{fn.name}",
+        kind=kind,
+        file=rel,
+        lineno=fn.lineno,
+        decorators=decorators,
+        is_skipped="skip" in lowered,
+        is_xfail="xfail" in lowered,
+        is_parametrized="parametrize" in lowered,
+        assertion_count=n,
+        has_assert=n > 0,
+    )
+
+
+def extract_tests(root: Path, path: Path) -> tuple[list[TestCase], str | None]:
+    rel = path.relative_to(root).as_posix()
+    try:
+        tree = ast.parse(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeDecodeError, SyntaxError) as exc:
+        return [], f"{rel}: {exc}"
+
+    cases: list[TestCase] = []
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) and node.name.startswith("test"):
+            cases.append(_make_case(node, rel, "function", ""))
+        elif isinstance(node, ast.ClassDef) and node.name.startswith("Test"):
+            for sub in node.body:
+                if isinstance(sub, (ast.FunctionDef, ast.AsyncFunctionDef)) and sub.name.startswith("test"):
+                    cases.append(_make_case(sub, rel, "method", f"{node.name}."))
+    return cases, None

tesserakit_tests-0.4.0/src/tessera_tests/schema.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class TestCase(BaseModel):
+    """A discovered test. Serialized to ``tests.jsonl``."""
+
+    # Tell pytest not to collect this domain model as a test class.
+    __test__ = False
+
+    name: str
+    qualname: str = ""
+    kind: str = "function"   # function / method
+    file: str = ""
+    lineno: int = 0
+    decorators: list[str] = Field(default_factory=list)
+    is_skipped: bool = False
+    is_xfail: bool = False
+    is_parametrized: bool = False
+    assertion_count: int = 0
+    has_assert: bool = False
+    metadata: dict[str, Any] = Field(default_factory=dict)

tesserakit_tests-0.4.0/src/tessera_tests/validator.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any
+
+from tessera_core.models import ValidationFinding
+
+from tessera_tests.schema import TestCase
+
+
+def validate_test_records(cases: list[TestCase], options: dict[str, Any]) -> list[ValidationFinding]:
+    findings: list[ValidationFinding] = []
+
+    for err in options.get("_parse_errors", []):
+        findings.append(ValidationFinding(severity="error", code="parse_error",
+                                          message=f"could not parse: {err}", field=None))
+
+    if not cases:
+        if not options.get("_parse_errors"):
+            findings.append(ValidationFinding(severity="info", code="no_tests_found",
+                                              message="no test functions discovered", field=None))
+        return findings
+
+    for c in cases:
+        loc = f"{c.file}:{c.lineno}"
+
+        def f(severity: str, code: str, message: str) -> ValidationFinding:
+            return ValidationFinding(severity=severity, code=code, message=message,
+                                     field="tests", metadata={"file": c.file, "lineno": c.lineno, "name": c.qualname})
+
+        if not c.has_assert and not c.is_skipped and not c.is_xfail:
+            findings.append(f("warning", "no_assertion_test",
+                              f"{loc}: test `{c.qualname}` has no assertions"))
+        if c.is_skipped:
+            findings.append(f("info", "skipped_test", f"{loc}: test `{c.qualname}` is skipped"))
+        if c.is_xfail:
+            findings.append(f("info", "xfail_test", f"{loc}: test `{c.qualname}` is expected to fail"))
+
+    return findings

tesserakit_tests-0.4.0/tests/test_tests_pack.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from tessera_core.models import RunContext
+
+from tessera_tests.pack import TestsPack
+from tessera_tests.scan import extract_tests, is_test_file
+from tessera_tests.schema import TestCase
+
+REPO_ROOT = Path(__file__).resolve().parents[3]
+SAMPLE = REPO_ROOT / "examples" / "tests"
+SAMPLE_FILE = SAMPLE / "sample" / "test_sample.py"
+
+
+# ---------- discovery / extraction ----------
+
+
+def test_is_test_file():
+    assert is_test_file(Path("tests/test_x.py"))
+    assert is_test_file(Path("foo_test.py"))
+    assert not is_test_file(Path("src/app.py"))
+
+
+def test_extract_flags():
+    cases, err = extract_tests(SAMPLE, SAMPLE_FILE)
+    assert err is None
+    by = {c.qualname: c for c in cases}
+
+    assert by["test_passes_with_assert"].has_assert
+    assert by["test_no_assertions"].has_assert is False
+    assert by["test_skipped"].is_skipped
+    assert by["test_expected_fail"].is_xfail
+    assert by["test_parametrized"].is_parametrized and by["test_parametrized"].has_assert
+    assert by["TestThing.test_method_with_assert"].kind == "method"
+    assert by["TestThing.test_method_with_assert"].has_assert  # self.assertEqual
+
+
+# ---------- end-to-end ----------
+
+
+def _run(tmp_path: Path):
+    out = tmp_path / "tests_pack"
+    ctx = RunContext(job_name="tests", output_dir=out)
+    TestsPack().run(input_path=SAMPLE, ctx=ctx, options={})
+    return out, ctx
+
+
+def test_findings(tmp_path: Path):
+    _, ctx = _run(tmp_path)
+    codes = {f.code for f in ctx.metadata["findings"]}
+    assert "no_assertion_test" in codes   # test_no_assertions
+    assert "skipped_test" in codes
+    assert "xfail_test" in codes
+
+
+def test_no_assertion_excludes_skipped(tmp_path: Path):
+    """A skipped test with no real assertion must not be double-flagged as no_assertion."""
+    _, ctx = _run(tmp_path)
+    no_assert = [f for f in ctx.metadata["findings"] if f.code == "no_assertion_test"]
+    flagged = {f.metadata.get("name") for f in no_assert}
+    assert "test_skipped" not in flagged
+    assert "test_no_assertions" in flagged
+
+
+def test_artifacts_and_not_running(tmp_path: Path):
+    out, _ = _run(tmp_path)
+    names = {p.name for p in out.iterdir()}
+    assert {
+        "tests.jsonl", "index.md", "validation_report.md",
+        "coverage_report.md", "not_running.md",
+    } <= names
+    not_running = (out / "not_running.md").read_text()
+    assert "test_skipped" in not_running
+    assert "test_expected_fail" in not_running
+
+
+def test_round_trip(tmp_path: Path):
+    out, _ = _run(tmp_path)
+    for line in (out / "tests.jsonl").read_text().splitlines():
+        c = TestCase.model_validate_json(line)
+        assert c.name