Metadata-Version: 2.1
Name: utfuzz
Version: 0.1.14
Summary: 
Author: Vyacheslav Tamarin
Author-email: tamarin.vs@ya.ru
Requires-Python: >=3.9,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: install-jdk (>=1.1.0,<2.0.0)
Requires-Dist: tqdm (>=4.66.1,<5.0.0)
Description-Content-Type: text/markdown

# utfuzz

`utfuzz` is a Python fuzzing engine, generating ready-to-use unit tests for both error and regression suites.

## Prerequisites

`utfuzz` supports Python 3.8–3.11.

`utfuzz` depends on Java 17 and newer. If you do not have Java installed, `utfuzz` will install it, or your can do it 
manually using these instructions:

* [Linux](https://docs.oracle.com/en/java/javase/17/install/installation-jdk-linux-platforms.html)

* [Windows](https://docs.oracle.com/en/java/javase/17/install/installation-jdk-microsoft-windows-platforms.html)

* [macOS](https://docs.oracle.com/en/java/javase/17/install/installation-jdk-macos.html)

## Installation

* Install from archive:
   1. Download [utfuzz.tar.gz](https://gitlab.com/tamarinvs19/utfuzz/-/raw/master/utfuzz_build/utfuzz.tar.gz?inline=false)
   2. Run:
   ```shell
   python -m pip install utfuzz.tar.gz
   ```

* Install from GitLab repository:
    ```shell
    python -m pip install git+https://gitlab.com/tamarinvs19/utfuzz
    ```
  
* Install from source code:
    ```shell
    git clone https://gitlab.com/tamarinvs19/utfuzz
    cd utfuzz
    python -m pip install ./
    ```
   
## Usage

You can run `utfuzz` in one of three modes:
* dialogue mode (default)
* config file mode
* CLI arguments mode

Upon each test generation, settings are saved to the `utfuzz_config.json` file.

### Generate tests in a dialogue mode
By default, `utfuzz` runs in a dialogue mode. You can use prompts and configure test generation, or stick to default options:
```shell
python -m utfuzz
```
or
```shell
utfuzz
```
The resulting tests appear in the autogenerated `utfuzz_tests` folder by default.

### Generate tests using CLI options
Turn off the dialogue mode with `–-skip-dialog` and specify the necessary options, for example:
```shell
python -m utfuzz –-skip-dialog -o /mnt/c/Users/username/uftests
```

### Generate tests using a configuration file

Edit the `utfuzz_config.json` file and enable the `--use-config-file` option:
```shell
python -m utfuzz --use-config-file
```

### Run tests

Run the generated tests as the usual `unittest` ones.

## Options

```shell
usage: utfuzz [-h] [--skip-dialog] [--use-config-file] [--generate-only-error-suite] 
              [-j JAVA] [-t TIMEOUT] [-p PROJECT_DIR] [-o OUTPUT_DIR] [--sys-paths [SYS_PATHS ...]]
              [--analyze-targets [ANALYZE_TARGETS ...]] [--requirements-file REQUIREMENTS_FILE] [--debug]

utfuzz is a Python fuzzing engine, generating ready-to-use unit tests for both error and regression suites.

options:
  -h, --help            show this help message and exit
  --skip-dialog         do not ask for options interactively
  --use-config-file     use config file from current directory
  --generate-only-error-suite
                        generate only error suite
  -j JAVA, --java JAVA  path to Java executable file or JAVA_HOME
  -t TIMEOUT, --timeout TIMEOUT
                        timeout in seconds for generating tests per class or group of top-level functions from one file
  -p PROJECT_DIR, --project-dir PROJECT_DIR
                        root directory with code under test (used for imports and dependency resolving)
  -o OUTPUT_DIR, --output-dir OUTPUT_DIR
                        directory for generated tests
  --sys-paths [SYS_PATHS ...]
                        additional path to find imports (will be added to `sys.path`; default = project directory)
  --analyze-targets [ANALYZE_TARGETS ...]
                        list of files or directories to test; empty value field means <<test all>>
  --requirements-file REQUIREMENTS_FILE
                        path to requirements.txt
  --debug               use debug mode
```

`utfuzz` has the [UnitTestBot fuzzing engine](https://github.com/UnitTestBot/UTBotJava/tree/main/utbot-cli-python) inside. To change the version of the UnitTestBot source, 
replace it with the necessary `utfuzz/utbot-cli-python.jar` file (do not change the file name).
Upon replacing, remember to reinstall this module.

For more information, see the [UnitTestBot website](utbot.org/python) and the related [GitHub repository](github.com/UnitTestBot/UTBotJava).

