1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
|
Metadata-Version: 2.1
Name: pytest-mpl
Version: 0.17.0
Summary: pytest plugin to help with testing figures output from Matplotlib
Home-page: https://github.com/matplotlib/pytest-mpl
Author: Thomas Robitaille
Author-email: thomas.robitaille@gmail.com
License: BSD
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: BSD License
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: pytest
Requires-Dist: matplotlib
Requires-Dist: importlib_resources; python_version < "3.8"
Requires-Dist: packaging
Requires-Dist: Jinja2
Requires-Dist: Pillow
Provides-Extra: test
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: mpl_sphinx_theme>=3.6.0.dev0; extra == "docs"
Requires-Dist: sphinx_design; extra == "docs"
Requires-Dist: matplotlib==3.6; extra == "docs"
``pytest-mpl``
==============
``pytest-mpl`` is a `pytest <https://docs.pytest.org>`__ plugin to facilitate image comparison for `Matplotlib <http://www.matplotlib.org>`__ 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 <https://pytest-mpl.readthedocs.io>`__.
Installation
------------
.. code-block:: bash
pip install pytest-mpl
For detailed instructions, see the `installation guide <https://pytest-mpl.readthedocs.io/en/latest/installing.html>`__ 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 <https://pytest-mpl.readthedocs.io>`__.
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 <https://github.com/matplotlib/pytest-mpl/issues>`__
- 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
|
