slimtest 0.1.0__py3-none-any.whl

slimtest/__init__.py

@@ -0,0 +1,13 @@
+"""slimtest — factory + trait DSL on top of dbt unit tests."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    __version__ = _version("slimtest")
+except PackageNotFoundError:  # not installed (e.g. running from a clean source tree)
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

slimtest/cli.py

@@ -0,0 +1,178 @@
+"""slimtest CLI entry point.
+
+`compile` is fully wired; `unittest` is still a stub pending the dbt
+subprocess layer (next phase).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from . import __version__
+from .compile import CompileResult, compile_project
+from .factory import SlimTestError
+from .runner import EnrichedOutcome, UnittestResult, unittest_project
+
+app = typer.Typer(
+    name="slimtest",
+    help="Factory + trait DSL on top of dbt unit tests.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+
+def _version_callback(value: bool) -> None:  # noqa: FBT001 -- typer convention
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit
+
+
+ProjectDirOption = Annotated[
+    Path,
+    typer.Option(
+        "--project-dir",
+        help="Path to the dbt project root (defaults to the current directory).",
+    ),
+]
+
+SelectOption = Annotated[
+    str | None,
+    typer.Option(
+        "--select",
+        help="Subset of models or tests to compile/run (dbt-style selector).",
+    ),
+]
+
+VerboseOption = Annotated[
+    bool,
+    typer.Option(
+        "--verbose",
+        "-v",
+        help=(
+            "Also print INFO-level notices (e.g. every auto-injected upstream "
+            "row). Warnings are always shown."
+        ),
+    ),
+]
+
+
+@app.callback()
+def _root(
+    version: Annotated[  # noqa: ARG001 -- handled by callback
+        bool,
+        typer.Option(
+            "--version",
+            callback=_version_callback,
+            is_eager=True,
+            help="Print the slimtest version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Top-level CLI options."""
+
+
+@app.command()
+def compile(  # noqa: A001 -- shadowing builtin is fine for a CLI verb
+    project_dir: ProjectDirOption = Path("."),
+    select: SelectOption = None,
+    verbose: VerboseOption = False,
+) -> None:
+    """Expand slimtest extension YAML into standard dbt unit_tests YAML.
+
+    Writes generated artefacts under `target/slimtest/` and does NOT
+    invoke dbt. Intended for debugging and inspection.
+    """
+    try:
+        result = compile_project(project_dir, select=select)
+    except SlimTestError as exc:
+        typer.echo(f"[slimtest] error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+    typer.echo(f"[slimtest] compiled {result.test_count} test(s):")
+    for path in result.generated_files:
+        rel = path.relative_to(result.project_root)
+        typer.echo(f"  -> {rel}")
+    rel_map = result.source_map_path.relative_to(result.project_root)
+    typer.echo(f"  -> {rel_map}")
+    _print_diagnostics(result, verbose=verbose)
+
+
+@app.command()
+def unittest(
+    project_dir: ProjectDirOption = Path("."),
+    select: SelectOption = None,
+    verbose: VerboseOption = False,
+) -> None:
+    """Compile + run the resulting unit tests via `dbt test`."""
+    try:
+        result = unittest_project(project_dir, select=select)
+    except SlimTestError as exc:
+        typer.echo(f"[slimtest] error: {exc}", err=True)
+        raise typer.Exit(code=1) from exc
+
+    _print_unittest_result(result, verbose=verbose)
+    raise typer.Exit(code=0 if result.ok else 1)
+
+
+# -- output helpers --------------------------------------------------
+
+
+def _print_diagnostics(compile_result: CompileResult, *, verbose: bool) -> None:
+    """Emit warnings always; emit notices only when verbose is set."""
+    for warning in compile_result.warnings:
+        typer.echo(f"[slimtest] warning: {warning}", err=True)
+    if verbose:
+        for notice in compile_result.notices:
+            typer.echo(f"[slimtest] info: {notice}", err=True)
+
+
+def _print_unittest_result(result: UnittestResult, *, verbose: bool = False) -> None:
+    n = result.compile.test_count
+    typer.echo(f"[slimtest] compiled {n} test(s)")
+    _print_diagnostics(result.compile, verbose=verbose)
+
+    if not result.parse_result.ok:
+        typer.echo(
+            f"[slimtest] warning: `dbt parse` exited {result.parse_result.exit_code}",
+            err=True,
+        )
+
+    if n == 0:
+        typer.echo("[slimtest] no slimtest tests to run.")
+        return
+
+    failed = [e for e in result.outcomes if e.outcome.status != "pass"]
+    typer.echo(
+        f"[slimtest] {result.summary.passed}/{result.summary.total} passed; "
+        f"{result.summary.failed} failed, "
+        f"{result.summary.errored} errored, "
+        f"{result.summary.skipped} skipped."
+    )
+
+    for entry in failed:
+        _print_failure(entry)
+
+    if result.summary.total == 0 and not result.test_result.ok:
+        # dbt failed before producing run_results.json -- surface stderr.
+        typer.echo(result.test_result.stderr, err=True)
+
+
+def _print_failure(entry: EnrichedOutcome) -> None:
+    label = entry.original_name or entry.outcome.name
+    if entry.source_file is not None and entry.source_line is not None:
+        location = f"{entry.source_file}:{entry.source_line}"
+    else:
+        location = "<source location unknown>"
+    typer.echo(
+        f"  {entry.outcome.status.upper()}: {label}  ({location})",
+        err=True,
+    )
+    if entry.outcome.message:
+        for line in entry.outcome.message.splitlines():
+            typer.echo(f"      {line}", err=True)
+
+
+__all__ = ["app"]

slimtest/compile.py

@@ -0,0 +1,268 @@
+"""Compile slimtest extension records into dbt-standard `unit_tests` YAML.
+
+End-to-end flow per design.md §8.1:
+
+  1. Load `slimtest.yml` (defaults if absent).
+  2. Build a `FactoryRegistry` from the factories_path.
+  3. Walk `models/**/*.yml` and collect every `meta.slimtest.unit_tests`
+     entry, paired with its source line.
+  4. For each entry, expand factory refs into literal rows.
+  5. Group by model, write `target/slimtest/<model>.generated.yml`.
+  6. Emit `target/slimtest/source_map.json` mapping generated test names
+     back to source (file, line).
+
+Upstream `ref()` vs `source()` disambiguation happens via the dbt
+manifest. If a manifest is supplied (or auto-loaded from
+`target/manifest.json`), each upstream identifier is rendered as the
+right form; if not, everything falls back to `ref('<name>')` and the
+caller is on the hook for any source-shaped tests it tries to run.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from io import StringIO
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+from .config import load_config
+from .dbt_project import check_generated_path_in_model_paths, load_dbt_project
+from .expand import ExpandedUnitTest, expand_unit_test
+from .factory import FactoryRegistry, SlimTestError
+from .manifest import Manifest, UpstreamRef, try_load_manifest
+from .model_parser import ParsedUnitTest, find_slimtest_tests
+from .parametrize import expand_parametrize
+from .scenario import apply_scenario
+from .schema import SlimTestConfig
+from .selector import filter_tests
+
+GENERATED_FILE_SUFFIX = ".generated.yml"
+SOURCE_MAP_FILENAME = "source_map.json"
+GENERATED_HEADER = "# Generated by slimtest. DO NOT EDIT.\n"
+
+
+@dataclass(frozen=True)
+class CompileResult:
+    """Summary of a `compile_project` run.
+
+    `source_map` is the in-memory form of what was written to
+    `source_map_path`; downstream stages (notably the unittest runner)
+    re-use it without round-tripping through JSON.
+
+    `warnings` collects situations that likely need user action (e.g.
+    a missing `model-paths` entry in dbt_project.yml). `notices` are
+    informational reports of automatic behaviour that worked as
+    designed (e.g. an upstream row that was auto-injected). CLI shows
+    warnings by default and notices only under `--verbose`.
+    """
+
+    project_root: Path
+    config: SlimTestConfig
+    output_dir: Path
+    generated_files: list[Path]
+    source_map_path: Path
+    source_map: dict[str, dict[str, Any]]
+    test_names: list[str]
+    warnings: list[str]
+    notices: list[str]
+
+    @property
+    def test_count(self) -> int:
+        return len(self.test_names)
+
+
+class DuplicateTestNameError(SlimTestError):
+    """Two unit tests resolved to the same `slimtest__<model>__<name>`."""
+
+    def __init__(self, name: str, first: Path, second: Path) -> None:
+        super().__init__(
+            f"duplicate generated test name {name!r}: defined in {first} and {second}"
+        )
+        self.name = name
+
+
+def compile_project(
+    project_root: Path,
+    *,
+    manifest: Manifest | None = None,
+    select: str | None = None,
+) -> CompileResult:
+    """Run the full compile flow against `project_root`.
+
+    If `manifest` is None, we try to load `target/manifest.json`; if
+    that file is also absent, upstreams are emitted as bare `ref()`
+    calls. `select` accepts a dbt-style selector (see `selector.py`).
+    """
+    project_root = project_root.resolve()
+    config = load_config(project_root)
+    registry = FactoryRegistry.load(project_root / config.factories_path)
+    parsed_tests = filter_tests(find_slimtest_tests(project_root), select)
+
+    effective_manifest = manifest or try_load_manifest(project_root)
+    warnings: list[str] = []
+    notices: list[str] = []
+
+    expanded_by_model: dict[str, list[ExpandedUnitTest]] = {}
+    seen: dict[str, Path] = {}
+
+    for parsed in parsed_tests:
+        expected_upstreams: list[str] = []
+        if effective_manifest is not None:
+            expected_upstreams = effective_manifest.get_upstreams(parsed.model_name)
+        for resolved_spec in _resolve_spec(parsed):
+            expanded = expand_unit_test(
+                resolved_spec,
+                model=parsed.model_name,
+                registry=registry,
+                source_file=parsed.source_path,
+                source_line=parsed.source_line,
+                expected_upstreams=expected_upstreams,
+                auto_fill=config.auto_fill_upstreams,
+            )
+            if expanded.auto_filled_upstreams:
+                for upstream in expanded.auto_filled_upstreams:
+                    notices.append(
+                        f"auto-injected base row of factory {upstream!r} for "
+                        f"upstream {upstream!r} in test "
+                        f"{expanded.prefixed_name!r} (not present in `given`)"
+                    )
+            if expanded.prefixed_name in seen:
+                raise DuplicateTestNameError(
+                    expanded.prefixed_name,
+                    first=seen[expanded.prefixed_name],
+                    second=parsed.source_path,
+                )
+            seen[expanded.prefixed_name] = parsed.source_path
+            expanded_by_model.setdefault(parsed.model_name, []).append(expanded)
+
+    dbt_project = load_dbt_project(project_root)
+    if dbt_project is not None:
+        warning = check_generated_path_in_model_paths(
+            dbt_project, config.generated_yml_path
+        )
+        if warning is not None:
+            warnings.append(warning)
+
+    output_dir = project_root / config.generated_yml_path
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    generated_files: list[Path] = []
+    source_map: dict[str, dict[str, Any]] = {}
+
+    for model_name, tests in sorted(expanded_by_model.items()):
+        out_path = output_dir / f"{model_name}{GENERATED_FILE_SUFFIX}"
+        _write_generated_yml(out_path, tests, manifest=effective_manifest)
+        generated_files.append(out_path)
+
+        rel_out = _relative_or_self(out_path, project_root)
+        for test in tests:
+            source_map[test.prefixed_name] = {
+                "source_file": str(test.source_file),
+                "source_line": test.source_line,
+                "generated_file": str(rel_out),
+                "model": test.model,
+                "original_name": test.original_name,
+            }
+
+    source_map_path = output_dir / SOURCE_MAP_FILENAME
+    with source_map_path.open("w", encoding="utf-8") as fh:
+        json.dump(source_map, fh, indent=2, sort_keys=True)
+        fh.write("\n")
+
+    test_names = sorted(source_map.keys())
+
+    return CompileResult(
+        project_root=project_root,
+        config=config,
+        output_dir=output_dir,
+        generated_files=generated_files,
+        source_map_path=source_map_path,
+        source_map=source_map,
+        test_names=test_names,
+        warnings=warnings,
+        notices=notices,
+    )
+
+
+# -- yml writer --------------------------------------------------------
+
+
+def _write_generated_yml(
+    path: Path, tests: list[ExpandedUnitTest], *, manifest: Manifest | None
+) -> None:
+    """Render the dbt-standard unit_tests yml for one model."""
+    yaml = YAML(typ="rt")
+    yaml.indent(mapping=2, sequence=4, offset=2)
+    yaml.default_flow_style = False
+
+    document = _build_document(tests, manifest=manifest)
+    buf = StringIO()
+    yaml.dump(document, buf)
+
+    with path.open("w", encoding="utf-8") as fh:
+        fh.write(GENERATED_HEADER)
+        fh.write(buf.getvalue())
+
+
+def _build_document(
+    tests: list[ExpandedUnitTest], *, manifest: Manifest | None
+) -> dict[str, Any]:
+    """Build the plain Python dict that becomes the generated yml file."""
+    return {
+        "version": 2,
+        "unit_tests": [_test_to_dbt_dict(t, manifest=manifest) for t in tests],
+    }
+
+
+def _test_to_dbt_dict(
+    test: ExpandedUnitTest, *, manifest: Manifest | None
+) -> dict[str, Any]:
+    entry: dict[str, Any] = {
+        "name": test.prefixed_name,
+        "model": test.model,
+    }
+    if test.description:
+        entry["description"] = test.description
+    entry["given"] = [
+        {"input": _input_expression(upstream, manifest), "rows": rows}
+        for upstream, rows in test.given.items()
+    ]
+    entry["expect"] = {"rows": test.expect}
+    return entry
+
+
+def _input_expression(upstream: str, manifest: Manifest | None) -> str:
+    """`ref(...)` or `source(...)` depending on what the manifest knows."""
+    if manifest is None:
+        return UpstreamRef(kind="ref", name=upstream).to_input_expression()
+    return manifest.resolve(upstream).to_input_expression()
+
+
+def _resolve_spec(parsed: ParsedUnitTest) -> list[Any]:
+    """Apply `parametrize` (1-to-N) and `scenario` (merge given) to one spec.
+
+    The output is a flat list of `UnitTestSpec`s with neither field set,
+    ready to feed `expand_unit_test`.
+    """
+    expanded = expand_parametrize(parsed.spec)
+    return [apply_scenario(spec, parsed.scenarios) for spec in expanded]
+
+
+def _relative_or_self(path: Path, base: Path) -> Path:
+    try:
+        return path.relative_to(base)
+    except ValueError:
+        return path
+
+
+__all__ = [
+    "CompileResult",
+    "DuplicateTestNameError",
+    "GENERATED_FILE_SUFFIX",
+    "GENERATED_HEADER",
+    "SOURCE_MAP_FILENAME",
+    "compile_project",
+]

slimtest/config.py

@@ -0,0 +1,57 @@
+"""Loader for `slimtest.yml`.
+
+The config file is optional. When absent, defaults from `SlimTestConfig`
+are used.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ruamel.yaml import YAML
+
+from .factory import SlimTestError
+from .schema import SlimTestConfig
+
+CONFIG_FILENAME = "slimtest.yml"
+
+
+class InvalidConfigError(SlimTestError):
+    """`slimtest.yml` exists but is malformed or fails schema validation."""
+
+    def __init__(self, path: Path, detail: str) -> None:
+        super().__init__(f"invalid {path}: {detail}")
+        self.path = path
+
+
+def load_config(project_root: Path) -> SlimTestConfig:
+    """Load `<project_root>/slimtest.yml` or return defaults.
+
+    A missing file is not an error -- the MVP defaults are usable as-is.
+    A present but malformed file raises `InvalidConfigError`.
+    """
+    config_path = project_root / CONFIG_FILENAME
+    if not config_path.exists():
+        return SlimTestConfig()
+
+    yaml = YAML(typ="safe")
+    try:
+        with config_path.open("r", encoding="utf-8") as fh:
+            raw = yaml.load(fh)
+    except Exception as exc:  # noqa: BLE001
+        raise InvalidConfigError(config_path, str(exc)) from exc
+
+    if raw is None:
+        return SlimTestConfig()
+    if not isinstance(raw, dict):
+        raise InvalidConfigError(
+            config_path, f"expected a mapping at top level, got {type(raw).__name__}"
+        )
+
+    try:
+        return SlimTestConfig.model_validate(raw)
+    except Exception as exc:  # noqa: BLE001 -- pydantic ValidationError
+        raise InvalidConfigError(config_path, str(exc)) from exc
+
+
+__all__ = ["CONFIG_FILENAME", "InvalidConfigError", "load_config"]

slimtest/dbt_project.py

@@ -0,0 +1,109 @@
+"""Read `dbt_project.yml` for the bits slimtest needs.
+
+Right now that's just `model-paths`, so we know whether `dbt` will
+actually pick up the generated yml we wrote to `target/slimtest/`. If
+it won't, the CLI surfaces a warning that walks the user through fixing
+it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ruamel.yaml import YAML
+
+from .factory import SlimTestError
+
+DBT_PROJECT_FILENAME = "dbt_project.yml"
+DEFAULT_MODEL_PATHS: tuple[str, ...] = ("models",)
+
+
+class InvalidDbtProjectError(SlimTestError):
+    """`dbt_project.yml` exists but is malformed or has unexpected shape."""
+
+    def __init__(self, path: Path, detail: str) -> None:
+        super().__init__(f"invalid {path}: {detail}")
+        self.path = path
+
+
+@dataclass(frozen=True)
+class DbtProject:
+    """Slim view over `dbt_project.yml`."""
+
+    project_root: Path
+    model_paths: tuple[str, ...]
+
+
+def load_dbt_project(project_root: Path) -> DbtProject | None:
+    """Load `<project_root>/dbt_project.yml`, or return None if absent.
+
+    A missing file is not an error: `slimtest compile` works without
+    dbt being present at all (debugging use case).
+    """
+    path = project_root / DBT_PROJECT_FILENAME
+    if not path.exists():
+        return None
+
+    yaml = YAML(typ="safe")
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data: Any = yaml.load(fh)
+    except Exception as exc:  # noqa: BLE001
+        raise InvalidDbtProjectError(path, str(exc)) from exc
+
+    if data is None:
+        return DbtProject(project_root=project_root, model_paths=DEFAULT_MODEL_PATHS)
+    if not isinstance(data, dict):
+        raise InvalidDbtProjectError(
+            path, f"top level must be a mapping, got {type(data).__name__}"
+        )
+
+    raw_paths = data.get("model-paths", list(DEFAULT_MODEL_PATHS))
+    if not isinstance(raw_paths, list):
+        raise InvalidDbtProjectError(path, "`model-paths` must be a list")
+    if not all(isinstance(p, str) for p in raw_paths):
+        raise InvalidDbtProjectError(
+            path, "every entry in `model-paths` must be a string"
+        )
+
+    return DbtProject(
+        project_root=project_root,
+        model_paths=tuple(raw_paths),
+    )
+
+
+def check_generated_path_in_model_paths(
+    dbt_project: DbtProject, generated_yml_path: str
+) -> str | None:
+    """Return a warning string if `generated_yml_path` isn't in model-paths.
+
+    The comparison normalises both sides via `Path()` so trailing
+    slashes, `./` prefixes, etc. don't cause false negatives.
+    """
+    target = _normalise(generated_yml_path)
+    known = {_normalise(p) for p in dbt_project.model_paths}
+    if target in known:
+        return None
+    return (
+        f"`{generated_yml_path}` is not in `model-paths` in dbt_project.yml -- "
+        "dbt won't pick up the generated unit tests. Add it, e.g.:\n"
+        f"    model-paths: [{', '.join(repr(p) for p in dbt_project.model_paths)}"
+        f", {generated_yml_path!r}]"
+    )
+
+
+def _normalise(path: str) -> str:
+    """Canonical string form so equivalent paths compare equal."""
+    return str(Path(path))
+
+
+__all__ = [
+    "DBT_PROJECT_FILENAME",
+    "DEFAULT_MODEL_PATHS",
+    "DbtProject",
+    "InvalidDbtProjectError",
+    "check_generated_path_in_model_paths",
+    "load_dbt_project",
+]