pytest-describe

library3.2.0pypypi✓ verified 24d ago

pytest-describe is a plugin for the pytest testing framework that enables writing tests in an RSpec/Jasmine-style format, using arbitrary nested `describe-blocks`. This approach helps organize tests by context and behavior, making test suites more readable and maintainable. The current version is 3.1.0, and it is actively maintained with regular updates to support newer Python and pytest versions.

testing

pip install pytest-describe

github ↗package ↗

INSTALL

IMPORT

SIG · PYTEST-DESCRIBE

pytest-describe

testingpythonv3.2.0

Install

2.7s avg

Import

354ms

Disk

30MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v3.2.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.368s · 31.1MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 2.7s · import 0.340s · 32MB

30MB installed

● package 30MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

behaves_like

✓ from pytest_describe import behaves_like

Used for sharing test behaviors across multiple describe blocks.

describe_ / it_ (naming conventions)

✓ def describe_feature(): def it_should_do_something(): pass

Core describe/it functionality relies on specific function naming conventions (`describe_`, `it_`) within test modules and does not require explicit imports into user code. These names are automatically discovered by pytest with the plugin active.

This example demonstrates how to structure tests for a `Wallet` class using nested `describe_` blocks and `pytest` fixtures. Define a top-level `describe_` function, and then nest further `describe_` functions or test functions (which can also use the `it_` prefix) within them. Fixtures defined within a `describe_` block apply to all tests within that block and its nested blocks. Save this as a Python file (e.g., `test_wallet.py`) and run `pytest` from your terminal.

import pytest class Wallet: def __init__(self, initial_amount=0): self.balance = initial_amount def spend_cash(self, amount): if self.balance < amount: raise ValueError(f'Not enough available to spend {amount}') self.balance -= amount def add_cash(self, amount): self.balance += amount def describe_wallet(): def describe_start_empty(): @pytest.fixture def wallet(): return Wallet() def initial_amount_is_zero(wallet): assert wallet.balance == 0 def can_add_cash(wallet): wallet.add_cash(80) assert wallet.balance == 80 def cannot_spend_if_empty(wallet): with pytest.raises(ValueError): wallet.spend_cash(10) def describe_with_starting_balance(): @pytest.fixture def wallet(): return Wallet(20) def initial_amount_is_twenty(wallet): assert wallet.balance == 20 def describe_adding(): def add_little_cash(wallet): wallet.add_cash(5) assert wallet.balance == 25 def add_much_cash(wallet): wallet.add_cash(980) assert wallet.balance == 1000 def describe_spending(): def spend_cash(wallet): wallet.spend_cash(15) assert wallet.balance == 5 def spend_too_much_cash(wallet): with pytest.raises(ValueError): wallet.spend_cash(25)

pytest --version

Debug

Known issues

breakingpytest-describe versions are tightly coupled to specific ranges of pytest and Python versions. For instance, version 3.1.0 supports pytest 6.0 to 9.0 and Python 3.9 to 3.14. Upgrading your pytest or Python environment without verifying compatibility against pytest-describe's release notes can lead to unexpected test collection failures or runtime errors.

fix

Always check the `pytest-describe` release notes or documentation for the supported `pytest` and `Python` versions before upgrading your testing environment. If compatibility issues arise, downgrade `pytest-describe` or `pytest` to a compatible version.

affects: <3.1.0, >=2.0.0

gotchaWithin `describe_` blocks, only functions starting with `describe_` or any non-underscore prefix are collected as tests. Functions that start with a single underscore (e.g., `def _helper_function():`) are explicitly *not* collected as tests. This is intended for helper functions but can be a gotcha if you accidentally prefix a test with an underscore, causing it to be skipped.

fix

Ensure that all functions intended to be tests within `describe_` blocks follow the standard pytest naming conventions (e.g., `test_`, or for `pytest-describe`, commonly `it_` or other non-underscore prefixed names like `initial_amount_is_zero`) to ensure they are discovered and run.

affects: All versions

gotchaBy default, `pytest-describe` only recognizes functions starting with `describe_` as test blocks. If you prefer to use alternative prefixes (e.g., `context_`, `feature_`) for your organizational blocks, you must explicitly configure these in your pytest configuration file (e.g., `pyproject.toml` or `pytest.ini`) using the `describe_prefixes` option.

fix

To use custom prefixes, add a configuration like this to your `pyproject.toml`: `[tool.pytest.ini_options]
describe_prefixes = ["describe_", "context_", "feature_"]`. Without this, only `describe_` blocks will be collected.

affects: All versions

Errors

Common errors & fixes

NameError: name 'describe' is not defined

The 'describe' (and 'it') function is not a built-in Python keyword; it must be imported from the 'pytest_describe' library to be available in your test files.

fix

Add 'from pytest_describe import describe, it' at the top of your test file.

ModuleNotFoundError: No module named 'pytest_describe'

The 'pytest-describe' package has not been installed in the Python environment where you are attempting to run your tests.

fix

Install the package using pip: `pip install pytest-describe`

TypeError: describe() missing 1 required positional argument: 'description'

The 'describe' (or 'it') function was called without providing the mandatory string argument that serves as its descriptive name.

fix

Provide a descriptive string as the first argument, e.g., `describe("My feature under test", ...)` or `it("should do something specific", ...)`.

NameError: name 'my_fixture' is not defined

A pytest fixture was used inside an 'it' or 'before_each' block without being explicitly declared as an argument to that block's function, which is how pytest injects fixtures.

fix

Declare the fixture as an argument in the 'it' or 'before_each' function signature, e.g., `it("should use fixture", lambda my_fixture: ...)` or `def before_each(my_fixture): ...`.

Upgrade

Version history

3.2.0latest on PyPI · released Jun 12, 2026

Audit

Dependencies

pytestrequiredpytest-describe is a plugin for pytest and requires pytest to function.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/pytest-dev/pytest-describe ↗

packagehttps://pypi.org/project/pytest-describe/ ↗