https://github.com/matplotlib/pytest-mpl

A pytest plugin to facilitate image comparison for Matplotlib figures
https://github.com/matplotlib/pytest-mpl

Last synced: 10 days 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 (over 9 years ago)
• Default Branch: main
• Last Pushed: 2024-10-07T18:19:22.000Z (about 1 month ago)
• Last Synced: 2024-10-29T14:21:53.963Z (15 days ago)
• Language: Python
• Homepage:
• Size: 2.53 MB
• Stars: 243
• Watchers: 15
• Forks: 47
• Open Issues: 40
• 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