pytest-spec: Specification-style Test Output

6.0.0 · active · verified Fri Apr 17

pytest-spec is a pytest plugin that transforms the standard test execution output into a clear, human-readable specification format, similar to RSpec or Mocha. It uses test names and docstrings to generate descriptive sentences about test behavior. The current version is 6.0.0, and it follows a release cadence tied to pytest and Python major version updates.

Common errors

```
ModuleNotFoundError: No module named 'pytest_spec'
```
cause The `pytest-spec` package has not been installed in your current Python environment.

fix Run `pip install pytest-spec` to install the plugin.
```
No 'spec' output, just standard pytest dots or progress.
```
cause The `pytest-spec` plugin is either not active, has been explicitly disabled, or is being overridden by another pytest plugin.

fix Ensure `pytest-spec` is installed. Check your `pytest.ini` for `addopts = -p no:spec`. You can run `pytest --trace-config` to see which plugins are loaded. If conflicts exist, try disabling other plugins, e.g., `pytest -p no:another_plugin`.
```
You need to install pytest>=6.0.0 to use this plugin with current Python version.
```
cause You are using an older version of pytest (pre-6.0.0) which is no longer supported by pytest-spec 6.0.0.

fix Upgrade your pytest installation: `pip install 'pytest>=6.0.0,<10.0.0'`.

Warnings

breaking Version 6.0.0 of pytest-spec drops support for Python 3.9. Users on Python 3.9 or older will experience compatibility issues.
Fix: Upgrade your Python environment to 3.10 or newer. For example: `pyenv install 3.10.12 && pyenv local 3.10.12`.
breaking Version 6.0.0 of pytest-spec drops support for pytest 4.x.x and 5.x.x. Running with these older pytest versions will lead to errors or incorrect behavior.
Fix: Upgrade pytest to version 6.0.0 or newer. For example: `pip install 'pytest>=6.0.0,<10.0.0'`.
gotcha For the most descriptive output, leverage docstrings in your test functions and methods. pytest-spec uses these to generate more readable specification descriptions.
Fix: Add a clear, concise docstring to each test function or method explaining its purpose. Example: `def test_something(): """It should do X when Y."""`.
gotcha If you need to temporarily disable pytest-spec or are experiencing conflicts with other plugins, you can disable it directly from the command line.
Fix: Run pytest with `pytest -p no:spec` to disable the plugin for that specific run. You can also add `addopts = -p no:spec` to your `pytest.ini` to disable it project-wide.

Install

pip install pytest-spec Install pytest-spec

Quickstart

Create a test file (e.g., `test_example.py`) and simply run `pytest` from your terminal after installation. pytest-spec automatically modifies the output.

# test_example.py
import pytest

def test_feature_login_successful():
    """When valid credentials are provided, it should allow a user to log in successfully."""
    assert True

def test_feature_login_failed():
    """When invalid credentials are provided, it should deny access and show an error."""
    assert False

@pytest.mark.parametrize("input, expected", [("hello", "HELLO"), ("world", "WORLD")])
def test_string_uppercase_conversion(input, expected):
    """It should correctly convert a given string to uppercase."""
    assert input.upper() == expected

# To run these tests with pytest-spec, simply navigate to the directory
# containing `test_example.py` in your terminal and run:
# pytest

view raw JSON →