Metadata-Version: 2.4
Name: manta-sdk
Version: 0.3.6
Summary: Manta Test SDK — extensible test runner framework for the Manta platform
Project-URL: Homepage, https://github.com/EranYonai/manta-sdk
Project-URL: Repository, https://github.com/EranYonai/manta-sdk
License: Apache-2.0
Keywords: automation,ci,manta,sdk,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: allure-pytest>=2.13.5
Requires-Dist: httpx>=0.28.0
Requires-Dist: pydantic>=2.10.0
Requires-Dist: pytest>=8.3.0
Requires-Dist: structlog>=24.4.0
Description-Content-Type: text/markdown

# manta-sdk

> Extensible test runner SDK for the [Manta](https://github.com/EranYonai/manta) autonomous testing platform.

[![PyPI version](https://img.shields.io/pypi/v/manta-sdk)](https://pypi.org/project/manta-sdk/)
[![Python 3.12+](https://img.shields.io/pypi/pyversions/manta-sdk)](https://pypi.org/project/manta-sdk/)
[![License: Apache 2.0](https://img.shields.io/pypi/l/manta-sdk)](https://github.com/EranYonai/manta-sdk/blob/main/LICENSE)
[![CI](https://github.com/EranYonai/manta-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/EranYonai/manta-sdk/actions/workflows/ci.yml)

**manta-sdk** is the test runner framework that powers Manta's elastic execution
engine. It provides a stage-based lifecycle (`setup` → `execute` → `teardown`)
with built-in Allure reporting, SUT asset management, and result callbacks.

The Manta AI pipeline generates runners as `BaseRunner` subclasses, but teams
can also write custom runners by hand for specialised test workflows.

## Installation

```bash
pip install manta-sdk
# or with uv
uv add manta-sdk
```

## Quick start

```python
from manta_sdk import BaseRunner, RunContext, RunResult, RunStatus

class MyPytestRunner(BaseRunner):

    async def setup(self, ctx: RunContext) -> None:
        """Prepare the test environment — install deps, download assets."""
        ...

    async def execute(self, ctx: RunContext) -> RunResult:
        """Run tests and return a structured result."""
        ...
        return RunResult(run_id=ctx.run_id, status=RunStatus.PASSED, ...)

    async def teardown(self, ctx: RunContext, result: RunResult) -> None:
        """Upload Allure reports, clean up temp files."""
        ...
```

### What happens at runtime

1. The execution engine provisions a runner container with `manta-sdk` pre-installed
2. `run_runner.py` downloads your generated runner wheel, installs it, and calls `BaseRunner.run()`
3. The SDK handles SUT download, pytest execution, Allure report collection, and result callbacks
4. Results flow back to the platform for analytics and (optionally) the AI repair loop

## Commit conventions

This repo uses [Conventional Commits](https://www.conventionalcommits.org/) to
drive **automated patch releases**. Every push to `main` is scanned for
releasable commit types. If found, the pipeline bumps the patch version,
tags, and publishes to PyPI.

### Commit format

```
<type>(<optional scope>): <description>

[optional body]

[optional footer(s)]
```

### Allowed types and version bumps

| Type | Purpose | Auto version bump |
|------|---------|-------------------|
| `feat` | New feature or capability | **patch** (0.3.2 → 0.3.3) |
| `fix` | Bug fix | **patch** (0.3.2 → 0.3.3) |
| `perf` | Performance improvement | **patch** (0.3.2 → 0.3.3) |
| `refactor` | Code restructuring (no behavior change) | none |
| `docs` | Documentation only | none |
| `test` | Adding or updating tests | none |
| `chore` | Maintenance (deps, CI config, tooling) | none |
| `ci` | CI/CD pipeline changes | none |
| `build` | Build system or dependency changes | none |

> **Minor and major bumps are manual.** During early development, the automated
> pipeline only bumps the patch version (Z in X.Y.Z). To bump minor or major,
> edit the `version` field in `pyproject.toml` directly, commit, and push.

### Examples

```bash
# New feature → auto patch bump (0.3.2 → 0.3.3)
git commit -m "feat(runner): add retry logic to BaseRunner.execute"

# Bug fix → auto patch bump (0.3.3 → 0.3.4)
git commit -m "fix(models): handle None values in RunResult.to_dict"

# Docs update → no version bump, no release
git commit -m "docs: add usage examples to README"

# Refactor → no version bump, no release
git commit -m "refactor(plugin): simplify MantaPlugin fixture registration"

# Minor bump → manual edit to pyproject.toml
# 1. Change version = "0.4.0" in pyproject.toml
# 2. git commit -m "chore(release): bump to 0.4.0"
# 3. git tag v0.4.0 && git push origin main --tags
```

### How the release pipeline works

```
push to main
  → release.yml (bump job): scans commits since last v* tag for feat/fix/perf
  → if found: bumps Z in X.Y.Z, commits, tags (v0.3.5)
  → release.yml (publish job): checks out tag → tests → builds wheel → PyPI → GitHub Release
```

If no `feat`, `fix`, or `perf` commits are found since the last tag, nothing
happens — no version bump, no release.

Minor (Y) and major (X) bumps are always manual — edit `version` in
`pyproject.toml`, commit, tag, and push. Manual tags trigger `publish-sdk.yml`.

### Setup (for maintainers)

The `PYPI_TOKEN` secret must be set in the repo's GitHub Actions settings for
PyPI publishing to work. Use a project-scoped token from
[pypi.org](https://pypi.org/manage/account/).

## License

Apache 2.0 — see [LICENSE](LICENSE).
