Master Property‑Based Testing in Python with Hypothesis

Introduction

Testing is essential regardless of the programming language or framework you use. Hypothesis is a high‑level testing library for Python that allows you to parameterize test cases and automatically generate simple, understandable data that makes tests fail, helping you discover more bugs with less effort.

This article demonstrates how to use Hypothesis for testing in Python and provides several examples.

How Do We Differentiate Tests?

Before diving into property‑based testing, it’s useful to know the general categories of tests. Tests are often grouped by method and level. The four common test levels are:

Unit testing

Integration testing

System testing

End‑to‑end testing

Each level focuses on different aspects: unit tests target specific functions or parts of code, integration tests examine interactions between components, and system tests evaluate the entire system.

Test methods can be classified as static or dynamic. Static testing examines code, interfaces, or documentation without executing the software, while dynamic testing involves running the software (unit and integration tests are dynamic).

Another common classification is based on the “box” approach: white‑box testing verifies internal structures, black‑box testing treats the program as a black box and tests its behavior without knowledge of the internals, and gray‑box combines both.

What Is Property‑Based Testing?

Property‑based testing involves writing logical statements (properties) that should hold true for your code, then using an automated tool to generate random inputs and check whether the property remains true. If an input violates a property, the test reveals a bug and provides a minimal counterexample.

Using Hypothesis for Property‑Based Testing

Consider two simple functions, increment() and decrement():

# increment_decrement.py

def increment(number: int) -> int:
    return number + 1

def decrement(number: int) -> int:
    return number - 1

Standard unit tests with pytest might look like this:

# test_increment_decrement_pytest.py

from increment_decrement import increment, decrement

def test_increment():
    x = 5
    expected = 6
    actual = increment(x)
    assert actual == expected

def test_decrement():
    x = 5
    expected = 4
    actual = decrement(x)
    assert actual == expected

With Hypothesis, you can write property‑based tests that automatically generate many integer inputs:

# test_increment_decrement_hypothesis.py

from hypothesis import given, strategies as st
from increment_decrement import increment, decrement

@given(st.integers())
def test_increment(x):
    expected = x + 1
    actual = increment(x)
    assert actual == expected

@given(st.integers())
def test_decrement(x):
    expected = x - 1
    actual = decrement(x)
    assert actual == expected

Both tests receive a parameter x whose values are generated by Hypothesis using the integers() strategy.

If you need to ensure a specific value is tested, Hypothesis provides an @example() decorator. For example, to test division by zero:

# div.py

def div(dividend: int, divisor: int) -> int:
    if divisor == 0:
        return -1
    return dividend // divisor

# test_div.py

from hypothesis import given, example, strategies as st
from div import div

@given(dividend=st.integers(), divisor=st.integers())
@example(1, 0)
def test_div(dividend, divisor):
    if divisor == 0:
        expected = -1
    else:
        expected = dividend // divisor
    actual = div(dividend, divisor)
    assert actual == expected

The @example(1, 0) ensures that the edge case of a zero divisor is always tested, even if it is not produced by the random generator.

Summary

This article explained what property‑based testing is, why it is useful, and introduced the Hypothesis library, which lets you write such tests and run them alongside traditional pytest tests.