manta-sdk

Extensible test runner SDK for the Manta autonomous testing platform.

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

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

Quick start

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 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

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

# 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.

License

Apache 2.0 — see LICENSE.