pytest-ruff

0.5 · active · verified Thu Apr 16

pytest-ruff is a pytest plugin designed to integrate Ruff's powerful linting and formatting checks directly into your test suite. It automatically runs `ruff format --check` and `ruff check` as part of your `pytest` execution, failing tests if any Ruff requirements are not met. The current version is 0.5, and it maintains a consistent release cadence with updates addressing bug fixes and new features.

Common errors

```
pytest: error: unrecognized arguments: --show-source
```
cause The `--show-source` CLI argument was removed in `pytest-ruff v0.4.0` in favor of `--output-format`.

fix Replace `--show-source` with `--output-format=full` (or `concise`) in your pytest command or configuration.
```
F401 'your_fixture_name' imported but unused
```
cause Ruff's unused import checker (F401) is flagging a pytest fixture that is imported but not directly referenced in the test body. This can happen with implicitly used fixtures.

fix If the fixture is correctly used by pytest, add `# noqa: F401` to the import line. For better clarity and to avoid the warning, consider defining fixtures in `conftest.py` or using `@pytest.mark.usefixtures('your_fixture_name')` on your test function.
```
RuffConfigError: Failed to load Ruff configuration from [...]
```
cause pytest-ruff encountered an issue parsing your Ruff configuration (e.g., in `pyproject.toml` or `ruff.toml`). This could be due to syntax errors or invalid options in the configuration file.

fix Review your Ruff configuration file for any syntax errors or invalid settings. Refer to the official Ruff documentation for valid configuration options and structure. The error message should provide more details on the specific parsing failure.

Warnings

breaking The `--show-source` CLI argument for controlling source code snippets in Ruff's output was replaced by `--output-format` in `pytest-ruff v0.4.0`. Using the old flag will result in an 'unrecognized arguments' error.
Fix: Update your pytest command or configuration to use `--output-format` instead of `--show-source`. For example, `pytest --ruff --output-format=full`.
gotcha In versions prior to `v0.2.1`, the `--ruff` and `--ruff-format` flags might not have worked independently or as expected, potentially leading to inconsistent behavior.
Fix: Upgrade to `pytest-ruff v0.2.1` or newer to ensure `--ruff` and `--ruff-format` operate as distinct checks as intended.
gotcha Tests generated by `pytest-ruff` (and similar quality assurance plugins) might not always respect pytest's `-k` expression for selecting a subset of tests. This means Ruff checks could run even when you're trying to target specific functional tests, potentially slowing down development in large projects.
Fix: Be aware that `-k` might not skip Ruff checks. If this is a significant performance bottleneck, consider running Ruff separately via `ruff check .` and `ruff format --check .` outside of your `pytest` invocation for focused test runs.
gotcha Ruff's `F401` (unused import) rule can sometimes incorrectly flag imported pytest fixtures as unused, especially if the fixtures are imported but not directly called in the test function body (e.g., when relying on implicit fixture injection).
Fix: You can add `# noqa: F401` to the line importing the fixture if you're sure it's being used implicitly by pytest. Alternatively, consider using `conftest.py` for shared fixtures or `pytest.mark.usefixtures()` for fixtures whose return value isn't directly consumed to make the dependency explicit and potentially avoid the `F401` warning.

Install

pip install pytest-ruff Install latest version

Imports

pytest-ruff

This is a pytest plugin and does not typically require direct Python imports in user code. Its functionality is enabled via pytest command-line arguments.

Users interact with pytest-ruff primarily through pytest CLI flags like `--ruff` and `--ruff-format`, not via Python import statements.

Quickstart

To quickly verify `pytest-ruff` is working, create a `pyproject.toml` to configure Ruff and a `test_example.py` file with a deliberate Ruff violation. Then, run pytest with the `--ruff` flag. The test suite should report a failure originating from the Ruff check.

# Save as pyproject.toml
[tool.ruff]
# By default, Ruff enables 'E' (pycodestyle errors) and 'F' (Pyflakes rules).
# Ensure these are active or extend with your desired rules.
select = ["E", "F"]

# Save as test_example.py
def test_linting_violation():
    x = 1; y = 2  # E702: Multiple statements on one line (will be flagged by Ruff)
    assert x < y

# Run from your terminal in the same directory:
# pytest --ruff
# Expected output will show a failure due to the E702 Ruff violation.

view raw JSON →