minigun-soren-n 2.5.0

A library for property-based testing of Python programs

Minigun

A QuickCheck-like library for property-based unit-testing of Python programs.

Minigun is inspired by QCheck, which in turn was inspired by QuickCheck. Both are libraries that provide implementations for performing property-based unit-testing; for OCaml and Haskell respectively.

If you would like a bit of motivation as to why you should use a QuickCheck-like system for testing your project, then I would recommend that you watch:

• John Hughes - Testing the Hard Stuff and Staying Sane
• John Hughes - Certifying your car with Erlang

If you wish to learn more about the subject, I can recommend Jan Midtgaard's lecture materials; it is OCaml based but translates easily to other QuickCheck-like libraries for other languages.

Install

Minigun is currently only supported for Python >=3.12. It is distributed with pip and can be installed with the following example command:

pip install minigun-soren-n

Quick Start

Using the CLI (Recommended)

Create a test module in tests/ directory:

# tests/my_tests.py
from minigun import prop, check, conj

@prop("reversing a list twice gives the original")
def test_reverse(lst: list[int]):
    return list(reversed(list(reversed(lst)))) == lst

@prop("list length distributes over concatenation")
def test_length(xs: list[int], ys: list[int]):
    return len(xs + ys) == len(xs) + len(ys)

def test():
    return check(conj(test_reverse, test_length))

Run your tests with time budget:

minigun --time-budget 30

Using as a Library

from minigun import prop, check

@prop("reversing a list twice gives the original")
def test_reverse(lst: list[int]):
    return list(reversed(list(reversed(lst)))) == lst

if __name__ == "__main__":
    success = check(test_reverse)
    exit(0 if success else 1)

Run directly:

python my_tests.py

Documentation

Full documentation and tutorials at Read The Docs.

Usage Guide

CLI Test Runner

# Run all tests in ./tests directory
minigun --time-budget 30

# Run tests from a different directory
minigun --time-budget 60 --test-dir my_tests

# Run specific test modules
minigun --time-budget 45 --modules my_tests other_tests

# List available test modules
minigun --list-modules

# Quiet mode (for CI/CD)
minigun --time-budget 60 --quiet

# JSON output (for automation)
minigun --time-budget 30 --json

The CLI discovers Python files in the test directory that contain a test() function.

Advanced: Manual Orchestrator Usage

For programmatic control, use the orchestrator directly:

# my_test_runner.py
from minigun.orchestrator import TestOrchestrator, OrchestrationConfig, TestModule
from minigun.specify import prop, check

@prop("your property")
def my_property(x: int):
    return x + 0 == x

def run_my_property():
    return check(my_property)

if __name__ == "__main__":
    config = OrchestrationConfig(
        time_budget=30.0,
        verbose=True
    )

    modules = [TestModule("my_tests", run_my_property)]
    orchestrator = TestOrchestrator(config)
    success = orchestrator.execute_tests(modules)

    exit(0 if success else 1)

Writing Tests

Basic Properties

from minigun import prop

@prop("addition is commutative")
def test_add_commute(x: int, y: int):
    return x + y == y + x

Custom Domains

from minigun import prop, context, domain as d

@context(d.int_range(1, 100), d.int_range(1, 100))
@prop("division reverses multiplication")
def test_div(x: int, y: int):
    return (x * y) // y == x

Combining Properties

from minigun import prop, check, conj

@prop("property 1")
def test_1(x: int):
    return x + 0 == x

@prop("property 2")
def test_2(x: int):
    return x * 1 == x

# Check both together
success = check(conj(test_1, test_2))

FAQ

Q: What's a good time budget?

A: Start with 30-60 seconds for quick feedback. Use 2-5 minutes for thorough testing in CI/CD.

Q: How do I test larger input spaces?

A: Increase the time budget. The system automatically runs more test attempts when given more time.

Q: Can I customize test generation?

A: Yes, use the @context decorator with domain specifications. See documentation for details.

Real-World Usage

The following projects use Minigun for testing:

• Minigun (self-testing)
• Tickle (parsing library)

If you have used Minigun for testing a public project, please file an issue with a link to add it to this list.