Skip to main content

pytest-bdd-property

Property-based testing for Gherkin scenarios, powered by Hypothesis.

Express universal invariants in standard Gherkin, and have Hypothesis generate 100+ inputs to find counterexamples automatically.

Quick Start

1. Tag your scenario with @property-based

@property-based
Feature: Password Hashing Properties

  Scenario: A password always verifies against its own hash
    Given any valid password <P>
    When <P> is hashed producing <H>
    Then <P> verifies against <H>

2. Register your conftest step definitions

In your root conftest.py:

import pytest_bdd_property.plugin  # registers pytest hooks

from pytest_bdd import given, when, then, parsers
from pytest_bdd_property.plugin import (
    handle_given_step,
    handle_when_step,
    handle_then_step,
)

@given(parsers.re(r"(?P<text>any .+|<.+)"))
def property_given_step(text):
    handle_given_step(text)

@when(parsers.re(r"(?P<text><.+)"))
def property_when_step(text):
    handle_when_step(text)

@then(parsers.re(r"(?P<text><.+)"))
def property_then_step(text):
    handle_then_step(text)

3. Write property step definitions

from pytest_bdd import scenarios
from pytest_bdd_property import register_strategy, property_when, property_then
from hypothesis import strategies as st

scenarios("my_feature.feature")

register_strategy("valid password", lambda: st.text(min_size=8, max_size=128))

@property_when(r"<(\w+)> is hashed producing <(\w+)>")
def hash_step(vals, results, pw_var, hash_var):
    results[hash_var] = hash_password(vals[pw_var])

@property_then(r"<(\w+)> verifies against <(\w+)>")
def verify_step(vals, results, pw_var, hash_var):
    assert verify_password(vals[pw_var], results[hash_var])

4. Run tests

pytest tests/ -v

Hypothesis runs each @property-based scenario 100 times with generated inputs. On failure, it shrinks to find the minimal counterexample.


How It Works

Two-Phase Execution Model

