rustest 0.7.0

Rust powered pytest-compatible runner

rustest

Rustest (pronounced like Russ-Test) is a Rust-powered test runner that aims to provide the most common pytest ergonomics with a focus on raw performance. Get ~2x faster test execution with familiar syntax and minimal setup.

📚 Full Documentation | Getting Started | User Guide | API Reference

Why rustest?

• 🚀 About 2x faster than pytest on the rustest integration test suite
• ✅ Familiar @fixture, @parametrize, @skip, and @mark decorators
• 🔄 Built-in async support with @mark.asyncio (like pytest-asyncio)
• 🔍 Automatic test discovery (test_*.py and *_test.py files)
• 📝 Built-in markdown code block testing (like pytest-codeblocks, but faster)
• 🎯 Simple, clean API—if you know pytest, you already know rustest
• 🧮 Built-in approx() helper for tolerant numeric comparisons
• 🪤 raises() context manager for precise exception assertions
• 📦 Easy installation with pip or uv
• ⚡ Low-overhead execution keeps small suites feeling instant

Performance

Rustest is designed for speed. Our latest benchmarks on the rustest integration suite (~200 tests) show a consistent 2.1x wall-clock speedup over pytest:

Test Runner	Wall Clock	Speedup	Command
pytest	1.33–1.59s	1.0x (baseline)	pytest tests/ examples/tests/ -q
rustest	0.69–0.70s	~2.1x faster	python -m rustest tests/ examples/tests/

Large Parametrized Stress Test

With 10,000 parametrized invocations:

Test Runner	Avg. Wall Clock	Speedup	Command
pytest	9.72s	1.0x	pytest benchmarks/test_large_parametrize.py -q
rustest	0.41s	~24x faster	python -m rustest benchmarks/test_large_parametrize.py

📊 View Detailed Performance Analysis →

Installation

Rustest supports Python 3.10 through 3.14.

# Using pip
pip install rustest

# Using uv
uv add rustest

📖 Installation Guide →

Quick Start

1. Write Your Tests

Create a file test_math.py:

from rustest import fixture, parametrize, mark, approx, raises
import asyncio

@fixture
def numbers() -> list[int]:
    return [1, 2, 3, 4, 5]

def test_sum(numbers: list[int]) -> None:
    assert sum(numbers) == approx(15)

@parametrize("value,expected", [(2, 4), (3, 9), (4, 16)])
def test_square(value: int, expected: int) -> None:
    assert value ** 2 == expected

@mark.slow
def test_expensive_operation() -> None:
    result = sum(range(1000000))
    assert result > 0

@mark.asyncio
async def test_async_operation() -> None:
    # Example async operation
    await asyncio.sleep(0.001)
    result = 42
    assert result == 42

def test_division_by_zero() -> None:
    with raises(ZeroDivisionError, match="division by zero"):
        1 / 0

2. Run Your Tests

# Run all tests
rustest

# Run specific tests
rustest tests/

# Filter by test name pattern
rustest -k "test_sum"

# Filter by marks
rustest -m "slow"                    # Run only slow tests
rustest -m "not slow"                # Skip slow tests
rustest -m "slow and integration"    # Run tests with both marks

# Rerun only failed tests
rustest --lf                         # Last failed only
rustest --ff                         # Failed first, then all others

# Exit on first failure
rustest -x                           # Fail fast

# Combine options
rustest --ff -x                      # Run failed tests first, stop on first failure

# Show output during execution
rustest --no-capture

📖 Full Quick Start Guide →

Documentation

📚 Full Documentation

Getting Started

• Installation
• Quick Start

User Guide

• Writing Tests
• Fixtures
• Parametrization
• Marks & Skipping
• Test Classes
• Assertion Helpers
• Markdown Testing
• CLI Usage
• Python API

API Reference

• API Overview
• Decorators
• Test Execution
• Reporting
• Assertion Utilities

Advanced Topics

• Performance
• Comparison with pytest
• Development Guide

Feature Comparison with pytest

Rustest implements the 20% of pytest features that cover 80% of use cases, with a focus on raw speed and simplicity.

📋 View Full Feature Comparison →

✅ Supported: Fixtures, parametrization, marks, test classes, conftest.py, markdown testing 🚧 Planned: Parallel execution, mark filtering, JUnit XML output ❌ Not Planned: Plugins, hooks, custom collectors (keeps rustest simple)

Contributing

We welcome contributions! See the Development Guide for setup instructions.

Quick reference:

# Setup
git clone https://github.com/Apex-Engineers-Inc/rustest.git
cd rustest
uv sync --all-extras
uv run maturin develop

# Run tests
uv run poe pytests  # Python tests
cargo test          # Rust tests

# Format and lint
uv run pre-commit install  # One-time setup
git commit -m "message"    # Pre-commit hooks run automatically

License

rustest is distributed under the terms of the MIT license. See LICENSE.