unittest-monkey

unittest-monkey is a command-line monkey runner for Python's standard-library unittest framework. It collects test cases using unittest, randomly selects test cases with replacement, and runs the selected cases a specified number of times.

Every execution prints its random seed. Reuse the same target, count, and seed to reproduce the same selection sequence.

Installation

pip install .

Usage

# Discover from the current directory and run 100 random test cases.
unittest-monkey --count 100

# Discover tests under a directory.
unittest-monkey tests/ --count 100

# Load tests from one Python file.
unittest-monkey tests/test_service.py --count 50

# Run a named unittest class or method.
unittest-monkey package.test_service.TestService.test_create --count 20

# Reproduce an earlier selection sequence.
unittest-monkey tests/ --count 100 --seed 1234567890

# Do not stop after the first failure and show each result.
unittest-monkey tests/ --count 100 --continue-on-fail --verbose

Options

Discovery Behavior

Directory and no-target discovery delegate to unittest.TestLoader.discover, therefore they retain unittest's native test*.py naming pattern and import requirements. File targets are loaded directly as Python modules. Named targets use unittest's dotted-name syntax.

Reports

Each run writes the following files to --report-dir:

• report.json: machine-readable seed, summary, selection results, durations, and failure tracebacks.
• report.html: browser-readable execution report.

License

This project is licensed under the MIT License.