Metadata-Version: 2.4
Name: unittest-monkey
Version: 0.1.0
Summary: A reproducible random test runner for Python unittest
Author-email: Enrico Yang <jackie826@163.com>
Maintainer-email: Enrico Yang <jackie826@163.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/enrico-j-yang/unittest-monkey
Project-URL: Repository, https://github.com/enrico-j-yang/unittest-monkey
Project-URL: Issues, https://github.com/enrico-j-yang/unittest-monkey/issues
Keywords: monkey-testing,random,test-runner,testing,unittest
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Testing
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tqdm<5,>=4.67
Dynamic: license-file

# 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

```bash
pip install .
```

## Usage

```bash
# 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

| Option | Description |
| --- | --- |
| `test_spec` | Optional directory, Python file, or dotted unittest name. When omitted, unittest discovers tests from the current directory. |
| `--count COUNT` | Required number of random test-case executions. |
| `--seed SEED` | Optional seed. A random 10-digit seed is generated when absent. |
| `--continue-on-fail` | Continue after a failure rather than stopping immediately. |
| `--report-dir DIR` | Report directory. Defaults to `./reports`. |
| `-v`, `--verbose` | Print each selected test and its outcome. |
| `-s`, `--no-capture` | Stream test stdout and stderr instead of capturing it. |

## 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](LICENSE).
