test_map

mkdocs_terok.test_map

Generate a Markdown test map from pytest collection.

Runs pytest --collect-only -qq on an integration test directory and groups the collected test IDs by subdirectory, producing Markdown tables with optional marker extraction and CI tier columns.

TestMapConfig dataclass

Configuration for test map generation.

Attributes:

Name	Type	Description
root	Path	Project root directory.
integration_dir	Path | None	Integration test directory. Defaults to root / "tests" / "integration".
dir_order	Sequence[str]	Canonical ordering for known test subdirectories.
show_markers	bool	Include CI tier and marker columns in the output.
title	str	Page title for the generated Markdown.

Source code in src/mkdocs_terok/test_map.py

@dataclass(frozen=True)
class TestMapConfig:
    """Configuration for test map generation.

    Attributes:
        root: Project root directory.
        integration_dir: Integration test directory. Defaults to
            ``root / "tests" / "integration"``.
        dir_order: Canonical ordering for known test subdirectories.
        show_markers: Include CI tier and marker columns in the output.
        title: Page title for the generated Markdown.
    """

    root: Path = field(default_factory=Path.cwd)
    integration_dir: Path | None = None
    dir_order: Sequence[str] = ()
    show_markers: bool = True
    title: str = "Integration Test Map"

    @property
    def resolved_integration_dir(self) -> Path:
        """Return the integration test directory, with fallback to default."""
        if self.integration_dir is not None:
            return self.integration_dir
        return self.root / "tests" / "integration"

resolved_integration_dir property

Return the integration test directory, with fallback to default.

collect_tests(*, config=None)

Run pytest --collect-only and return the list of test node IDs.

Parameters:

Name	Type	Description	Default
config	TestMapConfig | None	Test map configuration. Uses defaults if None.	None

Raises:

Type	Description
RuntimeError	If pytest collection fails (non-zero exit code).

Source code in src/mkdocs_terok/test_map.py

def collect_tests(*, config: TestMapConfig | None = None) -> list[str]:
    """Run pytest --collect-only and return the list of test node IDs.

    Args:
        config: Test map configuration. Uses defaults if ``None``.

    Raises:
        RuntimeError: If pytest collection fails (non-zero exit code).
    """
    if config is None:
        config = TestMapConfig()
    result = subprocess.run(
        [
            sys.executable,
            "-m",
            "pytest",
            "--collect-only",
            "-qq",
            "-p",
            "no:tach",
            str(config.resolved_integration_dir),
        ],
        capture_output=True,
        text=True,
        cwd=config.root,
        timeout=60,
        check=False,
    )
    if result.returncode != 0:
        msg = (result.stdout + result.stderr).strip()
        raise RuntimeError(f"pytest collection failed (exit {result.returncode}):\n{msg}")
    return [line.strip() for line in result.stdout.splitlines() if "::" in line]

generate_test_map(test_ids=None, *, config=None)

Generate a Markdown test map grouped by directory.

Parameters:

Name	Type	Description	Default
test_ids	list[str] | None	Optional pre-collected test IDs. If None, runs pytest --collect-only to collect them.	None
config	TestMapConfig | None	Configuration for the test map. Uses defaults if None.	None

Returns:

Type	Description
str	Markdown string with the test map.

Source code in src/mkdocs_terok/test_map.py

def generate_test_map(
    test_ids: list[str] | None = None,
    *,
    config: TestMapConfig | None = None,
) -> str:
    """Generate a Markdown test map grouped by directory.

    Args:
        test_ids: Optional pre-collected test IDs. If ``None``, runs
            ``pytest --collect-only`` to collect them.
        config: Configuration for the test map. Uses defaults if ``None``.

    Returns:
        Markdown string with the test map.
    """
    if config is None:
        config = TestMapConfig()
    if test_ids is None:
        test_ids = collect_tests(config=config)

    groups = _group_by_directory(test_ids, config.resolved_integration_dir)
    now = datetime.now(UTC).strftime("%Y-%m-%d %H:%M UTC")
    lines = [
        f"# {config.title}\n\n",
        f"*Generated: {now}*\n\n",
        f"**{len(test_ids)} tests** across **{len(groups)} directories**\n\n",
    ]

    for subdir in _sorted_dirs(groups, config.dir_order):
        lines.append(f"## `{subdir}/`\n\n")
        desc = _dir_description(subdir, config.resolved_integration_dir)
        if desc:
            lines.append(f"{desc}\n\n")

        if config.show_markers:
            lines.append("| Test | Class | CI Tier | Markers |\n")
            lines.append("|---|---|---|---|\n")
        else:
            lines.append("| Test | Class | File |\n")
            lines.append("|---|---|---|\n")

        marker_cache: dict[str, dict[str, list[str]]] = {}
        for tid in sorted(groups[subdir]):
            lines.append(
                _test_row(tid, marker_cache, config.root, show_markers=config.show_markers) + "\n"
            )
        lines.append("\n")

    return "".join(lines)