Hypothesis

https://hypothesis.readthedocs.io/en/latest/
Admin
Hypothesis is a property-based testing library for Python that helps developers write tests which...
Tokens:577,570
Snippets:5,275
Trust Score:8.3
Update:1 week ago
Show doc for...
Tokens:
Raw
### Basic @example usage

Source: https://hypothesis.readthedocs.io/en/latest/reference/api.html

Shows how to add explicit examples that Hypothesis always tries before random inputs. Explicit examples run in the Phase.explicit phase, do not count towards settings.max_examples, and do not shrink. If an explicit example fails, Hypothesis stops and reports the failure without generating random inputs.

```python
@example("Hello world")
@example("some string with special significance")
@given(st.text())
def test_strings(s):
    pass

```

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

### example.xfail usage example

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/core.html

Shows how to use @example(...).xfail() to mark an explicit example as expected to fail. The example demonstrates that only the explicit example is treated as xfailing, while generated examples from the strategy are not.

```python
@example(x=1, y=0).xfail(raises=ZeroDivisionError)
@given(x=st.just(1), y=st.integers())  # Missing `.filter(bool)`!
def test_fraction(x, y):
    # This test will try the explicit example and see it fail as
    # expected, then go on to generate more examples from the
    # strategy.  If we happen to generate y=0, the test will fail
    # because only the explicit example is treated as xfailing.
    x / y
```

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

### Install coverage subprocess .pth file

Source: https://hypothesis.readthedocs.io/en/latest/_sources/extensions.rst.txt

Creates a .pth file in site-packages to start coverage early for all new processes. Requires coverage to be installed and configuration in .coveragerc.

```bash
echo "import coverage; coverage.process_startup()" > \
    "$(python -c 'import sysconfig; print(sysconfig.get_path("purelib"))')/coverage_subprocess.pth"
```

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

### Start listening for file changes using watchdog

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/database.html

Starts a watchdog observer to monitor file changes. Requires the watchdog library; otherwise warns with a pip install command. Defines a handler that updates a hash-to-key mapping on file creation events.

```python
    def _start_listening(self) -> None:
        try:
            from watchdog.events import (
                DirCreatedEvent,
                DirDeletedEvent,
                DirMovedEvent,
                FileCreatedEvent,
                FileDeletedEvent,
                FileMovedEvent,
                FileSystemEventHandler,
            )
            from watchdog.observers import Observer
        except ImportError:
            warnings.warn(
                f"listening for changes in a {self.__class__.__name__} "
                "requires the watchdog library. To install, run "
                "`pip install hypothesis[watchdog]`",
                HypothesisWarning,
                stacklevel=4,
            )
            return

        hash_to_key = {_hash(key): key for key in self.fetch(self._metakeys_name)}
        _metakeys_hash = self._metakeys_hash
        _broadcast_change = self._broadcast_change

        class Handler(
            FileSystemEventHandler
        ):  # pragma: no cover # skipped in test_database.py for now
            def on_created(_self, event: FileCreatedEvent | DirCreatedEvent) -> None:
                # we only registered for the file creation event
                assert not isinstance(event, DirCreatedEvent)
                # watchdog events are only bytes if we passed a byte path to
                # .schedule
                assert isinstance(event.src_path, str)

                value_path = Path(event.src_path)
                # the parent dir represents the key, and its name is the key hash
                key_hash = value_path.parent.name

                if key_hash == _metakeys_hash:
                    try:
                        hash_to_key[value_path.name] = value_path.read_bytes()
                    except OSError:  # pragma: no cover
                        # this might occur if all the values in a key have been
                        # deleted and DirectoryBasedExampleDatabase removes its
                        # metakeys entry (which is `value_path` here`).
                        pass
                    return
```

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

### example.via usage example

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/core.html

Shows how to use @example(...).via() to attach a machine-readable label to an example. The label is optional and does not change runtime behavior; it is intended for self-documenting behavior and tooling.

```python
# Annotating examples is optional and does not change runtime behavior
@example(...)
@example(...).via("regression test for issue #42")
@example(...).via("discovered failure")
def test(x):
    pass
```

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

### Use .example() to see generated values

Source: https://hypothesis.readthedocs.io/en/latest/_sources/tutorial/introduction.rst.txt

Shows how to use the .example() method to get an idea of what a strategy will generate. It is intended for interactive use only, not inside tests.

```pycon
>>> st.lists(st.integers() | st.floats(allow_nan=False)).example()
[-5.969063e-08, 15283673678, 18717, -inf]
```

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

### Use crosshair backend with Hypothesis settings

Source: https://hypothesis.readthedocs.io/en/latest/_sources/extensions.rst.txt

Example of using the crosshair backend to generate inputs with SMT solvers. Requires pip install hypothesis[crosshair]. Failures are saved and shrink normally.

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

@settings(backend="crosshair")  # pip install hypothesis[crosshair]
@given(st.integers())
def test_needs_solver(x):
    assert x != 123456789
```

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

