HypoFuzz

https://hypofuzz.com/docs/
Admin
HypoFuzz is an advanced fuzzing backend and dashboard for Hypothesis property-based tests that finds...
Tokens:13,760
Snippets:249
Trust Score:6.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install HypoFuzz

Source: https://hypofuzz.com/docs/quickstart.html

Install HypoFuzz using pip. This is a prerequisite for running HypoFuzz tests.

```bash
pip install hypofuzz

```

--------------------------------

### Configure Redis Example Database

Source: https://hypofuzz.com/docs/_sources/manual/operating.rst.txt

Configures HypoFuzz to use Redis as its example database. This is recommended for distributed systems and more complex network topologies.

```python
hypothesis.extra.redis.RedisExampleDatabase()
```

--------------------------------

### Configure Directory-Based Example Database

Source: https://hypofuzz.com/docs/_sources/manual/operating.rst.txt

Configures HypoFuzz to use a local directory as its example database. This is useful when a shared filesystem is available between the server and local development environment.

```python
hypothesis.database.DirectoryBasedExampleDatabase("/path/to/.hypothesis")
```

--------------------------------

### Start Fuzzing with Specific Processes

Source: https://hypofuzz.com/docs/manual/cli.html

Starts HypoFuzz fuzzing with the dashboard and a specified number of cores.

```bash
hypothesis fuzz -n 2
```

--------------------------------

### HypoFuzz CLI Output Example

Source: https://hypofuzz.com/docs/_sources/manual/cli.rst.txt

This snippet shows an example of the output from the 'hypothesis fuzz' command, illustrating its typical execution.

```text
HypoFuzz Dashboard

Dashboard URL: http://127.0.0.1:5000

Starting 8 fuzz workers...
Worker 1 started (PID: 12345)
Worker 2 started (PID: 12346)
Worker 3 started (PID: 12347)
Worker 4 started (PID: 12348)
Worker 5 started (PID: 12349)
Worker 6 started (PID: 12350)
Worker 7 started (PID: 12351)
Worker 8 started (PID: 12352)

All fuzz workers started successfully.
```

--------------------------------

### Start Fuzzing Without Dashboard

Source: https://hypofuzz.com/docs/manual/cli.html

Starts HypoFuzz fuzzing with a specified number of cores, but without the dashboard.

```bash
hypothesis fuzz --no-dashboard -n 4
```

--------------------------------

### Install HypoFuzz

Source: https://hypofuzz.com/docs/_sources/quickstart.rst.txt

Install HypoFuzz using pip. This command adds the 'hypothesis fuzz' sub-command to your environment.

```shell
pip install hypofuzz
```

--------------------------------

### Fuzz Specific Tests with Pytest Arguments

Source: https://hypofuzz.com/docs/manual/cli.html

Starts HypoFuzz fuzzing and passes additional arguments to pytest to filter tests. This example fuzzed only tests with 'parse' in their name.

```bash
hypothesis fuzz -- -k parse
```

--------------------------------

### Install HypoFuzz with PyTrace support

Source: https://hypofuzz.com/docs/_sources/changelog.md.txt

Install HypoFuzz with PyTrace for web-based time-travel debugging. This enables clicking a link on failing tests to debug.

```bash
pip install hypofuzz[pytrace]
```

--------------------------------

### Configure Redis Database for HypoFuzz

Source: https://hypofuzz.com/docs/_sources/manual/database.rst.txt

Register and load a Hypothesis settings profile to use a Redis database for HypoFuzz. Ensure the 'hypothesis[redis]' package is installed.

```python
from hypothesis import settings

# pip install hypothesis[redis]
from hypothesis.extra.redis import RedisExampleDatabase

db = RedisExampleDatabase(redis=...)
settings.register_profile("custom_db", database=db)
settings.load_profile("custom_db")
```

--------------------------------

### Example Test Collection with Pytest

Source: https://hypofuzz.com/docs/_sources/manual/collection.rst.txt

