pytest-black Plugin

0.6.0 · active · verified Thu Apr 16

pytest-black is a pytest plugin that enables code format checking using the 'black' formatter directly within the pytest test suite. It integrates `black` as a linter, failing tests if code is not formatted according to `black`'s standards. The current version is 0.6.0, with releases typically occurring on an annual to bi-annual cadence.

Common errors

```
pytest: error: unrecognized arguments: --black
```
cause The pytest-black plugin is not installed or not correctly recognized by pytest.

fix Ensure `pytest-black` is installed in the active Python environment: `pip install pytest-black`.
```
ModuleNotFoundError: No module named 'black'
```
cause The 'black' formatter package, which pytest-black relies on, is not installed.

fix Install the 'black' formatter: `pip install black`.
```
blackd cannot be used as an executable. Please install blackd to use it.
```
cause pytest-black's default behavior tries to use `blackd` (the black daemon) for faster checks if available, but it's not installed, and the fallback to `black` isn't working as expected.

fix Install `blackd` (`pip install blackd`) or explicitly configure pytest-black to use the `black` executable by setting `--black-executable black`.

Warnings

gotcha pytest-black checks formatting but does NOT automatically reformat code. It merely reports formatting violations.
Fix: To fix formatting, manually run `black .` in your project root after `pytest --black` reports issues.
gotcha The plugin is only active when the `--black` flag is explicitly passed to pytest. Running `pytest` without this flag will not perform any black checks.
Fix: Always use `pytest --black` to enable formatting checks. Consider adding it to your CI/CD pipeline or as a pre-commit hook.
gotcha Ensure that the `black` package itself is installed in the same environment where `pytest` and `pytest-black` are running. `pytest-black` depends on `black` being available.
Fix: Make sure to include `pip install black` alongside `pytest` and `pytest-black` in your setup, e.g., `pip install pytest pytest-black black`.

Install

pip install pytest-black Install stable version

Imports

pytest_black plugin activation
```
Install 'pytest-black' and run 'pytest --black'
```
pytest-black is a pytest plugin that extends pytest's command-line interface. It does not expose Python symbols (classes, functions) for direct import into user test files or application code. Its functionality is primarily controlled via pytest flags.

Quickstart

To quickly start using pytest-black, install the plugin along with black and pytest. Then, simply run pytest with the `--black` flag. pytest-black will check all Python files found by pytest for black compliance. If any files are unformatted, tests will fail.

import pytest

# Create a test file (e.g., test_example.py)
# with some unformatted code:
# def test_hello():
#    print(   'Hello, World!')
#    assert True

# To run:
# 1. Save the above unformatted code in test_example.py
# 2. Run in terminal: pip install pytest-black black pytest
# 3. Run in terminal: pytest --black

# Expected output for unformatted code would include black errors.
# If code is formatted, it would pass without black errors.

view raw JSON →