### Output of running example.py

Source: https://hypothesis.readthedocs.io/en/latest/_sources/quickstart.rst.txt

Example output when running python example.py, showing generated integers.

```none
called with 0
called with -18588
called with -672780074
called with 32616
...
```

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

### Targeted Property-Based Testing with hypothesis.target

Source: https://hypothesis.readthedocs.io/en/latest/_sources/reference/api.rst.txt

Use the target function to guide input generation towards values that are more likely to falsify a property. This example demonstrates testing floating-point associativity by targeting the difference between two calculation orders.

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

@given(st.floats(0, 1e100), st.floats(0, 1e100), st.floats(0, 1e100))
def test_associativity_with_target(a, b, c):
    ab_c = (a + b) + c
    a_bc = a + (b + c)
    difference = abs(ab_c - a_bc)
    target(difference)  # Without this, the test almost always passes
    assert difference < 2.0
```

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

### Register a settings profile

Source: https://hypothesis.readthedocs.io/en/latest/_sources/tutorial/settings.rst.txt

Create a settings profile using settings.register_profile. This example registers a profile named "fast" with max_examples=10. Place this code in a file loaded before tests run, such as a conftest.py file.

```python
from hypothesis import HealthCheck, settings

settings.register_profile("fast", max_examples=10)
```

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

### ExampleDatabase._start_listening

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/database.html

Internal method called when the database adds its first change listener. Intended to allow databases to start expensive listening operations.

```APIDOC
## ExampleDatabase._start_listening

### Description
Called when the database adds a change listener and did not previously have any. Intended to allow databases to wait to start expensive listening operations until necessary. `_start_listening` and `_stop_listening` are guaranteed to alternate.

### Method
_start_listening

### Signature
`_start_listening(self) -> None`

### Notes
- Emits a `HypothesisWarning` if the database does not support listening for changes.
```

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

### Using the crosshair backend with settings.backend

Source: https://hypothesis.readthedocs.io/en/latest/extensions.html

Configure a test to use the crosshair backend by setting backend="crosshair" in the @settings decorator. Requires pip install hypothesis[crosshair]. The example shows a test that asserts x != 123456789, which is difficult for random generation but solvable with SMT solvers.

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

@settings(backend="crosshair")  # pip install hypothesis[crosshair]
@given(st.integers())
def test_needs_solver(x):
    assert x != 123456789

```

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

### Build strategy for current settings with st.builds

Source: https://hypothesis.readthedocs.io/en/latest/_sources/changelog.rst.txt

This example shows how to build a strategy that generates the current default settings. Previously it generated the settings at definition time, but now it generates the settings used for the current test. This is a small change to non-public API behavior and is not encouraged.

```python
import hypothesis.strategies as st
from hypothesis import settings

CURRENT_SETTINGS = st.builds(lambda: settings.default)
```

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

### Use assume for multiple conditions and move simple filters to .filter

Source: https://hypothesis.readthedocs.io/en/latest/_sources/tutorial/adapting-strategies.rst.txt

This example shows a test that filters out two types of inputs: b != 0 and a % b == 0. It starts with two assume calls, then moves the b != 0 condition into a .filter call on the strategy, leaving the more complex relationship as an assume.

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

