``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
Raw data
{
"_id": null,
"home_page": "https://github.com/matplotlib/pytest-mpl",
"name": "pytest-mpl",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Thomas Robitaille",
"author_email": "thomas.robitaille@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/a9/81/636f9ea4ec0182abc0ab96e5abeab39fc1d9ce8fecf19e2943d685de519f/pytest-mpl-0.17.0.tar.gz",
"platform": null,
"description": "``pytest-mpl``\n==============\n\n``pytest-mpl`` is a `pytest <https://docs.pytest.org>`__ plugin to facilitate image comparison for `Matplotlib <http://www.matplotlib.org>`__ figures.\n\nFor each figure to test, an image is generated and then subtracted from an existing reference image.\nIf the RMS of the residual is larger than a user-specified tolerance, the test will fail.\nAlternatively, the generated image can be hashed and compared to an expected value.\n\nFor more information, see the `pytest-mpl documentation <https://pytest-mpl.readthedocs.io>`__.\n\nInstallation\n------------\n.. code-block:: bash\n\n pip install pytest-mpl\n\nFor detailed instructions, see the `installation guide <https://pytest-mpl.readthedocs.io/en/latest/installing.html>`__ in the ``pytest-mpl`` docs.\n\nUsage\n-----\nFirst, write test functions that create a figure.\nThese image comparison tests are decorated with ``@pytest.mark.mpl_image_compare`` and return the figure for testing:\n\n.. code-block:: python\n\n import matplotlib.pyplot as plt\n import pytest\n\n @pytest.mark.mpl_image_compare\n def test_plot():\n fig, ax = plt.subplots()\n ax.plot([1, 2])\n return fig\n\nThen, generate reference images by running the test suite with the ``--mpl-generate-path`` option:\n\n.. code-block:: bash\n\n pytest --mpl-generate-path=baseline\n\nThen, run the test suite as usual, but pass ``--mpl`` to compare the returned figures to the reference images:\n\n.. code-block:: bash\n\n pytest --mpl\n\nBy also passing ``--mpl-generate-summary=html``, a summary of the image comparison results will be generated in HTML format:\n\n+---------------+---------------+---------------+\n| |html all| | |html filter| | |html result| |\n+---------------+---------------+---------------+\n\nFor more information on how to configure and use ``pytest-mpl``, see the `pytest-mpl documentation <https://pytest-mpl.readthedocs.io>`__.\n\nContributing\n------------\n``pytest-mpl`` is a community project maintained for and by its users.\nThere are many ways you can help!\n\n- Report a bug or request a feature `on GitHub <https://github.com/matplotlib/pytest-mpl/issues>`__\n- Improve the documentation or code\n\n.. |html all| image:: docs/images/html_all.png\n.. |html filter| image:: docs/images/html_filter.png\n.. |html result| image:: docs/images/html_result.png\n",
"bugtrack_url": null,
"license": "BSD",
"summary": "pytest plugin to help with testing figures output from Matplotlib",
"version": "0.17.0",
"project_urls": {
"Homepage": "https://github.com/matplotlib/pytest-mpl"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f3323b5d6973cc8bdc320736ee608377e2756b1042ed162ca2d2ee5555f2d117",
"md5": "471a568d98da0fc59b8e65ee810b35c0",
"sha256": "2ee7cf902ef071e45ae14fe190b3d8a9839c2fd8933e0514bf58df310d8ed66b"
},
"downloads": -1,
"filename": "pytest_mpl-0.17.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "471a568d98da0fc59b8e65ee810b35c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 27555,
"upload_time": "2024-02-14T20:12:03",
"upload_time_iso_8601": "2024-02-14T20:12:03.504826Z",
"url": "https://files.pythonhosted.org/packages/f3/32/3b5d6973cc8bdc320736ee608377e2756b1042ed162ca2d2ee5555f2d117/pytest_mpl-0.17.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a981636f9ea4ec0182abc0ab96e5abeab39fc1d9ce8fecf19e2943d685de519f",
"md5": "5c021e0c9715eb2e8dc73739ec734ee8",
"sha256": "fbef05d7e664b4b33452fb698ac188e522791f327de34e7ea37dbdfe9d52cac6"
},
"downloads": -1,
"filename": "pytest-mpl-0.17.0.tar.gz",
"has_sig": false,
"md5_digest": "5c021e0c9715eb2e8dc73739ec734ee8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 885613,
"upload_time": "2024-02-14T20:12:05",
"upload_time_iso_8601": "2024-02-14T20:12:05.711542Z",
"url": "https://files.pythonhosted.org/packages/a9/81/636f9ea4ec0182abc0ab96e5abeab39fc1d9ce8fecf19e2943d685de519f/pytest-mpl-0.17.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-14 20:12:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "matplotlib",
"github_project": "pytest-mpl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "pytest-mpl"
}
JSON
