Describe how to test regular installations of Matplotlib

timhoffm · timhoffm · commit f7f578c05ed0 · 2021-01-24T00:43:23.000+01:00
diff --git a/INSTALL.rst b/INSTALL.rst
@@ -38,26 +38,6 @@ Although not required, we suggest also installing ``IPython`` for
 interactive use.  To easily install a complete Scientific Python
 stack, see :ref:`install_scipy_dists` below.
 
-Test data
----------
-
-The wheels (:file:`*.whl`) on the `PyPI download page
-<https://pypi.org/project/matplotlib/>`_ do not contain test data
-or example code.
-
-If you want to try the many demos that come in the Matplotlib source
-distribution, download the :file:`*.tar.gz` file and look in the
-:file:`examples` subdirectory.
-
-To run the test suite:
-
-* extract the :file:`lib/matplotlib/tests` or :file:`lib/mpl_toolkits/tests`
-  directories from the source distribution.
-* install test dependencies: `pytest <https://pypi.org/project/pytest>`_,
-  MiKTeX, GhostScript, ffmpeg, avconv, ImageMagick, and `Inkscape
-  <https://inkscape.org/>`_.
-* run ``python -mpytest``.
-
 Third-party distributions of Matplotlib
 =======================================
 
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -225,3 +225,50 @@ you may (rarely) need to build very old versions of Matplotlib.  The following
 constraints need to be taken into account:
 
 - Matplotlib 1.3 (or earlier) requires numpy 1.8 (or earlier).
+
+Testing regular installations of Matplotlib
+-------------------------------------------
+
+.. note::
+
+   There is usually no need to run the tests on regular installations of
+   Matplotlib.  Official releases are tested before publishing.
+
+While rarely needed, it is possible to run the tests on a regular installation
+of matplotlib. To do so you need to set up additional dependencies and the
+reference images.
+
+Install additional dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Install the :ref:`additional dependencies for testing <test-dependencies>`.
+
+Obtain the reference images
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Many tests compare the plot result against reference images. The reference
+images are not part of the regular packaged versions (wheels or conda
+packages). If you want to run tests with reference images, you need to obtain
+the reference images matching the version of Matplotlib you want to test.
+
+To do so, either download the matching source distribution
+``matplotlib-X.Y.Z.tar.gz`` from `PyPI <https://pypi.org/project/matplotlib/>`_
+or alternatively, clone the git repository and ``git checkout vX.Y.Z``. Copy
+the folder :file:`lib/matplotlib/tests/baseline_images` to the folder
+:file:`matplotlib/tests` of your the matplotlib installation to test.
+The correct target folder can be found using::
+
+    python -c "import matplotlib.tests; print(matplotlib.tests.__file__.rsplit('/', 1)[0])"
+
+An analogous copying of :file:`lib/mpl_toolkits/tests/baseline_images`
+is necessary for testing the :ref:`toolkits`.
+
+Run the tests
+^^^^^^^^^^^^^
+To run the all the tests on your installed version of Matplotlib::
+
+    pytest --pyargs matplotlib.tests
+
+The test discovery scope can be narrowed to single test modules or even single
+functions::
+
+    pytest --pyargs matplotlib.tests.test_simplification.py::test_clipping
+
