---
id: pytest-describe
version: "3.2.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# pytest-describe — Describe-style plugin for pytest

License: permissive · Maintenance: active · Downloads: 1.2M/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest nested describe blocks, rspec style testing python, organize tests by function cases, pytest describe plugin, hierarchical test organization, jasmine style test structure, test grouping and nesting, test-organization, rspec-style, pytest-plugin

[View on SkillFed](https://skillfed.io/packages/pytest-describe) · [View on PyPI](https://pypi.org/project/pytest-describe/)