Testosterone

One YAML file to run your whole test cycle (pytest, Behave, BehaveX or any JUnit-writing command), then see what changed since the last run.

Live demo: https://taltal-beep.github.io/testosterone/

Run detail (failed fake-api run)	Compare (two fake-api runs)
Cycles	Dashboard on a phone

What you're looking at: Testosterone testing itself (its own test suite) and fake-api, a small app whose routes fail on purpose. CI runs both cycles and publishes the real results as a read-only static site.

Why

Most projects run several test frameworks, each with its own command, report format and CI glue. Testosterone puts them in one testosterone.yaml as a cycle of stages, runs it, records every run, and answers the question you actually have after a red build: what changed? You get run-to-run deltas, a test pyramid, and an optional AI summary of the failures. The same engine runs the cycle whether you start it from the CLI, from CI, or from the web UI.

How it compares. Allure and ReportPortal display the results of a run someone else started. Testosterone starts the run: it orchestrates the stages, keeps the history and diffs runs against each other, then hands results to Allure, ReportPortal, Extent or TestBeats as reporters. It sits upstream of those tools rather than replacing them.

What ships: the testo CLI (--ci streams NDJSON events, exit codes 0–4), a FastAPI backend (testo_api, /api/v1, live runs over server-sent events), a React frontend (frontend/), and GitHub Action / GitLab CI wrappers around testo run --ci. See ARCHITECTURE.md for how the pieces fit.

Quickstart

Install the CLI from PyPI and point it at your own tests:

pip install testo-core            # the `testo` CLI; add [api] for the REST API, [db] for Postgres
testo config init                 # writes a starter testosterone.yaml; edit its stages
testo run --cycle smoke-test      # run a cycle from it

Or work from a checkout of this repository, which ships sample cycles:

git clone https://github.com/taltal-beep/testosterone.git
cd testosterone
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

testo run --cycle sample-pytests      # run a cycle from testosterone.yaml
testo report --cycle sample-pytests   # build the Allure report for it

Adding Testosterone to your own project with an AI coding assistant? Paste one of the Setup Prompts.

Runs are stored in SQLite by default (database.url in testosterone.yaml, or DATABASE_URL). Postgres and MySQL work too; docker compose up -d postgres starts one.

UI

testo-api                              # FastAPI on http://127.0.0.1:8000
npm --prefix frontend install
npm --prefix frontend run dev          # React on http://localhost:5173

Pages: Dashboard, Cycles (run any cycle and watch its stages live), Runs and Run Detail (reports, test pyramid, AI summary), Compare (delta between two runs), Quick Run (run one framework against a repo without defining a cycle) and AI settings.

Defining cycles

version: 1
defaults:
  target_repo: .
  artifacts_root: artifacts
  timeout_s: 600
reporters:
  - type: allure
cycles:
  smoke:
    description: Unit tests, then BDD flows.
    trigger:                     # optional: skip unless these paths changed
      paths: ["src/**", "tests/**"]
    stages:
      - name: unit
        equipment: pytest
        args: [-q, tests/unit]
      - name: flows
        equipment: behave
        args: [features/smoke.feature]   # always target Behave features explicitly
      - name: web
        equipment: command               # any runner; results come from JUnit XML
        args: [npx, jest, --ci]
        junit_xml: ["reports/junit/*.xml"]

testo config validate checks the file; testo init writes one interactively. The full schema and every flag are in Command Reference.

CLI

Exit codes: 0 success (or trigger-skipped), 1 tests failed, 2 invalid input, 3 infrastructure failure, 4 internal error. Details: Troubleshooting and Error Codes.

API

Interactive docs at http://127.0.0.1:8000/docs while testo-api runs.

CI

GitHub Actions:

- uses: taltal-beep/testosterone/integrations/github-action@v1
  with:
    cycle: smoke          # optional: config-path, ci-mode, persist, python-version

GitLab CI (a GitLab mirror of this repo is coming; until then, include the template straight from GitHub, or copy ci/gitlab/testo.gitlab-ci.yml):

include:
  - remote: "https://raw.githubusercontent.com/taltal-beep/testosterone/v1/ci/gitlab/testo.gitlab-ci.yml"
variables:
  TESTO_CYCLE: "smoke"

Both run testo run --ci, keep the NDJSON event stream, and expose the final plan_finished event (exit code, per-stage results). Run records written in CI carry the provider, pipeline, job, commit and branch. Inputs and outputs: integrations/github-action/README.md.

Optional integrations

• Metrics push: after each run, test KPIs go to InfluxDB when INFLUXDB_URL, INFLUXDB_TOKEN, INFLUXDB_ORG and INFLUXDB_BUCKET are set, and to a Prometheus Pushgateway when PROMETHEUS_PUSHGATEWAY_URL is set (PROMETHEUS_JOB_NAME defaults to testo). Pushes are best-effort and never change the run result.
• Reporters: allure, extent, reportportal, testbeats under reporters:.
• AI failure summaries: opt in on the AI settings page with an OpenAI or Anthropic key. Failed runs store their failing cases, first traceback and log tail (redacted), which is what the summary is built from.

Development

pip install -e ".[dev]"
pre-commit install
ruff check .
ruff format --check .
mypy testo_core testo_api
pytest -q -m "tier_fast and not quarantined" --no-cov
npm --prefix frontend run typecheck
npm --prefix frontend test

ruff check, ruff format --check and mypy testo_core testo_api are all blocking in CI (.github/workflows/ci.yml's format job), as are the frontend typecheck and tests.

See CONTRIBUTING.md for the full checklist. Start with ARCHITECTURE.md for the design; docs/ holds internal design notes and ADRs (an Obsidian vault, so some links only resolve inside Obsidian).

History

The project started as UQO ("Unified Quality Orchestrator") and was renamed to Testosterone (the uqo command and UQO_* variables became testo and TESTO_*). v1.1 replaced the Streamlit UI with the React frontend and dropped the Docker-based headless runner (stages now run as host subprocesses). Full details in CHANGELOG.md.