---
id: pytest-spec
version: "6.1.0"
license: GPL-2.0-or-later
license_treatment: copyleft
maintenance: active
---

# pytest-spec — Library pytest-spec is a pytest plugin to display test execution output like a SPECIFICATION.

License: copyleft · Maintenance: active · Downloads: 212.6K/mo

## What it is and what it does

pytest-spec is a pytest plugin that changes how test results are displayed in the terminal. Instead of the default pytest output, it formats results to resemble a specification document, grouping tests by file and class, replacing underscores and test_ prefixes with readable names, and marking pass/fail/skip status with configurable indicators and colors.

The plugin is designed for teams that want test output to double as living documentation. It supports function-based, class-based, and describe-style tests, and allows extensive customization through pytest configuration files (pytest.ini or pyproject.toml) to control header format, test name display, status indicators, indentation, and filtering of unwanted output.

Use it for:

- Display test results as readable specification output during development and CI/CD pipelines.
- Replace test_ prefixes and underscores with human-readable names automatically in test output.
- Group and organize test results hierarchically by module, class, and describe blocks.
- Customize test result indicators (✓, ✗, ») and formatting to match team documentation standards.
- Filter out noise from other pytest plugins (e.g., FLAKE8, ISORT) in spec output.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

pytest-spec is a pytest plugin that reformats test output to display results in a specification-like format with hierarchical grouping, colored status indicators, and human-readable test names.

Yes. Low install friction, no dependencies, actively maintained, supports modern Python versions, and zero known vulnerabilities. The GPL-2.0-or-later license is the only consideration—verify compatibility with your project's licensing before adopting. Useful for teams that want test output to serve as readable documentation.

## Install

pip install pytest-spec
uv add pytest-spec
poetry add pytest-spec

## Installing pytest-spec

Before you install: Low install friction with no runtime dependencies. The package is actively maintained with a recent release (89 days ago) and supports current Python versions (3.9 through 3.14).

License in practice: Licensed under GPL-2.0-or-later (copyleft). Any derivative work or distribution must comply with GPL-2.0 terms; review your project's license compatibility before adopting.

Quickstart:

pip install pytest-spec

Then run pytest normally:
pytest

Optionally configure in pytest.ini or pyproject.toml:
[tool.pytest.ini_options]
spec_header_format = "{module_path}:"
spec_test_format = "{result} {name}"

Requires Python 3.9 or later. pytest must be installed and your tests must be discoverable by pytest.

Verify before relying:

- Whether the plugin works with all pytest plugins or has known incompatibilities.
- Performance impact on test suites with many tests or complex hierarchies.

## Package facts

- License: GPL-2.0-or-later (copyleft)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 212.6K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pytest output formatting, test specification display, pytest plugin readable output, colored test results, test hierarchy grouping, test-output-formatting, pytest-plugin

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