Demonstrates how HypoFuzz collects tests based on pytest's discovery and selection mechanisms. Arguments after 'hypothesis fuzz --' are passed directly to pytest.

```bash
hypothesis fuzz

```

```bash
hypothesis fuzz -- tests/test_a.py

```

```bash
hypothesis fuzz -- -k selector_string

```

--------------------------------

### Run HypoFuzz Dashboard Only Locally

Source: https://hypofuzz.com/docs/_sources/manual/operating.rst.txt

Launches only the dashboard, allowing fuzz workers to be stopped while still viewing the dashboard. Can be used to start the dashboard at any time.

```bash
hypothesis fuzz --dashboard-only
```

--------------------------------

### hypofuzz.detection.in_hypofuzz_run

Source: https://hypofuzz.com/docs/reference.html

`in_hypofuzz_run` returns `True` when HypoFuzz has been invoked via `hypothesis fuzz` or another entrypoint, and `False` otherwise. This function can be used to determine if HypoFuzz is currently fuzzing or about to start fuzzing, as opposed to simply being imported.

```APIDOC
## hypofuzz.detection.in_hypofuzz_run()

### Description
Returns `True` if HypoFuzz is currently running as part of a fuzzing process, `False` otherwise. Useful for conditional logic within your test suite.

### Method
Function Call

### Parameters
None

### Response
#### Success Response
- **bool**: `True` if HypoFuzz is actively fuzzing, `False` otherwise.

### Response Example
```json
{
  "example": "True"
}
```
```

--------------------------------

### Implement a Custom HypoFuzz Database

Source: https://hypofuzz.com/docs/_sources/manual/database.rst.txt

Create a custom database by inheriting from Hypothesis's ExampleDatabase and implementing fetch, save, and delete methods. This allows HypoFuzz to use a custom key-value store.

```python
from hypothesis import settings
from hypothesis.database import ExampleDatabase


class MyDatabase(ExampleDatabase):
    def fetch(self, key: bytes):
        pass

    def save(self, key: bytes, value: bytes):
        pass

    def delete(self, key: bytes, value: bytes):
        pass


db = MyDatabase()
settings.register_profile("custom_db", database=db)
settings.load_profile("custom_db")
```

--------------------------------

### Implement a Custom Hypothesis Database

Source: https://hypofuzz.com/docs/manual/database.html

Create a custom database by subclassing ExampleDatabase and implementing fetch, save, and delete methods. This allows HypoFuzz to use a custom key-value store.

```python
from hypothesis import settings
from hypothesis.database import ExampleDatabase


class MyDatabase(ExampleDatabase):
    def fetch(self, key: bytes):
        pass

    def save(self, key: bytes, value: bytes):
        pass

    def delete(self, key: bytes, value: bytes):
        pass


db = MyDatabase()
settings.register_profile("custom_db", database=db)
settings.load_profile("custom_db")

```

--------------------------------

### Hypothesis Fuzz CLI Help

Source: https://hypofuzz.com/docs/manual/cli.html

Displays the help message for the `hypothesis fuzz` command, outlining its usage, options, and how it integrates with pytest.

```bash
$ hypothesis fuzz --help
```

--------------------------------

### Run HypoFuzz Dashboard and Workers Locally

Source: https://hypofuzz.com/docs/_sources/manual/operating.rst.txt

Launches both the dashboard and fuzz workers for local development. This is the recommended command for running HypoFuzz on your laptop.

```bash
hypothesis fuzz
```

--------------------------------

### HypoFuzz Direct Dependencies

Source: https://hypofuzz.com/docs/_sources/compatibility.rst.txt

Lists the direct dependencies of HypoFuzz as defined in its pyproject.toml file. Ensure these are managed for reproducible environments.

