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 on it.

Install

pytest-describe on PyPI

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.

Requires Python 3.10 or later

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

Package facts

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

Tags

More Libraries packages

See also pytest-markdown-docs · pytest-integration · pytest-cases · pytest-lazy-fixtures · pytest-datadir · pytest-container · pytest-beartype-tests · pytest-codeblocks · pytest-docker