@given(st.integers(), st.integers())
def test_floor_division_lossless_when_b_divides_a(a, b):
    # we want to assume that:
    # * b is nonzero, and
    # * b divides a
    assert (a // b) * b == a
```

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

@given(st.integers(), st.integers())
def test_floor_division_lossless_when_b_divides_a(a, b):
    assume(b != 0)
    assume(a % b == 0)
    assert (a // b) * b == a
```

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

@given(st.integers(), st.integers().filter(lambda n: n != 0))
def test_floor_division_lossless_when_b_divides_a(a, b):
    assume(a % b == 0)
    assert (a // b) * b == a
```

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

### Explicit example with @example

Source: https://hypothesis.readthedocs.io/en/latest/_sources/glossary.rst.txt

Defines an explicit example for a test function. The example is always run in the Phase.explicit phase and is not shrunk by Hypothesis.

```python
@example(42)
def f(n):
    pass
```

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

### GitHubArtifactDatabase __init__ method

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/database.html

Initializes the GitHubArtifactDatabase with owner, repo, artifact_name, cache_timeout, and optional path. Reads GITHUB_TOKEN from environment, sets up storage directory, and prepares internal state for lazy initialization.

```python
def __init__(
    self,
    owner: str,
    repo: str,
    artifact_name: str = "hypothesis-example-db",
    cache_timeout: timedelta = timedelta(days=1),
    path: StrPathT | None = None,
):
    super().__init__()
    self.owner = owner
    self.repo = repo
    self.artifact_name = artifact_name
    self.cache_timeout = cache_timeout

    # Get the GitHub token from the environment
    # It's unnecessary to use a token if the repo is public
    self.token: str | None = getenv("GITHUB_TOKEN")

    self._storage_dir: StorageDirectory | None = None
    if path is None:
        self._storage_dir = storage_directory(
            f"github-artifacts/{self.artifact_name}/"
        )
        self.path = self._storage_dir.path
    else:
        self.path = Path(path)

    # We don't want to initialize the cache until we need to
    self._initialized: bool = False
    self._disabled: bool = False

    # This is the path to the artifact in usage
    # .hypothesis/github-artifacts/<artifact-name>/<modified_isoformat>.zip
    self._artifact: Path | None = None
    # This caches the artifact structure
    self._access_cache: dict[PurePath, set[PurePath]] | None = None

    # Message to display if user doesn't wrap around ReadOnlyDatabase
    self._read_only_message = (
        "This database is read-only. "
        "Please wrap this class with ReadOnlyDatabase"
        "i.e. ReadOnlyDatabase(GitHubArtifactDatabase(...))."
    )
```

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

### SearchStrategy.example

Source: https://hypothesis.readthedocs.io/en/latest/reference/strategies.html

The example method generates a single example value from the strategy. It is intended for REPL use and will raise an error if used inside @given or strategy definitions.

```APIDOC
## SearchStrategy.example

### Description
Provide an example of the sort of value that this strategy generates. This method is designed for use in a REPL, and will raise an error if called from inside `@given` or a strategy definition.

### Method
N/A

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

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

### Using positional and keyword arguments with @example

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/core.html

Shows that @example arguments may be either positional or keyword arguments, but not both in the same @example. Arguments to @example are values, not strategies.

```python
@example(1, 2)
@example(x=1, y=2)
@given(st.integers(), st.integers())
def test(x, y):
    pass
```

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

### Example of assume() with @example() decorator

Source: https://hypothesis.readthedocs.io/en/latest/changelog.html

This test demonstrates the improved interaction between assume() and @example() introduced in version 5.11.0. Previously, the @example(value=0.56789) would cause the test to fail with UnsatisfiedAssumption, but now it works correctly.

```python
@given(value=floats(0, 1))
@example(value=0.56789)  # used to make the test fail!
@pytest.mark.parametrize("threshold", [0.5, 1])
def test_foo(threshold, value):
    assume(value < threshold)
    ...

```

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

### hypothesis write CLI help output

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/extra/ghostwriter.html

Example output from running `hypothesis write --help`, showing the command-line interface usage and options for the ghostwriter.

```text
$ hypothesis write --help
Usage: hypothesis write [OPTIONS] FUNC...

  `hypothesis write` writes property-based tests for you!

  Type annotations are helpful but not required for our advanced
  introspection and templating logic.  Try running the examples below to see
  how it works:

      hypothesis write gzip
      hypothesis write numpy.matmul
      hypothesis write pandas.from_dummies
      hypothesis write re.compile --except re.error
      hypothesis write --equivalent ast.literal_eval eval
      hypothesis write --roundtrip json.dumps json.loads
      hypothesis write --style=unittest --idempotent sorted
      hypothesis write --binary-op operator.add

Options:
  --roundtrip                 start by testing write/read or encode/decode!
  --equivalent                very useful when optimising or refactoring code
  --errors-equivalent         --equivalent, but also allows consistent errors
  --idempotent                check that f(x) == f(f(x))
  --binary-op                 associativity, commutativity, identity element
  --style [pytest|unittest]   pytest-style function, or unittest-style method?
  -e, --except OBJ_NAME       dotted name of exception(s) to ignore
  --annotate / --no-annotate  force ghostwritten tests to be type-annotated
                              (or not).  By default, match the code to test.
  -h, --help                  Show this message and exit.
```

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

### GitHub Actions workflow to download example database

Source: https://hypothesis.readthedocs.io/en/latest/_modules/hypothesis/database.html

YAML workflow steps to download the example database artifact and run tests. The download step uses dawidd6/action-download-artifact@v9 with the artifact name 'hypothesis-example-db' and path '.hypothesis/examples'.

```yaml
- name: Download example database
  uses: dawidd6/action-download-artifact@v9
  with:
    name: hypothesis-example-db
    path: .hypothesis/examples
    if_no_artifact_found: warn
    workflow_conclusion: completed

- name: Run tests
  run: pytest
```
Tokens:
Raw