pytest-examples

0.0.18 · active · verified Mon Apr 13

pytest-examples is a pytest plugin designed for testing Python code examples found within docstrings and markdown files. It can lint these code examples using tools like ruff and black, run them to verify their correctness, and even check if print statements are inlined as expected. The library is currently at version 0.0.18 and follows an active development and release cadence, often aligning with its upstream `pytest` and `pydantic` projects.

Warnings

gotcha pytest-examples's features (running, linting, updating examples) are enabled via command-line flags (e.g., `--py-examples`, `--update-examples`). Simply installing the plugin does not automatically activate these checks; you must explicitly include the relevant flags when running `pytest`.
Fix: Always run `pytest` with `--py-examples` to enable example testing. Add `--update-examples` if you intend to format or update print statements in place.
gotcha When using the `--update-examples` flag, `pytest-examples` can modify your source files (e.g., to format code or insert/update print statement outputs). It's crucial to understand this behavior to avoid unintended changes, especially in CI/CD environments or when working with version control.
Fix: Review changes carefully after running `pytest --update-examples`. Consider running without `--update-examples` first to see only report failures, then with it only when explicit updates are desired. Use version control to track and revert unwanted changes.
gotcha pytest-examples relies on `pytest`'s test discovery mechanism. If your docstrings or markdown files are not discovered, or if the code within them cannot be correctly parsed or executed by Python, `pytest-examples` might not report issues as expected or might encounter its own errors during collection.
Fix: Ensure your example code is valid Python syntax. For docstrings, follow standard Python docstring conventions. For markdown, clearly delineate code blocks (e.g., using ````py`). Verify `pytest`'s overall test discovery is working as expected in your project setup.

Install

pip install pytest-examples Install stable version

Imports

pytest
```
import pytest
```
pytest-examples operates as a pytest plugin; its functionalities are typically enabled via pytest configuration or command-line flags, rather than direct Python imports from pytest_examples itself in test files. Users will commonly import pytest for writing their tests.

Quickstart

To use `pytest-examples`, ensure it is installed alongside `pytest`. The plugin automatically discovers code examples in docstrings (like the `add_two_things` function above) and markdown files. You typically invoke `pytest` with specific flags to enable `pytest-examples`'s features. The `--py-examples` flag enables example collection and running, and `--update-examples` enables in-place updates for formatting and print statement checks.

import pytest

# my_lib.py (example code to be tested)
def add_two_things(a, b):
    """
    Adds two things.

    >>> add_two_things(1, 2)
    3
    """
    return a + b

# test_my_lib.py (pytest test file)
def test_add_two_things_example():
    # This test primarily ensures pytest-examples is installed and discoverable.
    # The actual testing of examples is done by running `pytest`.
    pass

# To run tests and check examples:
# 1. Save the above code into 'my_lib.py' and 'test_my_lib.py'
# 2. Run from your terminal in the same directory: pytest --py-examples
# 3. To lint and run, and optionally update: pytest --py-examples --update-examples

view raw JSON →