pytest-describe

What it is and what it does

pytest-describe is a pytest plugin that lets you write tests using nested describe-blocks instead of flat test functions or test classes. Rather than naming each test to encode both the function being tested and the case (like `test_my_function_with_default_arguments`), you nest functions inside describe-blocks to create a hierarchy that mirrors your code structure. This reduces naming overhead and allows fixtures and marks to apply locally to groups of related tests.

The plugin works by recognizing functions prefixed with `describe_` (configurable) as test containers and collecting nested functions as individual tests. It supports pytest fixtures as describe-block arguments, shared behaviors similar to RSpec's shared examples, helper functions prefixed with underscore, and optional docstring-based naming for clearer test reports. It requires Python 3.10 or later and integrates transparently with pytest's standard collection and execution.

Use it for:

• Organizing tests for a class with multiple methods by creating nested describe-blocks for each method and cases within
• Sharing common test patterns across multiple test subjects using the behaves_like decorator
• Reducing test function name length and complexity by using describe hierarchy instead of long descriptive names
• Applying fixtures and marks to groups of related tests without repeating them in every test function
• Writing test suites that closely mirror the structure of the code being tested for easier navigation

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A pytest plugin that organizes tests into nested describe-blocks, allowing test structure to mirror production code organization with separate cases for each function.

Yes. The plugin is actively maintained, has no known vulnerabilities, low install friction, and solves a real organizational problem for test suites. It's particularly valuable if your tests have multiple cases per function and you prefer hierarchy over long naming conventions. The MIT license imposes no restrictions.

Install

pytest-describe on PyPI

pip install pytest-describe

uv add pytest-describe

poetry add pytest-describe

Installing pytest-describe

Before you install

Low friction: pure Python wheel with only pytest as a runtime dependency. Actively maintained with a recent release 63 days ago and steady repository activity.

License in practice

MIT license permits unrestricted use, modification, and distribution in both open and proprietary projects with minimal restrictions.

Quickstart

pip install pytest-describe

import pytest

def describe_wallet():
    def with_starting_balance():
        @pytest.fixture
        def wallet():
            return Wallet(20)
        
        def initial_amount(wallet):
            assert wallet.balance == 20

Requires Python 3.10 or later

Verify before relying

• Whether shared behaviors (behaves_like) work correctly with all pytest fixture scopes and parametrization patterns
• Performance impact of nested describe-blocks on test collection time for large test suites

Package facts

Evidence: pytest_describe-3.2.0-py3-none-any.whl

Keywords: test, unittest, plugin, describe

Tags

More Libraries packages