```toml
dependencies = [
    "hypothesis>=6.80.0",
    "hypothesis-autoheal>=0.1.0",
    "hypothesis-doctestplus>=0.1.0",
    "hypothesis-jsonschema>=0.17.0",
    "hypothesis-regex>=0.2.0",
    "hypothesis-sqlalchemy>=0.1.0",
    "hypothesis-yaml>=0.1.0",
    "packaging",
    "pluggy>=1.0.0",
    "pytest>=7.0.0",
    "rich>=13.0.0",
    "sqlalchemy>=2.0.0",
    "typing_extensions",
    "yamlable>=0.2.0",
]
```

--------------------------------

### HypoFuzz Direct Dependencies

Source: https://hypofuzz.com/docs/compatibility.html

List of direct dependencies for HypoFuzz. Pinning these is recommended for reproducible environments.

```python
dependencies = [
    "black>=23.3.0",
    "hypothesis[cli,watchdog]>=6.140.2",
    "libcst>=1.0.0", # for hypothesis.extra._patching
    "psutil>=3.0.0",
    "pytest>=7.0.0",
    "starlette",
    "trio",
    "hypercorn",
]
```

--------------------------------

### Using hypothesis.event for Custom Coverage

Source: https://hypofuzz.com/docs/_sources/manual/behavior.rst.txt

This snippet demonstrates how to use `hypothesis.event` to mark specific behaviors, such as URLs with multiple domains, as custom coverage events. This helps HypoFuzz focus its efforts on these areas. Ensure `hypothesis.event` and `hypothesis.given` are imported.

```python
from hypothesis import event, given, strategies as st


@given(st.urls())
def test_parse_url(url: str):
    if len(url.split(".")) > 2:
        event("multiple_domains")

    parse_url(url)
```

--------------------------------

### Using hypothesis.event() for Custom Coverage

Source: https://hypofuzz.com/docs/manual/behavior.html

This snippet demonstrates how to use `hypothesis.event()` to mark specific behaviors, such as URLs with multiple domains, as 'virtual' branches. This helps Hypothesis focus its fuzzing efforts on these interesting cases.

```python
from hypothesis import event, given, strategies as st


@given(st.urls())
def test_parse_url(url: str):
    if len(url.split(".")) > 2:
        event("multiple_domains")

    parse_url(url)

```

--------------------------------

### Run HypoFuzz Workers Only Locally

Source: https://hypofuzz.com/docs/_sources/manual/operating.rst.txt

Launches only the fuzz workers, without the dashboard. Useful when you want to run fuzzing in the background or on a server without a UI.

```bash
hypothesis fuzz --no-dashboard
```

--------------------------------

### Skipping Tests During HypoFuzz Runs

Source: https://hypofuzz.com/docs/_sources/manual/collection.rst.txt

Shows how to use `pytest.mark.skipif` with `hypofuzz.detection.in_hypofuzz_run` to prevent a test from being fuzzed by HypoFuzz, while still being discoverable by regular pytest.

```python
import pytest
from hypothesis import given, strategies as st

from hypofuzz.detection import in_hypofuzz_run


@pytest.mark.skipif(in_hypofuzz_run())
@given(st.integers())
def test_will_not_be_fuzzed(n):
    pass

```

--------------------------------

### Check if HypoFuzz is Running

Source: https://hypofuzz.com/docs/_modules/hypofuzz/detection.html

Use this function to determine if HypoFuzz is actively fuzzing. It returns True when invoked via `hypothesis fuzz` or similar entrypoints, and False otherwise. This helps differentiate between active fuzzing and simple library import.

```python
_in_hypofuzz_run: bool = False




[docs]
def in_hypofuzz_run() -> bool:
    """
    |in_hypofuzz_run| returns ``True`` when HypoFuzz has been invoked via
    ``hypothesis fuzz`` or another entrypoint, and ``False`` otherwise. You can
    use this to check whether HypoFuzz is currently fuzzing (or about to
    start fuzzing), as opposed to just having been imported.
    """

    # this is a function to get ahead of any issues with importing
    # in_hypofuzz_run and then not receiving updates of hypofuzz setting it to a
    # different value, unlike `import hypofuzz; hypofuzz.detection.in_hypofuzz_run`.
    return _in_hypofuzz_run

```
Tokens:
Raw