rut

rut - Run Unit Tests

rut is a modern and fully-featured test runner for Python's unittest framework, with simplicity as a core design goal.

Sponsored by asserto.ai

Features

• Blazingly Fast (to type): rut is only 3 characters.
• Built-in support for async code.
• Test discovery with keyword-based filtering.
• Topological test ordering by import dependencies.
• Incremental testing: only run tests affected by changes.
• Code coverage support.

Why use rut?

For the unittest User: A Modern Upgrade

Are you a fan of the stability and explicitness of unittest, but wish you had a better runner experience? rut is your drop-in upgrade.

• Zero-Config Discovery: Just run rut. No more writing if __name__ == '__main__': boilerplate.
• First-Class asyncio Support: rut automatically detects and runs async tests correctly. No more asyncio.run() wrappers.
• Powerful Filtering: Run exactly the tests you want with simple keyword filtering (-k "transfer").
• Integrated Coverage: Get a full coverage report with a single flag (--cov).

For the pytest User: Simplicity and Power, Reunited

Do you appreciate the power of modern test runners, but find yourself wrestling with the complexity and "magic" of third-party frameworks? rut offers a compelling alternative, embracing the explicitness of the standard library.

• No Magic, Just Python: rut is built directly on unittest. There are no hidden hooks, complex fixture systems, or assertion rewriting. Your tests are plain, debuggable Python.
• Familiar, Powerful Features: Get the features you rely on, like keyword filtering (-k), failing fast (-x), and seamless asyncio support, without the overhead of a large framework.
• A Leaner Dependency Tree: rut is a single, focused tool, not a sprawling ecosystem. Keep your project's dependencies clean and understandable.

Installation

Add rut as a development dependency to your project:

uv add --dev rut

Usage

rut [options] [path]

Example

To run all tests in the tests/ directory that have the word "transfer" in their name, you would run:

rut -k "transfer"

Options

Option	Short	Description
--keyword	-k	Only run tests that match the given keyword.
--exitfirst	-x	Exit on the first failure.
--capture	-s	Disable all output capturing.
--alpha	-a	Sort tests alphabetically instead of by import dependencies.
--changed	-c	Only run tests affected by file changes since last successful run.
--dry-run		List tests in execution order without running them.
--verbose	-v	Show test names instead of dots.
--debug		Show internal debug information (dependency graph, changed modules).
--cov		Run with code coverage.
--version	-V	Show version and exit.
--test-base-dir		The base directory for conftest.py discovery.
--no-color		Disable color output.

Positional Arguments

Argument	Description	Default
path	Path to test file or directory to run. Does not affect project config.	discover all in test_dir

Configuration

rut can be configured via the [tool.rut] section in your pyproject.toml file.

rut looks for pyproject.toml in the current directory. If cwd is tests/, it also checks the parent directory and changes to it if found.

Without pyproject.toml, rut runs in ad-hoc mode with test_dir=. and source_dirs=["."].

source_dirs

Specifies the source directories for coverage reporting, incremental testing (--changed), and import dependency analysis. If not configured, the default is ["src", "tests"]. Validated only when --cov or --changed is used.

[tool.rut]
source_dirs = ["finance", "tests"]

warning_filters

To add custom warning filters, use the warning_filters key. The format for each filter is a string that follows the warnings.filterwarnings format: action:message:category:module.

[tool.rut]
warning_filters = [
    "error::UserWarning:pydantic",
]

test_base_dir

The base directory for test discovery and conftest.py lookup. Default: "tests".

[tool.rut]
test_base_dir = "my_tests"

Writing Tests

Basic Tests

For standard, synchronous tests, you can use the standard unittest.TestCase.

import unittest