pytest-mpl

Warnings

• breaking When testing figures within classes, hash library test names generated prior to v0.16.0 will be incompatible. You must regenerate or update baseline image names to include the class name.
  Fix: Regenerate your hash library or update baseline image filenames to incorporate the class name for affected tests. Refer to the v0.16.0 release notes for details.
• gotcha Tests marked with `@pytest.mark.mpl_image_compare` will only perform image comparison if pytest is run with the `--mpl` command-line option. Without this flag, the tests will execute, but only basic assertions (e.g., that the code runs without error) will be checked, not the visual output.
  Fix: Always run pytest with `pytest --mpl` to enable image comparison for marked tests. Consider adding `--mpl` to your `pytest.ini` `addopts` for consistent behavior.
• gotcha Baseline images or hash libraries must be explicitly generated before running image comparison tests. Tests will fail if no reference images/hashes exist or if they are not found in the expected location.
  Fix: Generate baseline images using `pytest --mpl-generate-path=your_baseline_dir` or a hash library with `pytest --mpl-generate-hash-library=your_hash_library.json`. Store these baselines in a consistent, version-controlled location.
• gotcha When a test marked with `mpl_image_compare` returns a figure, `pytest` versions 7.2 and higher may emit a `PytestReturnNotNoneWarning` if `pytest-mpl` is not properly installed or configured, which could become an exception in future `pytest` releases. Ensure `pytest-mpl` is correctly installed and activated.
  Fix: Verify `pytest-mpl` is installed (`pip install pytest-mpl`) and that pytest is loading it (check `pytest --trace-config`). `pytest-mpl` has added compatibility for `pytest 7` and `pytest 8.1` in recent versions.
• gotcha Matplotlib's rendering can sometimes exhibit minor differences across different operating systems, Python versions, or specific backend configurations (e.g., font rendering). While `pytest-mpl` aims for robustness, ensure your baseline generation environment closely matches your testing environment for cross-platform consistency if this is a concern.
  Fix: Generate and test baselines in a consistent CI/CD environment or a Docker container to minimize environmental variations. Adjust the `tolerance` parameter in `@pytest.mark.mpl_image_compare` if minor, acceptable differences occur.

Install

• pip install pytest-mpl Install latest version

Imports

• mpl_image_compare

  import pytest
  
  @pytest.mark.mpl_image_compare

  The core decorator to mark a test function for Matplotlib image comparison.

Quickstart

This example defines a basic pytest function that creates a Matplotlib figure and returns it. The `@pytest.mark.mpl_image_compare` decorator instructs pytest-mpl to compare the generated figure against a baseline. The commands below the code show how to generate initial baseline images and how to run the comparison tests. Ensure a directory named 'baseline_images' (or your chosen path) exists next to your test file.

import matplotlib.pyplot as plt
import pytest

@pytest.mark.mpl_image_compare
def test_simple_plot():
    fig, ax = plt.subplots()
    ax.plot([1, 2, 3], [4, 5, 6])
    ax.set_title("A simple line plot")
    return fig

# To generate baseline images (run once or when figures change):
# pytest --mpl-generate-path=baseline_images

# To run tests and compare against baselines:
# pytest --mpl