testudos
A testing harness for Python packages using uv's isolated environments.
Overview
Testudos simplifies running your Python package's test suite across multiple Python versions. It automatically determines which versions to test based on:
- Currently supported Python versions - Fetched from endoflife.date
- Your package's compatibility - Parsed from
requires-pythoninpyproject.toml
Only versions that are both still supported by Python and compatible with your package are tested.
Quick Start
# Install testudos
uv tool install testudos
# Run tests on all compatible Python versions
testudos run
# Run tests in parallel for speed
testudos run --parallel
# See which versions would be tested
testudos versions
# Preview commands without running (dry-run)
testudos run --dry-run
Installation
# Using uv (recommended)
uv tool install testudos
# Using pip
pip install testudos
Requirements
- Python 3.10+
- uv - Fast Python package installer
Usage
Running Tests
# Run tests on all compatible versions (sequential)
testudos run
# Run tests in parallel
testudos run --parallel
testudos run -P
# Limit parallel jobs
testudos run --parallel --jobs 4
testudos run -P -j 4
# Test specific Python versions
testudos run --python 3.11 --python 3.12
testudos run -p 3.11 -p 3.12
# Fail fast (stop on first failure) - default in sequential mode
testudos run --fail-fast
testudos run -f
# Continue on failures
testudos run --no-fail-fast
testudos run -F
# Verbose output
testudos run --verbose
testudos run -v
# Dry run - show what would be executed
testudos run --dry-run
testudos run -n
# Test a specific project directory
testudos run ./path/to/project
# Control colored output
testudos run --color # Force colored output
testudos run --no-color # Disable colors (for CI, piping, etc.)
Note: Testudos respects the
NO_COLORandFORCE_COLORenvironment variables as an alternative to CLI flags.
Test Coverage
Testudos can collect and aggregate test coverage data across all Python versions:
# Run tests with coverage collection
testudos run --coverage
# Run with coverage and generate HTML report
testudos run --coverage --coverage-report html
# Run with coverage threshold (fail if below 80%)
testudos run --coverage --coverage-fail-under 80
# Multiple report formats
testudos run --coverage --coverage-report html --coverage-report xml
# Available report formats: term, term-missing, html, xml, json, lcov
Coverage Commands
Manage coverage data manually:
# Combine coverage from multiple Python versions
testudos coverage combine
# Generate coverage report
testudos coverage report
testudos coverage report --format html
# Clean coverage data
testudos coverage clean
Installing Coverage Support
Coverage collection requires the coverage package:
# Install testudos with coverage support
pip install testudos[coverage]
# Or add coverage to your project dependencies
uv add coverage
Viewing Versions
# Show versions that would be tested
testudos versions
# Show versions for a specific project
testudos versions ./path/to/project
Configuration
Configure testudos in your pyproject.toml:
[project]
requires-python = ">=3.11"
[tool.testudos]
# Optional: Override auto-detected Python versions
python-versions = ["3.11", "3.12", "3.13"]
# Test command to run (default: "pytest")
test-command = "pytest"
# Additional arguments for test command
test-args = ["-v", "--tb=short"]
# Run tests in parallel by default
parallel = false
# Maximum parallel jobs (default: number of versions)
max-jobs = 4
# Coverage options
coverage = true # Enable coverage collection
coverage-combine = true # Combine coverage from all versions
coverage-report = ["html", "xml"] # Report formats to generate
coverage-fail-under = 80 # Fail if coverage below threshold
Configuration Validation
Testudos validates your configuration on load and will:
- Error on invalid types or values
- Warn on unknown configuration keys
How It Works
Testudos uses uv run --isolated to create ephemeral, isolated environments for each Python version. This ensures:
- Clean test environments - No leftover state between versions
- Fast execution - uv's caching makes environment creation nearly instant
- No version conflicts - Each version is completely isolated
Example Command
For Python 3.11, testudos runs:
uv run --isolated --python=3.11 --with pytest pytest
The --with pytest flag ensures pytest runs in the same isolated environment as your project, with full access to all your project's dependencies.
Features
- Automatic version detection: Fetches supported versions from endoflife.date API
- Smart caching: 24-hour TTL cache for API responses with offline fallback
- Parallel execution: Run tests concurrently with live progress display
- Coverage aggregation: Collect and combine coverage data across all Python versions
- Dry-run mode: Preview commands without execution
- Configuration validation: Schema validation for
[tool.testudos]settings - Input validation: Safe command construction with validation
Documentation
- Architecture - Detailed design and component overview
- Implementation Roadmap - Development phases and tasks
- Future Enhancements - Planned features and issue descriptions
Development
# Clone the repository
git clone https://github.com/martinristovski/testudos.git
cd testudos
# Install dependencies
uv sync
# Run tests
uv run pytest
# Run testudos on itself
uv run testudos run
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for testudos 0.20.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| testudos-0.20.0.tar.gz | 122.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| testudos-0.20.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 168.8 kB
Release files / testudos-0.20.0.tar.gz
| Download URL | testudos-0.20.0.tar.gz |
|---|---|
| Size | 122.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4a9fefeab5756e4f92062a8d06da32f27a47b595fb38d3af2ca79c7fb390c74e
|
|
BLAKE2b-256 checksum How to use checksums |
92b7dbbdb96ff34b5b0cc8df0cbb97d3f11b547b04120a2846310b10064cc191
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logRelease files / testudos-0.20.0-py3-none-any.whl
| Download URL | testudos-0.20.0-py3-none-any.whl |
|---|---|
| Size | 46.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
494dcc33629ca3900ba457d128e2ea44995a98e4afe1a3104c71d269aa1d27d2
|
|
BLAKE2b-256 checksum How to use checksums |
e210ff7db22976abadd0d7572a7578eeb88b36861d79a82aee4ac22902f4f318
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency log
