pytest-spec 6.1.0

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

pytest-spec

Library pytest-spec is a pytest plugin to display test execution output like a SPECIFICATION.
[Documentation]

Available features

• Format output to look like specification.
• Group tests by classes and files
• Failed, passed and skipped are marked and colored.
• Remove test_ and underscores for every test.
• It is possible to use docstring summary instead of test name.
• Supports function based, class based test.
• Supports describe like tests.

Output example

Configuration

spec_header_format

spec_header_format

You can configure the format of the test headers by specifying a format string in your ini-file:

    ; since pytest 4.6.x
    [pytest]
    spec_header_format = {module_path}:

    ; legacy pytest
    [tool:pytest]
    spec_header_format = {module_path}:

or in your pyproject.toml file:

    [tool.pytest.ini_options]
    spec_header_format = "{module_path}:"

In addition to the {path} and {class_name} replacement fields, there is also {test_case} that holds a more human readable name.

spec_container_format

spec_container_format

You can configure the format of test container names (e.g., describe_* or Test* classes/methods) by specifying a format string in your ini-file:

Available variables:

• {sentence} - Capitalize first letter, replace underscores with spaces, remove describe_ prefix
• {unit_name} - Raw name with describe_ prefix removed, underscores preserved

    ; since pytest 4.6.x
    [pytest]
    spec_container_format = {sentence}:

    ; legacy pytest
    [tool:pytest]
    spec_container_format = {sentence}:

Similar configuration could be done in your pyproject.toml file:

    [tool.pytest.ini_options]
    spec_container_format = "{sentence}:"

Here is an example of what the formatted output might look like:

Format	Test Container	Formatted Output
sentence	class TestFibonacciSequence	Fibonacci Sequence
sentence	def describe_fibonacci_sequence()	Fibonacci sequence
unit_name	class TestFibonacciSequence	FibonacciSequence
unit_name	def describe_fibonacci_sequence()	fibonacci_sequence

spec_test_format

spec_test_format

You can configure the format of the test results by specifying a format string in your ini-file:

3 variables are available:

• result - place for indicator
• name - name of test
• docstring_summary - first line from test docstring if available

    ; since pytest 4.6.x
    [pytest]
    spec_test_format = {result} {name}

    ; legacy pytest
    [tool:pytest]
    spec_test_format = {result} {name}

or

    ; since pytest 4.6.x
    [pytest]
    spec_test_format = {result} {docstring_summary}

    ; legacy pytest
    [tool:pytest]
    spec_test_format = {result} {docstring_summary}

In second example where docstring is not available the name will be added to spec output.

Similar configuration could be done in your pyproject.toml file:

    [tool.pytest.ini_options]
    spec_test_format = "{result} {name}"

or

    [tool.pytest.ini_options]
    spec_test_format = "{result} {docstring_summary}"

spec_success_indicator

spec_success_indicator

You can configure the indicator displayed when test passed.

ini-file

    ; since pytest 4.6.x
    [pytest]
    spec_success_indicator = ✓

    ; legacy pytest
    [tool:pytest]
    spec_success_indicator = ✓

or pyproject.toml

    [tool.pytest.ini_options]
    spec_success_indicator = "✓"

spec_failure_indicator

spec_failure_indicator

You can configure the indicator displated when test failed.

ini-file

    ; since pytest 4.6.x
    [pytest]
    spec_failure_indicator = ✗

    ; legacy pytest
    [tool:pytest]
    spec_failure_indicator = ✗

or pyproject.toml

    [tool.pytest.ini_options]
    spec_failure_indicator = "✗"

spec_skipped_indicator

spec_skipped_indicator

You can configure the indicator displated when test is skipped.

ini-file

    ; since pytest 4.6.x
    [pytest]
    spec_skipped_indicator = »

    ; legacy pytest
    [tool:pytest]
    spec_skipped_indicator = »

or pyproject.toml

    [tool.pytest.ini_options]
    spec_skipped_indicator = "»"

spec_ignore

spec_ignore

Comma-separated settings to ignore/hide some tests or output from from plugins like FLAKE8 or ISORT. Any test which contain provided string will be ignored in output spec.

ini-file

    ; since pytest 4.6.x
    [pytest]
    spec_ignore = FLAKE8

    ; legacy pytest
    [tool:pytest]
    spec_ignore = FLAKE8

or pyproject.toml

    [tool.pytest.ini_options]
    spec_ignore = "FLAKE8"

spec_indent

spec_indent

ini-file

    ; since pytest 4.6.x
    [pytest]
    spec_indent = "   "

    ; legacy pytest
    [tool:pytest]
    spec_indent = "   "

or pyproject.toml

    [tool.pytest.ini_options]
    spec_indent = "   "

Continuous Integration

Download

All versions of library are available on official pypi server.

Install

From pypi.org

    pip install pytest-spec

From source

    cd pytest-spec
    uv sync

From source for testing

    cd pytest-spec
    uv sync --all-extras --dev

From source for build or deployment

    cd pytest-spec
    uv sync
    uv build
    uv publish

Contribution

Please feel free to present your idea by code example (pull request) or reported issues.

Contributors

• @0x64746b
• @lucasmarshall
• @amcgregor
• @jhermann
• @frenzymadness
• @chrischambers
• @maxalbert
• @jayvdb
• @hugovk
• @b0g3r
• @paxcodes
• @s-t-e-v-e-n-k
• @yk-kd
• @benfairless
• @damienflament
• @joshuaprior

License

pytest-spec - pytest plugin to display test execution output like a SPECIFICATION.

Copyright (C) 2014-2026 Pawel Chomicki

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.