testops-mirror 0.1.0__py3-none-any.whl

testops_mirror/__init__.py

@@ -0,0 +1,3 @@
+"""testops-mirror: mirror TMS test cases into a Git repository."""
+
+__version__ = "0.1.0"

testops_mirror/cli.py

@@ -0,0 +1,149 @@
+"""Command-line interface for testops-mirror."""
+
+from __future__ import annotations
+
+import logging
+import sys
+from typing import Annotated
+
+import typer
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from testops_mirror.connectors.allure_testops import AllureTestOpsConnector
+from testops_mirror.exceptions import AuthError, TestopsMirrorError
+from testops_mirror.gitstore import GitStore
+from testops_mirror.models import TestCase
+from testops_mirror.sync import run_sync
+
+app = typer.Typer(
+    name="testops-mirror",
+    help="Mirror test cases from a TMS into a Git repository.",
+    add_completion=False,
+)
+console = Console()
+err_console = Console(stderr=True)
+
+
+_ProjectId = Annotated[
+    str, typer.Option("--project-id", help="TMS project ID.", envvar="TESTOPS_PROJECT_ID")
+]
+_Endpoint = Annotated[
+    str, typer.Option("--endpoint", help="Base URL of the TMS.", envvar="TESTOPS_ENDPOINT")
+]
+_Token = Annotated[str, typer.Option("--token", help="API token.", envvar="TESTOPS_TOKEN")]
+_Repo = Annotated[str, typer.Option("--repo", help="Local git repository path.")]
+_SuiteField = Annotated[
+    str,
+    typer.Option(
+        "--suite-field",
+        help="Custom field for folder structure.",
+        envvar="TESTOPS_SUITE_FIELD",
+    ),
+]
+_DryRun = Annotated[bool, typer.Option("--dry-run", help="Preview changes without writing.")]
+_Verbose = Annotated[bool, typer.Option("-v", "--verbose", help="Verbose logging.")]
+
+
+@app.command()
+def sync(
+    project_id: _ProjectId,
+    endpoint: _Endpoint,
+    token: _Token,
+    repo: _Repo = "./mirror",
+    suite_field: _SuiteField = "Suite",
+    dry_run: _DryRun = False,
+    verbose: _Verbose = False,
+) -> None:
+    """Mirror all test cases from a TMS project into a local Git repository."""
+    load_dotenv()
+
+    logging.basicConfig(
+        level=logging.DEBUG if verbose else logging.WARNING,
+        format="%(levelname)s %(name)s: %(message)s",
+    )
+
+    connector = AllureTestOpsConnector(
+        endpoint=endpoint,
+        api_token=token,
+        suite_field=suite_field,
+    )
+    store = GitStore(repo)
+
+    fetched: list[TestCase] = []
+
+    def _on_case(case: TestCase) -> None:
+        fetched.append(case)
+        if len(fetched) % 50 == 0:
+            logging.getLogger(__name__).info("Fetched %d cases so far...", len(fetched))
+
+    try:
+        if dry_run:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+                transient=True,
+            ) as progress:
+                task = progress.add_task("Fetching test cases...", total=None)
+                changes, _ = run_sync(
+                    connector,
+                    store,
+                    project_id,
+                    dry_run=True,
+                    on_case=_on_case,
+                )
+                progress.update(task, completed=True)
+
+            console.print(f"Found [bold]{len(fetched)}[/bold] test cases")
+            console.print()
+
+            for path in changes.added:
+                console.print(f"[green]+[/green] {path}")
+            for path in changes.updated:
+                console.print(f"[yellow]~[/yellow] {path}")
+            for path in changes.deleted:
+                console.print(f"[red]-[/red] {path}")
+
+            if not changes.empty:
+                console.print()
+            console.print(
+                f"[bold]{len(changes.added)}[/bold] to add, "
+                f"[bold]{len(changes.updated)}[/bold] to update, "
+                f"[bold]{len(changes.deleted)}[/bold] to delete"
+            )
+
+        else:
+            with Progress(
+                SpinnerColumn(),
+                TextColumn("[progress.description]{task.description}"),
+                console=console,
+            ) as progress:
+                task = progress.add_task("Fetching test cases...", total=None)
+                changes, sha = run_sync(
+                    connector,
+                    store,
+                    project_id,
+                    on_case=_on_case,
+                )
+                progress.update(
+                    task,
+                    description=f"Fetched {len(fetched)} test cases",
+                    completed=True,
+                )
+
+            if sha:
+                console.print(f"[green]Committed[/green] {sha[:8]} — {changes.summary()}")
+            else:
+                console.print("[dim]Nothing to commit[/dim]")
+
+    except AuthError as exc:
+        err_console.print(f"[red]Authentication failed:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    except TestopsMirrorError as exc:
+        err_console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    except KeyboardInterrupt:
+        err_console.print("\n[yellow]Interrupted[/yellow]")
+        sys.exit(130)

testops_mirror/connectors/__init__.py

@@ -0,0 +1 @@
+"""TMS connector implementations."""

testops_mirror/connectors/allure_testops.py

@@ -0,0 +1,380 @@
+"""Allure TestOps connector.
+
+Implements the TmsConnector protocol for Allure TestOps instances.
+
+API paths are defined as module-level constants — verify them against your
+instance's Swagger UI (<endpoint>/swagger-ui/) as paths may differ between
+TestOps versions.
+
+Authentication flow (confirmed by official docs):
+  POST /api/uaa/oauth/token  (form: grant_type=apitoken, scope=openid, token=<api_token>)
+  -> { access_token, expires_in }
+  The JWT is then used as Bearer for all /api/rs/* requests.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from testops_mirror.exceptions import AuthError, ConnectorError, NotFoundError, RateLimitError
+from testops_mirror.models import Link, Step, TestCase
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# API path constants
+# Verify against <endpoint>/swagger-ui/ for your TestOps version.
+# ---------------------------------------------------------------------------
+_PATH_TOKEN = "/api/uaa/oauth/token"
+_PATH_TESTCASE_LIST = "/api/rs/testcase"  # ?projectId=&page=&size=
+_PATH_TESTCASE_DETAIL = "/api/rs/testcase/{id}"
+_PATH_TESTCASE_SCENARIO = "/api/rs/testcase/{id}/scenario"
+_PATH_TESTCASE_STEP = "/api/rs/testcase/{id}/step"
+
+_PAGE_SIZE = 100
+_RETRY_STATUSES = {429, 500, 502, 503, 504}
+_MAX_RETRIES = 3
+_RETRY_BASE_DELAY = 1.0  # seconds; doubled on each attempt
+_TOKEN_REFRESH_BUFFER = 60  # seconds before expiry to proactively refresh
+
+
+class AllureTestOpsConnector:
+    """Connector for Allure TestOps.
+
+    Parameters
+    ----------
+    endpoint:
+        Base URL of the TestOps instance, e.g. ``https://testops.example.com``.
+    api_token:
+        API token generated in TestOps → Profile → API tokens.
+    suite_field:
+        Name of the custom field used to derive the folder hierarchy.
+        Values like ``"Shipments/Negative"`` are split on ``/`` to produce
+        nested directories.
+    """
+
+    def __init__(
+        self,
+        endpoint: str,
+        api_token: str,
+        suite_field: str = "Suite",
+        *,
+        http_client: httpx.Client | None = None,
+    ) -> None:
+        self._endpoint = endpoint.rstrip("/")
+        self._api_token = api_token
+        self._suite_field = suite_field
+        self._client = http_client or httpx.Client(timeout=30)
+        self._jwt: str | None = None
+        self._jwt_expires_at: float = 0.0
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    def _authenticate(self) -> None:
+        """Exchange the API token for a short-lived JWT."""
+        url = self._endpoint + _PATH_TOKEN
+        try:
+            resp = self._client.post(
+                url,
+                data={
+                    "grant_type": "apitoken",
+                    "scope": "openid",
+                    "token": self._api_token,
+                },
+            )
+        except httpx.HTTPError as exc:
+            raise ConnectorError(f"Auth request failed: {exc}") from exc
+
+        if resp.status_code in (401, 403):
+            raise AuthError(f"Authentication failed ({resp.status_code}): {resp.text}")
+        if not resp.is_success:
+            raise ConnectorError(f"Auth endpoint returned {resp.status_code}: {resp.text}")
+
+        data = resp.json()
+        self._jwt = data["access_token"]
+        expires_in: int = data.get("expires_in", 3600)
+        self._jwt_expires_at = time.monotonic() + expires_in
+
+    def _get_bearer(self) -> str:
+        """Return a valid JWT, refreshing proactively if close to expiry."""
+        if self._jwt is None or time.monotonic() >= self._jwt_expires_at - _TOKEN_REFRESH_BUFFER:
+            self._authenticate()
+        assert self._jwt is not None
+        return self._jwt
+
+    # ------------------------------------------------------------------
+    # HTTP with retry
+    # ------------------------------------------------------------------
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> httpx.Response:
+        """Send an authenticated request with retry logic.
+
+        Retries on 429 and 5xx up to _MAX_RETRIES times using exponential
+        backoff.  On 401 attempts one token refresh before retrying.
+        Raises typed exceptions for all terminal error conditions.
+        """
+        url = self._endpoint + path
+        delay = _RETRY_BASE_DELAY
+        last_exc: Exception | None = None
+
+        for attempt in range(_MAX_RETRIES):
+            headers = {"Authorization": f"Bearer {self._get_bearer()}"}
+            try:
+                resp = self._client.request(method, url, headers=headers, **kwargs)
+            except httpx.HTTPError as exc:
+                last_exc = exc
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(delay)
+                    delay *= 2
+                continue
+
+            if resp.status_code == 401:
+                if attempt < _MAX_RETRIES - 1:
+                    # Force token refresh and retry once
+                    self._jwt = None
+                    continue
+                raise AuthError(f"Persistent 401 on {path}")
+
+            if resp.status_code == 403:
+                raise AuthError(f"Forbidden (403) on {path}")
+
+            if resp.status_code == 404:
+                raise NotFoundError(f"Resource not found: {path}")
+
+            if resp.status_code == 429:
+                retry_after = float(resp.headers.get("Retry-After", delay))
+                logger.warning("Rate limited (429); sleeping %.1fs", retry_after)
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(retry_after)
+                    delay *= 2
+                    last_exc = RateLimitError(f"Rate limit on {path}")
+                    continue
+                raise RateLimitError(f"Rate limit exceeded after {_MAX_RETRIES} attempts on {path}")
+
+            if resp.status_code >= 500:
+                logger.warning(
+                    "Server error %d on %s; attempt %d/%d",
+                    resp.status_code,
+                    path,
+                    attempt + 1,
+                    _MAX_RETRIES,
+                )
+                if attempt < _MAX_RETRIES - 1:
+                    time.sleep(delay)
+                    delay *= 2
+                    last_exc = ConnectorError(f"Server error {resp.status_code} on {path}")
+                    continue
+                raise ConnectorError(
+                    f"Server error {resp.status_code} after {_MAX_RETRIES} attempts on {path}"
+                )
+
+            if not resp.is_success:
+                raise ConnectorError(f"Unexpected {resp.status_code} on {path}: {resp.text}")
+
+            return resp
+
+        if last_exc is not None:
+            raise ConnectorError(f"All {_MAX_RETRIES} attempts failed for {path}") from last_exc
+        raise ConnectorError(f"Request failed for {path}")  # unreachable, satisfies mypy
+
+    # ------------------------------------------------------------------
+    # Steps — fallback chain
+    # ------------------------------------------------------------------
+
+    def _fetch_steps(self, case_id: str) -> list[dict[str, Any]]:
+        """Fetch steps using a fallback chain.
+
+        Known bug in some TestOps versions: /scenario returns empty steps.
+        See: github.com/orgs/allure-framework/discussions/3190
+        Try /scenario first; if the result is empty fall back to /step.
+        4xx responses are silently ignored (return empty list).
+        """
+        for path_tpl in (_PATH_TESTCASE_SCENARIO, _PATH_TESTCASE_STEP):
+            path = path_tpl.format(id=case_id)
+            try:
+                resp = self._request("GET", path)
+                data = resp.json()
+                steps: list[dict[str, Any]] = (
+                    data if isinstance(data, list) else data.get("steps", data.get("content", []))
+                )
+                if steps:
+                    return steps
+            except (NotFoundError, ConnectorError):
+                pass
+        return []
+
+    # ------------------------------------------------------------------
+    # Mapping helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _extract_status(raw: Any) -> str | None:
+        if isinstance(raw, dict):
+            return str(raw["name"]) if "name" in raw else None
+        if isinstance(raw, str):
+            return raw or None
+        return None
+
+    @staticmethod
+    def _extract_tags(raw: Any) -> list[str]:
+        if not isinstance(raw, list):
+            return []
+        result = []
+        for item in raw:
+            if isinstance(item, dict):
+                name = item.get("name")
+                if name:
+                    result.append(str(name))
+            elif isinstance(item, str) and item:
+                result.append(item)
+        return result
+
+    def _extract_custom_fields(self, raw: Any) -> dict[str, list[str]]:
+        """Extract custom fields from the API response.
+
+        Expected shape (verify against your instance):
+          customFields[].customField.name  — field name
+          customFields[].name              — field value
+        """
+        if not isinstance(raw, list):
+            return {}
+        result: dict[str, list[str]] = {}
+        for item in raw:
+            if not isinstance(item, dict):
+                continue
+            cf = item.get("customField", {})
+            field_name: str = cf.get("name", "") if isinstance(cf, dict) else ""
+            value: str = item.get("name", "")
+            if field_name and value:
+                result.setdefault(field_name, []).append(value)
+        return result
+
+    def _extract_suite_path(self, custom_fields: dict[str, list[str]]) -> tuple[str, ...]:
+        """Derive suite folder path from the configured custom field.
+
+        A value of ``"Shipments/Negative"`` becomes ``("Shipments", "Negative")``.
+        Cases without the field land in the repo root.
+        """
+        values = custom_fields.get(self._suite_field, [])
+        if not values:
+            return ()
+        # Use the first value; split on "/" for nested paths
+        return tuple(part.strip() for part in values[0].split("/") if part.strip())
+
+    @staticmethod
+    def _map_steps(raw: list[dict[str, Any]]) -> list[Step]:
+        result = []
+        for item in raw:
+            if not isinstance(item, dict):
+                continue
+            name: str = item.get("name") or item.get("keyword") or ""
+            if not name:
+                continue
+            expected: str | None = item.get("expectedResult") or item.get("expected_result") or None
+            nested_raw: list[dict[str, Any]] = item.get("steps", [])
+            result.append(
+                Step(
+                    name=name,
+                    expected_result=expected,
+                    steps=AllureTestOpsConnector._map_steps(nested_raw),
+                )
+            )
+        return result
+
+    @staticmethod
+    def _map_links(raw: Any) -> list[Link]:
+        if not isinstance(raw, list):
+            return []
+        result = []
+        for item in raw:
+            if not isinstance(item, dict):
+                continue
+            url: str = item.get("url", "")
+            if not url:
+                continue
+            result.append(
+                Link(
+                    name=item.get("name") or None,
+                    url=url,
+                    type=item.get("type") or None,
+                )
+            )
+        return result
+
+    def _map_case(
+        self,
+        detail: dict[str, Any],
+        steps_raw: list[dict[str, Any]],
+        project_id: str,
+    ) -> TestCase:
+        case_id = str(detail["id"])
+        custom_fields = self._extract_custom_fields(detail.get("customFields"))
+        suite_path = self._extract_suite_path(custom_fields)
+
+        return TestCase(
+            id=case_id,
+            name=detail.get("name", ""),
+            description=detail.get("description") or None,
+            precondition=detail.get("precondition") or None,
+            expected_result=detail.get("expectedResult") or None,
+            status=self._extract_status(detail.get("status")),
+            automated=bool(detail.get("automated", False)),
+            tags=self._extract_tags(detail.get("tags")),
+            custom_fields=custom_fields,
+            links=self._map_links(detail.get("links")),
+            suite_path=suite_path,
+            steps=self._map_steps(steps_raw),
+            source_url=f"{self._endpoint}/project/{project_id}/test-cases/{case_id}",
+            source_project=project_id,
+        )
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def iter_test_cases(self, project_id: str) -> Iterator[TestCase]:
+        """Yield all test cases for *project_id*.
+
+        Fetches the full list page by page, then loads details and steps for
+        each case.  A ConnectorError on a single case is logged as WARNING and
+        that case is skipped; it does not abort the entire sync.
+
+        Raises AuthError immediately if token exchange fails — this is not
+        recoverable per-case.
+        """
+        page = 0
+        while True:
+            resp = self._request(
+                "GET",
+                _PATH_TESTCASE_LIST,
+                params={"projectId": project_id, "page": page, "size": _PAGE_SIZE},
+            )
+            data = resp.json()
+            items: list[dict[str, Any]] = data.get("content", [])
+            total_pages: int = data.get("totalPages", 1)
+
+            for item in items:
+                case_id = str(item.get("id", ""))
+                if not case_id:
+                    continue
+                try:
+                    detail_resp = self._request("GET", _PATH_TESTCASE_DETAIL.format(id=case_id))
+                    detail: dict[str, Any] = detail_resp.json()
+                    steps_raw = self._fetch_steps(case_id)
+                    yield self._map_case(detail, steps_raw, project_id)
+                except AuthError:
+                    raise
+                except Exception as exc:
+                    logger.warning("Skipping test case %s due to error: %s", case_id, exc)
+                    continue
+
+            page += 1
+            if page >= total_pages:
+                break

testops_mirror/connectors/base.py

@@ -0,0 +1,31 @@
+"""Base protocol for TMS connectors.
+
+Any new connector must implement :class:`TmsConnector` — a single method
+``iter_test_cases`` that yields canonical :class:`~testops_mirror.models.TestCase`
+objects.  No connector-specific types should leak outside the connector module.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import Protocol, runtime_checkable
+
+from testops_mirror.models import TestCase
+
+
+@runtime_checkable
+class TmsConnector(Protocol):
+    """Structural protocol for TMS connectors.
+
+    To add a new connector, implement this method and wire it up in the CLI.
+    See CONTRIBUTING.md for details.
+    """
+
+    def iter_test_cases(self, project_id: str) -> Iterator[TestCase]:
+        """Yield all test cases for *project_id* as canonical TestCase objects.
+
+        Must raise:
+        - :class:`~testops_mirror.exceptions.AuthError` on 401/403
+        - :class:`~testops_mirror.exceptions.ConnectorError` on unrecoverable errors
+        """
+        ...

testops_mirror/exceptions.py

@@ -0,0 +1,25 @@
+"""Custom exception hierarchy for testops-mirror.
+
+All exceptions raised by connectors and core modules are subclasses of
+TestopsMirrorError so callers can catch them with a single except clause.
+"""
+
+
+class TestopsMirrorError(Exception):
+    """Base exception for all testops-mirror errors."""
+
+
+class AuthError(TestopsMirrorError):
+    """Authentication or authorisation failure (401/403)."""
+
+
+class NotFoundError(TestopsMirrorError):
+    """Requested resource does not exist (404)."""
+
+
+class RateLimitError(TestopsMirrorError):
+    """API rate limit exceeded (429)."""
+
+
+class ConnectorError(TestopsMirrorError):
+    """Generic connector-level error (5xx, network, parse)."""

testops_mirror/gitstore.py

@@ -0,0 +1,154 @@
+"""Git-backed storage for mirrored test cases.
+
+All test-case files live under the ``cases/`` subdirectory of the managed
+repository.  The store is intentionally TMS-agnostic: it operates on
+(relpath -> content) mappings produced by the serializer.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+
+from git import Actor, InvalidGitRepositoryError, Repo
+
+logger = logging.getLogger(__name__)
+
+CASES_DIR = "cases"
+DEFAULT_AUTHOR_NAME = "testops-mirror"
+DEFAULT_AUTHOR_EMAIL = "testops-mirror@localhost"
+
+
+@dataclass
+class ChangeSet:
+    added: list[str] = field(default_factory=list)
+    updated: list[str] = field(default_factory=list)
+    deleted: list[str] = field(default_factory=list)
+
+    @property
+    def empty(self) -> bool:
+        return not (self.added or self.updated or self.deleted)
+
+    def summary(self) -> str:
+        parts = []
+        if self.added:
+            parts.append(f"{len(self.added)} added")
+        if self.updated:
+            parts.append(f"{len(self.updated)} updated")
+        if self.deleted:
+            parts.append(f"{len(self.deleted)} deleted")
+        return ", ".join(parts) if parts else "no changes"
+
+
+class GitStore:
+    """Manage a ``cases/`` directory inside a Git repository."""
+
+    def __init__(
+        self,
+        repo_path: str | Path,
+        author_name: str = DEFAULT_AUTHOR_NAME,
+        author_email: str = DEFAULT_AUTHOR_EMAIL,
+    ) -> None:
+        self._root = Path(repo_path)
+        self._author = Actor(author_name, author_email)
+        self._root.mkdir(parents=True, exist_ok=True)
+        try:
+            self._repo = Repo(self._root)
+        except InvalidGitRepositoryError:
+            self._repo = Repo.init(self._root)
+            logger.info("Initialised new git repository at %s", self._root)
+
+    @property
+    def cases_dir(self) -> Path:
+        return self._root / CASES_DIR
+
+    # ------------------------------------------------------------------
+    # Plan
+    # ------------------------------------------------------------------
+
+    def plan(self, desired: dict[str, str]) -> ChangeSet:
+        """Compare *desired* (relpath -> content) against the working tree.
+
+        Returns a :class:`ChangeSet` describing what needs to change.
+        All lists in the result are sorted for deterministic output.
+        """
+        existing = self._read_existing()
+
+        desired_keys = set(desired)
+        existing_keys = set(existing)
+
+        added = sorted(desired_keys - existing_keys)
+        deleted = sorted(existing_keys - desired_keys)
+        updated = sorted(k for k in desired_keys & existing_keys if desired[k] != existing[k])
+
+        return ChangeSet(added=added, updated=updated, deleted=deleted)
+
+    # ------------------------------------------------------------------
+    # Apply
+    # ------------------------------------------------------------------
+
+    def apply(
+        self,
+        desired: dict[str, str],
+        changes: ChangeSet,
+        message: str | None = None,
+    ) -> str | None:
+        """Write/delete files according to *changes* and create a git commit.
+
+        Returns the commit SHA, or ``None`` if *changes* is empty.
+        """
+        if changes.empty:
+            return None
+
+        for relpath in changes.added + changes.updated:
+            abs_path = self.cases_dir / relpath
+            abs_path.parent.mkdir(parents=True, exist_ok=True)
+            abs_path.write_text(desired[relpath], encoding="utf-8")
+
+        for relpath in changes.deleted:
+            abs_path = self.cases_dir / relpath
+            if abs_path.exists():
+                abs_path.unlink()
+
+        self._prune_empty_dirs()
+
+        self._repo.git.add(str(self.cases_dir))
+
+        if message is None:
+            ts = datetime.now(tz=UTC).strftime("%Y-%m-%d %H:%M UTC")
+            message = f"sync: {changes.summary()} ({ts})"
+
+        commit = self._repo.index.commit(
+            message,
+            author=self._author,
+            committer=self._author,
+        )
+        logger.info("Created commit %s: %s", commit.hexsha[:8], message)
+        return str(commit.hexsha)
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _read_existing(self) -> dict[str, str]:
+        """Return all *.md files under cases/ as {relpath: content}."""
+        if not self.cases_dir.exists():
+            return {}
+        result: dict[str, str] = {}
+        for md_file in self.cases_dir.rglob("*.md"):
+            relpath = str(md_file.relative_to(self.cases_dir))
+            result[relpath] = md_file.read_text(encoding="utf-8")
+        return result
+
+    def _prune_empty_dirs(self) -> None:
+        """Remove empty subdirectories under cases/ (bottom-up)."""
+        if not self.cases_dir.exists():
+            return
+        for dirpath in sorted(self.cases_dir.rglob("*"), reverse=True):
+            if dirpath.is_dir() and dirpath != self.cases_dir:
+                try:
+                    dirpath.rmdir()
+                except OSError:
+                    pass

testops_mirror/models.py

@@ -0,0 +1,45 @@
+"""Canonical TMS-agnostic data models.
+
+These models are the single source of truth between connectors and the
+serializer. No connector-specific fields belong here.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel
+
+
+class Step(BaseModel):
+    name: str
+    expected_result: str | None = None
+    steps: list[Step] = []
+
+
+# Required for Pydantic v2 self-referential model
+Step.model_rebuild()
+
+
+class Link(BaseModel):
+    name: str | None = None
+    url: str
+    type: str | None = None  # "issue" | "tms" | ...
+
+
+class TestCase(BaseModel):
+    # pytest must not collect this as a test class
+    __test__ = False
+
+    id: str
+    name: str
+    description: str | None = None
+    precondition: str | None = None
+    expected_result: str | None = None
+    status: str | None = None
+    automated: bool = False
+    tags: list[str] = []
+    custom_fields: dict[str, list[str]] = {}
+    links: list[Link] = []
+    suite_path: tuple[str, ...] = ()
+    steps: list[Step] = []
+    source_url: str | None = None
+    source_project: str | None = None

testops_mirror/serializer.py

@@ -0,0 +1,217 @@
+"""Serialize TestCase instances to Markdown files with YAML front matter.
+
+Invariants enforced here:
+- Determinism: identical input always produces identical bytes.
+- Stable file names: TC-{id}-{slug}.md, slug is cosmetic only.
+- Collision handling: if a different slug exists for the same ID, append -2, -3, ...
+"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+from pathlib import PurePosixPath
+from typing import Any
+
+import yaml
+
+from testops_mirror.models import Step, TestCase
+
+# Characters illegal in directory names on Windows/Linux/macOS
+_DIR_FORBIDDEN = re.compile(r'[/\\:*?"<>|]')
+
+# Transliteration table for common Cyrillic characters
+_CYRILLIC: dict[str, str] = {
+    "а": "a",
+    "б": "b",
+    "в": "v",
+    "г": "g",
+    "д": "d",
+    "е": "e",
+    "ё": "yo",
+    "ж": "zh",
+    "з": "z",
+    "и": "i",
+    "й": "j",
+    "к": "k",
+    "л": "l",
+    "м": "m",
+    "н": "n",
+    "о": "o",
+    "п": "p",
+    "р": "r",
+    "с": "s",
+    "т": "t",
+    "у": "u",
+    "ф": "f",
+    "х": "kh",
+    "ц": "ts",
+    "ч": "ch",
+    "ш": "sh",
+    "щ": "shch",
+    "ъ": "",
+    "ы": "y",
+    "ь": "",
+    "э": "e",
+    "ю": "yu",
+    "я": "ya",
+}
+
+
+def slugify(text: str, max_len: int = 60) -> str:
+    """Convert arbitrary text to a URL-safe slug.
+
+    Transliterates Cyrillic, lowercases, strips everything outside [a-z0-9-],
+    collapses hyphens, trims to *max_len* characters.  Returns ``"case"`` if
+    the result would otherwise be empty.
+    """
+    result = text.lower()
+
+    # Transliterate Cyrillic
+    result = "".join(_CYRILLIC.get(ch, ch) for ch in result)
+
+    # Decompose accented characters and drop combining marks
+    result = unicodedata.normalize("NFKD", result)
+    result = "".join(ch for ch in result if not unicodedata.combining(ch))
+
+    # Replace non-alphanumeric with hyphens
+    result = re.sub(r"[^a-z0-9]+", "-", result)
+
+    # Collapse and strip leading/trailing hyphens
+    result = result.strip("-")
+
+    # Truncate at a word boundary when possible
+    if len(result) > max_len:
+        truncated = result[:max_len]
+        last_hyphen = truncated.rfind("-")
+        result = truncated[:last_hyphen] if last_hyphen > 0 else truncated
+        result = result.strip("-")
+
+    return result or "case"
+
+
+def _clean_dir_name(name: str) -> str:
+    """Remove characters that are forbidden in directory names."""
+    return _DIR_FORBIDDEN.sub("_", name).strip()
+
+
+def case_relpath(case: TestCase, existing_paths: set[str] | None = None) -> str:
+    """Compute the relative path for *case* inside the ``cases/`` directory.
+
+    Format: ``{suite_folders}/TC-{id}-{slug}.md``
+
+    Collision handling: if *existing_paths* already contains a path with the
+    same ``TC-{id}-`` prefix but a different slug, append ``-2``, ``-3``, ...
+    until the name is unique.
+    """
+    slug = slugify(case.name)
+    dir_parts = [_clean_dir_name(part) for part in case.suite_path if part]
+    base_stem = f"TC-{case.id}-{slug}"
+
+    def _build(stem: str) -> str:
+        filename = f"{stem}.md"
+        parts = [*dir_parts, filename]
+        return str(PurePosixPath(*parts)) if parts else filename
+
+    candidate = _build(base_stem)
+    if existing_paths is None:
+        return candidate
+
+    # Check for existing file with same ID but different slug
+    prefix = f"TC-{case.id}-"
+    conflicting = {
+        p for p in existing_paths if p != candidate and PurePosixPath(p).stem.startswith(prefix)
+    }
+    if not conflicting:
+        return candidate
+
+    # Generate unique suffix
+    counter = 2
+    while True:
+        stem = f"{base_stem}-{counter}"
+        candidate = _build(stem)
+        if candidate not in existing_paths:
+            return candidate
+        counter += 1
+
+
+def _render_steps(steps: list[Step], indent: int = 0) -> list[str]:
+    """Render a (possibly nested) step list as numbered Markdown lines."""
+    lines: list[str] = []
+    prefix = "    " * indent
+    for i, step in enumerate(steps, 1):
+        lines.append(f"{prefix}{i}. {step.name}")
+        if step.expected_result:
+            lines.append(f"{prefix}    - **Expected:** {step.expected_result}")
+        if step.steps:
+            lines.extend(_render_steps(step.steps, indent + 1))
+    return lines
+
+
+def serialize(case: TestCase) -> str:
+    """Render *case* as a Markdown string with YAML front matter.
+
+    The output is deterministic: same input → same bytes every time.
+    """
+    # --- Build front matter dict (fixed key order, skip None/empty) ---
+    fm: dict[str, Any] = {}
+    fm["id"] = case.id
+    fm["name"] = case.name
+
+    if case.status is not None:
+        fm["status"] = case.status
+
+    fm["automated"] = case.automated
+
+    if case.tags:
+        fm["tags"] = sorted(case.tags)
+
+    if case.custom_fields:
+        fm["custom_fields"] = {k: sorted(v) for k, v in sorted(case.custom_fields.items())}
+
+    if case.links:
+        fm["links"] = [
+            {
+                k: v
+                for k, v in {"name": lnk.name, "url": lnk.url, "type": lnk.type}.items()
+                if v is not None
+            }
+            for lnk in case.links
+        ]
+
+    if case.source_url or case.source_project:
+        source: dict[str, str] = {}
+        if case.source_url:
+            source["url"] = case.source_url
+        if case.source_project:
+            source["project"] = case.source_project
+        fm["source"] = source
+
+    front_matter = yaml.safe_dump(
+        fm,
+        sort_keys=False,
+        allow_unicode=True,
+        default_flow_style=False,
+    ).rstrip("\n")
+
+    # --- Build Markdown body ---
+    body_lines: list[str] = [f"# {case.name}", ""]
+
+    if case.description:
+        body_lines += [case.description, ""]
+
+    if case.precondition:
+        body_lines += ["## Preconditions", "", case.precondition, ""]
+
+    if case.steps:
+        body_lines.append("## Steps")
+        body_lines.append("")
+        body_lines.extend(_render_steps(case.steps))
+        body_lines.append("")
+
+    if case.expected_result:
+        body_lines += ["## Expected result", "", case.expected_result, ""]
+
+    body = "\n".join(body_lines).rstrip("\n") + "\n"
+
+    return f"---\n{front_matter}\n---\n\n{body}"

testops_mirror/sync.py

@@ -0,0 +1,64 @@
+"""Orchestrator: connector -> serialize -> plan -> commit."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+
+from testops_mirror.connectors.base import TmsConnector
+from testops_mirror.gitstore import ChangeSet, GitStore
+from testops_mirror.models import TestCase
+from testops_mirror.serializer import case_relpath, serialize
+
+logger = logging.getLogger(__name__)
+
+
+def run_sync(
+    connector: TmsConnector,
+    store: GitStore,
+    project_id: str,
+    *,
+    dry_run: bool = False,
+    on_case: Callable[[TestCase], None] | None = None,
+) -> tuple[ChangeSet, str | None]:
+    """Pull all test cases and mirror them into the git store.
+
+    Parameters
+    ----------
+    connector:
+        Any object implementing the TmsConnector protocol.
+    store:
+        Initialised GitStore pointing at the target repository.
+    project_id:
+        TMS project identifier passed to the connector.
+    dry_run:
+        If True, compute the plan but do not write files or create commits.
+    on_case:
+        Optional callback invoked for each fetched TestCase (used by CLI for
+        progress reporting).
+
+    Returns
+    -------
+    (ChangeSet, sha | None)
+        The planned change set and the commit SHA (None when dry_run or no changes).
+    """
+    desired: dict[str, str] = {}
+    seen_paths: set[str] = set()
+
+    for case in connector.iter_test_cases(project_id):
+        if on_case is not None:
+            on_case(case)
+        relpath = case_relpath(case, existing_paths=seen_paths)
+        seen_paths.add(relpath)
+        desired[relpath] = serialize(case)
+        logger.debug("Serialized %s -> %s", case.id, relpath)
+
+    logger.info("Fetched %d test cases", len(desired))
+
+    changes = store.plan(desired)
+
+    if dry_run or changes.empty:
+        return changes, None
+
+    sha = store.apply(desired, changes)
+    return changes, sha

testops_mirror-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: testops-mirror
+Version: 0.1.0
+Summary: Mirror test cases from any TMS into a Git repository as Markdown files
+Project-URL: Homepage, https://github.com/exzist-qa/testops-mirror
+Project-URL: Repository, https://github.com/exzist-qa/testops-mirror
+Project-URL: Issues, https://github.com/exzist-qa/testops-mirror/issues
+Author: testops-mirror contributors
+License: MIT License
+        
+        Copyright (c) 2026 testops-mirror contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: allure,git,mirror,test-management,testing,testops,tms
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: gitpython>=3.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# testops-mirror
+
+> Mirror test cases from any TMS into a Git repository — one file per test case, history forever.
+
+```
+mirror/
+├── Transfers/
+│   ├── Negative/
+│   │   └── TC-2301-transfer-to-blocked-account.md
+│   └── TC-2201-transfer-between-own-accounts.md
+└── Auth/
+    └── TC-1001-login-with-valid-credentials.md
+```
+
+## Why
+
+Your TMS is a single point of failure. Test cases deserve version control just like code —
+history, diff, blame, and code review through merge requests.
+
+testops-mirror pulls every test case on a schedule and commits changes to a plain Git repo.
+No vendor lock-in, no proprietary format.
+
+## Quick Start
+
+**pip:**
+
+```bash
+pip install testops-mirror
+cp .env.example .env  # fill in TESTOPS_ENDPOINT and TESTOPS_TOKEN
+testops-mirror sync --project-id 42 --repo ./mirror
+```
+
+**Docker:**
+
+```bash
+docker run --rm \
+  -e TESTOPS_ENDPOINT=https://testops.example.com \
+  -e TESTOPS_TOKEN=your-token \
+  -v $(pwd)/mirror:/mirror \
+  ghcr.io/exzist-qa/testops-mirror \
+  sync --project-id 42 --repo /mirror
+```
+
+## Example output file
+
+```markdown
+---
+id: '2301'
+name: Transfer to blocked account
+status: Ready
+automated: false
+tags: [api, negative]
+links:
+  - {name: BAN-17, url: 'https://jira.example.com/browse/BAN-17', type: issue}
+source: {url: 'https://testops.example.com/project/42/test-cases/2301', project: '42'}
+---
+
+# Transfer to blocked account
+
+## Preconditions
+
+Sender account has sufficient balance. Recipient account status is BLOCKED.
+
+## Steps
+
+1. Send `POST /transfers`
+    - **Expected:** `422 Unprocessable Entity`
+2. Check response body
+    1. Field `code` equals `ACCOUNT_BLOCKED`
+
+## Expected result
+
+API returns 422 with error code ACCOUNT_BLOCKED.
+```
+
+## Supported TMS
+
+| TMS | Status |
+|-----|--------|
+| Allure TestOps | ✅ |
+| TestIT | 🚧 planned |
+| TestRail | 🤝 contributions welcome |
+
+## Configuration
+
+| Option | Env | Default | Description |
+|--------|-----|---------|-------------|
+| `--project-id` | — | required | TMS project ID |
+| `--endpoint` | `TESTOPS_ENDPOINT` | required | Base URL of TMS |
+| `--token` | `TESTOPS_TOKEN` | required | API token |
+| `--repo` | — | `./mirror` | Local Git repo path |
+| `--suite-field` | `TESTOPS_SUITE_FIELD` | `Suite` | Custom field for folder structure |
+| `--dry-run` | — | false | Preview changes without writing |
+| `-v/--verbose` | — | false | Verbose logging |
+
+> **Note:** API endpoint paths are verified against Allure TestOps documented API.
+> If your instance uses different paths, check `<endpoint>/swagger-ui/` and
+> update the constants in `connectors/allure_testops.py`.
+
+## Roadmap
+
+- Attachments download
+- TestIT connector
+- Index file (`cases/INDEX.md`) with a table of all cases
+- Reverse import (Markdown → TMS)
+
+## License
+
+MIT

testops_mirror-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+testops_mirror/__init__.py,sha256=uKrAWK61H5tHGo_1Kn1BTKo40j_S6DR1rPFf5F8_TP0,90
+testops_mirror/cli.py,sha256=kenD3lFD9KwI8R-dfaU3HKm7rDFfiT_SUJutOJVqsLE,4922
+testops_mirror/exceptions.py,sha256=25D1RFhJChQ5ZnRRcY2R_3Oy-FBAK3AzlKmZcjU5vwY,681
+testops_mirror/gitstore.py,sha256=NcJpPH7Hkygfij7LfxhaHZgt-XKDJ3uIhQMDn9Wu4ng,5213
+testops_mirror/models.py,sha256=FMfPGFKafT_JTFVhmMWaD0c039FDs1eHb7obqyua4bg,1063
+testops_mirror/serializer.py,sha256=H5Kpy_8U3RjmCOmi5XLWOcesFiJiJKt1svaHI_ErzaU,6197
+testops_mirror/sync.py,sha256=5VV-K6NGm6ydHYT46Mdz9unqGJkqDFFXAYMlSgUW0qI,1887
+testops_mirror/connectors/__init__.py,sha256=6-ozPiilbQFvpWdLLoh_doVNAE9QMRTxK_9EII46IH8,37
+testops_mirror/connectors/allure_testops.py,sha256=iDYOGPi0CQSEufEk7Y4mVlQYjENt2vtLOhutZjXklEI,14535
+testops_mirror/connectors/base.py,sha256=FXfMaFzJxua1MVFgPpt4RkJHYjCf8K5MpuqcnctsHD0,1014
+testops_mirror-0.1.0.dist-info/METADATA,sha256=Mr_-nOAxRjvaZEizgm0xolSvOpkghvcqF7CiCJrXBf4,5421
+testops_mirror-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+testops_mirror-0.1.0.dist-info/entry_points.txt,sha256=JiPErL91CBJpsPSLZBHehfZ82pCpEPjXrvwagkVd3UA,58
+testops_mirror-0.1.0.dist-info/licenses/LICENSE,sha256=NzNVXU-PP5CoKV09KwYEV7ZEpUpbeGq159cVj6udtcQ,1084
+testops_mirror-0.1.0.dist-info/RECORD,,

testops_mirror-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

testops_mirror-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+testops-mirror = testops_mirror.cli:app

testops_mirror-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 testops-mirror contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.