https://github.com/matplotlib/pytest-mpl
A pytest plugin to facilitate image comparison for Matplotlib figures
https://github.com/matplotlib/pytest-mpl
Last synced: about 1 month ago
JSON representation
A pytest plugin to facilitate image comparison for Matplotlib figures
- Host: GitHub
- URL: https://github.com/matplotlib/pytest-mpl
- Owner: matplotlib
- License: other
- Created: 2015-06-25T15:09:39.000Z (about 10 years ago)
- Default Branch: main
- Last Pushed: 2025-05-26T21:57:11.000Z (about 2 months ago)
- Last Synced: 2025-06-08T12:28:36.884Z (about 1 month ago)
- Language: Python
- Homepage:
- Size: 2.53 MB
- Stars: 253
- Watchers: 14
- Forks: 48
- Open Issues: 47
-
Metadata Files:
- Readme: README.rst
- Changelog: CHANGES.md
- License: LICENSE
Awesome Lists containing this project
README
``pytest-mpl``
==============
``pytest-mpl`` is a `pytest `__ plugin to facilitate image comparison for `Matplotlib `__ figures.
For each figure to test, an image is generated and then subtracted from an existing reference image.
If the RMS of the residual is larger than a user-specified tolerance, the test will fail.
Alternatively, the generated image can be hashed and compared to an expected value.
For more information, see the `pytest-mpl documentation `__.
Installation
------------
.. code-block:: bash
pip install pytest-mpl
For detailed instructions, see the `installation guide `__ in the ``pytest-mpl`` docs.
Usage
-----
First, write test functions that create a figure.
These image comparison tests are decorated with ``@pytest.mark.mpl_image_compare`` and return the figure for testing:
.. code-block:: python
import matplotlib.pyplot as plt
import pytest
@pytest.mark.mpl_image_compare
def test_plot():
fig, ax = plt.subplots()
ax.plot([1, 2])
return fig
Then, generate reference images by running the test suite with the ``--mpl-generate-path`` option:
.. code-block:: bash
pytest --mpl-generate-path=baseline
Then, run the test suite as usual, but pass ``--mpl`` to compare the returned figures to the reference images:
.. code-block:: bash
pytest --mpl
By also passing ``--mpl-generate-summary=html``, a summary of the image comparison results will be generated in HTML format:
+---------------+---------------+---------------+
| |html all| | |html filter| | |html result| |
+---------------+---------------+---------------+
For more information on how to configure and use ``pytest-mpl``, see the `pytest-mpl documentation `__.
Contributing
------------
``pytest-mpl`` is a community project maintained for and by its users.
There are many ways you can help!
- Report a bug or request a feature `on GitHub `__
- Improve the documentation or code
.. |html all| image:: docs/images/html_all.png
.. |html filter| image:: docs/images/html_filter.png
.. |html result| image:: docs/images/html_result.png