Merge pull request #12552 from anntzer/imagecomparisondocs

jklymak · web-flow · commit 2622bf47ad4a · 2018-11-05T15:50:30.000-08:00
Update docs for writing image comparison tests.
diff --git a/doc/devel/testing.rst b/doc/devel/testing.rst
@@ -143,60 +143,40 @@ The seed is John Hunter's birthday.
 Writing an image comparison test
 --------------------------------
 
-Writing an image based test is only slightly more difficult than a
-simple test. The main consideration is that you must specify the
-"baseline", or expected, images in the
-:func:`~matplotlib.testing.decorators.image_comparison` decorator. For
-example, this test generates a single image and automatically tests it::
-
-  import numpy as np
-  import matplotlib
-  from matplotlib.testing.decorators import image_comparison
-  import matplotlib.pyplot as plt
-
-  @image_comparison(baseline_images=['spines_axes_positions'],
-                    extensions=['png'])
-  def test_spines_axes_positions():
-      # SF bug 2852168
-      fig = plt.figure()
-      x = np.linspace(0,2*np.pi,100)
-      y = 2*np.sin(x)
-      ax = fig.add_subplot(1,1,1)
-      ax.set_title('centered spines')
-      ax.plot(x,y)
-      ax.spines['right'].set_position(('axes',0.1))
-      ax.yaxis.set_ticks_position('right')
-      ax.spines['top'].set_position(('axes',0.25))
-      ax.xaxis.set_ticks_position('top')
-      ax.spines['left'].set_color('none')
-      ax.spines['bottom'].set_color('none')
-
-The first time this test is run, there will be no baseline image to
-compare against, so the test will fail.  Copy the output images (in
-this case `result_images/test_category/spines_axes_positions.png`) to
-the correct subdirectory of `baseline_images` tree in the source
-directory (in this case
-`lib/matplotlib/tests/baseline_images/test_category`).  Put this new
-file under source code revision control (with `git add`).  When
-rerunning the tests, they should now pass.
-
-The :func:`~matplotlib.testing.decorators.image_comparison` decorator
-defaults to generating ``png``, ``pdf`` and ``svg`` output, but in
-interest of keeping the size of the library from ballooning we should only
-include the ``svg`` or ``pdf`` outputs if the test is explicitly exercising
-a feature dependent on that backend.
-
-There are two optional keyword arguments to the `image_comparison`
-decorator:
-
-- `extensions`: If you only wish to test additional image formats (rather than
-  just `png`), pass any additional file types in the list of the extensions to
-  test.  When copying the new baseline files be sure to only copy the output
-  files, not their conversions to ``png``.  For example only copy the files
-  ending in ``pdf``, not in ``_pdf.png``.
-
-- `tol`: This is the image matching tolerance, the default `1e-3`. If some
-  variation is expected in the image between runs, this value may be adjusted.
+Writing an image-based test is only slightly more difficult than a simple
+test. The main consideration is that you must specify the "baseline", or
+expected, images in the `~matplotlib.testing.decorators.image_comparison`
+decorator. For example, this test generates a single image and automatically
+tests it::
+
+   from matplotlib.testing.decorators import image_comparison
+   import matplotlib.pyplot as plt
+
+   @image_comparison(baseline_images=['line_dashes'], remove_text=True,
+                     extensions=['png'])
+   def test_line_dashes():
+       fig, ax = plt.subplots()
+       ax.plot(range(10), linestyle=(0, (3, 3)), lw=5)
+
+The first time this test is run, there will be no baseline image to compare
+against, so the test will fail.  Copy the output images (in this case
+:file:`result_images/test_lines/test_line_dashes.png`) to the correct
+subdirectory of :file:`baseline_images` tree in the source directory (in this
+case :file:`lib/matplotlib/tests/baseline_images/test_lines`).  Put this new
+file under source code revision control (with ``git add``).  When rerunning
+the tests, they should now pass.
+
+Baseline images take a lot of space in the Matplotlib repository.
+An alternative approach for image comparison tests is to use the
+`~matplotlib.testing.decorators.check_figures_equal` decorator, which should be
+used to decorate a function taking two `Figure` parameters and draws the same
+images on the figures using two different methods (the tested method and the
+baseline method).  The decorator will arrange for setting up the figures and
+then collect the drawn results and compare them.
+
+See the documentation of `~matplotlib.testing.decorators.image_comparison` and
+`~matplotlib.testing.decorators.check_figures_equal` for additional information
+about their use.
 
 Known failing tests
 -------------------
diff --git a/lib/matplotlib/testing/decorators.py b/lib/matplotlib/testing/decorators.py
@@ -348,8 +348,8 @@ def image_comparison(baseline_images, extensions=None, tol=0,
                      style='_classic_test'):
     """
     Compare images generated by the test with those specified in
-    *baseline_images*, which must correspond else an
-    ImageComparisonFailure exception will be raised.
+    *baseline_images*, which must correspond, else an `ImageComparisonFailure`
+    exception will be raised.
 
     Arguments
     ---------
@@ -361,10 +361,15 @@ def image_comparison(baseline_images, extensions=None, tol=0,
         either as a parameter or with `pytest.mark.usefixtures`. This value is
         only allowed when using pytest.
 
-    extensions : [ None | list ]
+    extensions : None or list of str
+        The list of extensions to test, e.g. ``['png', 'pdf']``.
 
-        If None, defaults to all supported extensions.
-        Otherwise, a list of extensions to test, e.g. ``['png', 'pdf']``.
+        If *None*, defaults to all supported extensions: png, pdf, and svg.
+
+        In order to keep the size of the test suite from ballooning, we only
+        include the ``svg`` or ``pdf`` outputs if the test is explicitly
+        exercising a feature dependent on that backend (see also the
+        `check_figures_equal` decorator for that purpose).
 
     tol : float, optional, default: 0
         The RMS threshold above which the test is considered failed.
@@ -374,7 +379,10 @@ def image_comparison(baseline_images, extensions=None, tol=0,
         pass.
 
     remove_text : bool
-        Remove the title and tick text from the figure before comparison.
+        Remove the title and tick text from the figure before comparison.  This
+        is useful to make the baseline images independent of variations in text
+        rendering between different versions of FreeType.
+
         This does not remove other, more deliberate, text, such as legends and
         annotations.
 
@@ -418,12 +426,25 @@ def check_figures_equal(*, extensions=("png", "pdf", "svg"), tol=0):
     and draw the test and reference images on them.  After the function
     returns, the figures are saved and compared.
 
+    This decorator should be preferred over `image_comparison` when possible in
+    order to keep the size of the test suite from ballooning.
+
     Arguments
     ---------
     extensions : list, default: ["png", "pdf", "svg"]
         The extensions to test.
     tol : float
         The RMS threshold above which the test is considered failed.
+
+    Examples
+    --------
+    Check that calling `Axes.plot` with a single argument plots it against
+    ``[0, 1, 2, ...]``::
+
+        @check_figures_equal()
+        def test_plot(fig_test, fig_ref):
+            fig_test.subplots().plot([1, 3, 5])
+            fig_ref.subplots().plot([0, 1, 2], [1, 3, 5])
     """
 
     def decorator(func):