Phase 1 (Registration): During normal pytest-bdd step execution:

  • Given any <type> <var> → registers a Hypothesis strategy
  • And <A> is not equal to <B> → registers an assumption (filter)
  • When/Then steps → register callbacks (don't execute yet)

Phase 2 (Execution): After all steps run, a pytest hook triggers:

  • Hypothesis builds a composite strategy from all registered strategies
  • Runs the property 100+ times with generated inputs
  • Applies assumptions via hypothesis.assume()
  • Executes When callbacks (actions), then Then callbacks (assertions)
  • On failure: shrinks to find the minimal counterexample

Architecture

conftest.py                    test_my_feature.py
  ├── plugin hooks               ├── scenarios("my.feature")
  └── catch-all steps            ├── register_strategy(...)
       │                         ├── @property_when(...)
       ▼                         └── @property_then(...)
  plugin.py
  ├── pytest_runtest_setup → detect @property-based tag
  ├── handle_given_step → strategy + assumption registration
  ├── handle_when_step → action callback registration
  ├── handle_then_step → assertion callback registration
  └── pytest_runtest_call → run_property_test() via Hypothesis

Built-in Strategies

Use these directly in your feature files with Given any <type> <var>:

Primitives

Strategy Name Description Hypothesis Equivalent
text Arbitrary Unicode strings st.text()
non-empty text Strings with length ≥ 1 st.text(min_size=1)
integer Arbitrary integers st.integers()
positive integer Integers ≥ 1 st.integers(min_value=1)
negative integer Integers ≤ -1 st.integers(max_value=-1)
natural Integers ≥ 0 st.integers(min_value=0)
float Floats (no NaN/Infinity) st.floats(allow_nan=False, allow_infinity=False)
boolean True or False st.booleans()

Strings

Strategy Name Description Hypothesis Equivalent
ascii text ASCII-only strings st.text(alphabet=st.characters(codec="ascii"))
alphanumeric [a-z0-9]+ strings st.from_regex(r"[a-z0-9]+")
hex string [0-9a-f]+ strings st.from_regex(r"[0-9a-f]+")

Identifiers

Strategy Name Description Hypothesis Equivalent
uuid UUID v4 strings st.uuids().map(str)
email Email-shaped strings st.emails()
url URL-shaped strings st.from_regex(...)

Temporal

Strategy Name Description Hypothesis Equivalent
date Date objects st.dates()

Structured

Strategy Name Description Hypothesis Equivalent
json value Recursive JSON values st.recursive(...)
json object dict[str, str] st.dictionaries(st.text(), st.text())

Domain Defaults

Strategy Name Description Hypothesis Equivalent
password Text, 8-128 chars st.text(min_size=8, max_size=128)
username [a-z0-9_]{3,32} st.from_regex(...)

Custom Strategies

Register domain-specific strategies in your test file:

from pytest_bdd_property import register_strategy
from hypothesis import strategies as st

register_strategy("valid password", lambda: (
    st.tuples(
        st.text(alphabet="abcdefghijklmnopqrstuvwxyz", min_size=2, max_size=10),
        st.text(alphabet="ABCDEFGHIJKLMNOPQRSTUVWXYZ", min_size=2, max_size=10),
        st.text(alphabet="0123456789", min_size=2, max_size=5),
        st.text(alphabet="!@#$%^&*", min_size=2, max_size=3),
    ).map(lambda parts: parts[0] + parts[1] + parts[2] + parts[3])
))

Then in Gherkin:

Given any valid password <P>

Built-in Assumptions

Use these in Given/And steps to filter generated inputs:

Equality

Pattern Meaning Maps To
<A> is not equal to <B> A ≠ B assume(A != B)
<A> is equal to <B> A = B assume(A == B)

Numeric Comparison

Pattern Meaning Maps To
<A> is greater than <B> A > B assume(A > B)
<A> is less than <B> A < B assume(A < B)
<A> is greater than or equal to <B> A ≥ B assume(A >= B)
<A> is less than or equal to <B> A ≤ B assume(A <= B)

Emptiness

Pattern Meaning Maps To
<A> is not empty len(A) > 0 assume(len(A) > 0)
<A> is empty len(A) = 0 assume(len(A) == 0)

Length

Pattern Meaning Maps To
<A> has length greater than N len(A) > N assume(len(A) > N)
<A> has length less than N len(A) < N assume(len(A) < N)

Containment

Pattern Meaning Maps To
<A> contains <B> B in A assume(B in A)
<A> does not contain <B> B not in A assume(B not in A)

Type Checks

Pattern Meaning Maps To
<A> is a number isinstance(A, (int, float)) assume(isinstance(A, (int, float)))
<A> is a string isinstance(A, str) assume(isinstance(A, str))

Custom Assumptions

from pytest_bdd_property import register_assumption

register_assumption(
    r"^<(\w+)> is a valid email$",
    lambda var: lambda vals: "@" in str(vals[var])
)

Configuration via Tags

@property-based @num-runs:500 @seed:42 @verbose
Scenario: Stress test hashing
  ...
Tag Effect
@num-runs:<n> Override number of generated examples (default: 100)
@seed:<n> Fix the random seed for reproducibility
@verbose Enable verbose output

Common Patterns

Round-trip (Serialization)

@property-based
Scenario: JSON round-trip preserves data
  Given any json object <D>
  When <D> is serialized to JSON producing <J>
  And <J> is deserialized producing <D2>
  Then <D> is equal to <D2>

Idempotency

@property-based
Scenario: Normalizing email twice gives the same result
  Given any email <E>
  When <E> is normalized producing <N1>
  And <N1> is normalized producing <N2>
  Then <N1> is equal to <N2>

No False Positives

@property-based
Scenario: Wrong password never verifies
  Given any valid password <P>
  And any valid password <Q>
  And <P> is not equal to <Q>
  When <P> is hashed producing <H>
  Then <Q> does not verify against <H>

No Information Leakage

@property-based
Scenario: Hash never contains plaintext
  Given any valid password <P>
  When <P> is hashed producing <H>
  Then <H> does not contain <P>

API Reference

register_strategy(name, factory)

Register a named strategy for Given any <name> <var>.

  • name: Case-insensitive strategy name
  • factory: () -> SearchStrategy callable

property_when(pattern)

Decorator to register a When step for property-based scenarios.

@property_when(r"<(\w+)> is hashed producing <(\w+)>")
def hash_step(vals, results, pw_var, hash_var):
    results[hash_var] = hash_password(vals[pw_var])
  • vals: dict[str, Any] — generated values keyed by variable name
  • results: dict[str, Any] — intermediate results from When steps
  • Additional args: regex capture groups from the pattern

property_then(pattern)

Decorator to register a Then step for property-based scenarios.

@property_then(r"<(\w+)> verifies against <(\w+)>")
def verify_step(vals, results, pw_var, hash_var):
    assert verify_password(vals[pw_var], results[hash_var])

Raise AssertionError to signal a property violation. Hypothesis shrinks to minimal counterexample.

register_assumption(pattern, builder)

Register a custom assumption pattern.

register_assumption(
    r"^<(\w+)> is a valid email$",
    lambda var: lambda vals: "@" in str(vals[var])
)

resolve_strategy(name)

Resolve a strategy name to a Hypothesis SearchStrategy. Raises ValueError if not found.

list_strategies()

Return all registered strategy names, sorted.


Coexistence with Behavioral Scenarios

Property-based and behavioral scenarios coexist naturally:

Feature: User Authentication

  # Behavioral (concrete examples)
  Scenario: User can log in with correct password
    Given a user with password "hunter2"
    When they log in with "hunter2"
    Then they are authenticated

  # Property (universal invariant)
  @property-based
  Scenario: Wrong password never authenticates
    Given any text <P>
    And any text <Q>
    And <P> is not equal to <Q>
    Given a user with password <P>
    When they log in with <Q>
    Then they are rejected

The @property-based tag tells the plugin to intercept execution. Scenarios without the tag run normally through pytest-bdd.

Metadata

Release files for pytest-bdd-property 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pytest-bdd-property 0.1.1
File Size Uploaded Provenance Actions
pytest_bdd_property-0.1.1.tar.gz 15.1 kB Without provenance Details for pytest_bdd_property-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for pytest-bdd-property 0.1.1
File Interpreter ABI Platform Actions
pytest_bdd_property-0.1.1-py3-none-any.whl Python 3 none any Details for pytest_bdd_property-0.1.1-py3-none-any.whl

Total release size: 29.7 kB

Release files / pytest_bdd_property-0.1.1.tar.gz

Download URL pytest_bdd_property-0.1.1.tar.gz
Size 15.1 kB
Tags Source
SHA-256 checksum
How to use checksums
313f9232d449c9467f7c39dc31e639532281e292a924477235feaeee82b1d8f7
BLAKE2b-256 checksum
How to use checksums
3405181e51189b505efe1c6928c04ce3ee44d86abd6ccf8c5f81393018529825
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Release files / pytest_bdd_property-0.1.1-py3-none-any.whl

Download URL pytest_bdd_property-0.1.1-py3-none-any.whl
Size 14.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1524a3148ba7df2c526cdd32d1227420963ae72a84abcaa4bf7b6e8e9e473050
BLAKE2b-256 checksum
How to use checksums
f7f858d3a2f38ad00e9a9ef96b801a3838ea5fbb2b907f47daeb053397ad28ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.14.7

Security for pytest-bdd-property 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page