Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 2622bf4

Browse filesBrowse files
jklymakjklymak
authored
Merge pull request #12552 from anntzer/imagecomparisondocs
Update docs for writing image comparison tests.
2 parents 8f969d1 + 96f97fa commit 2622bf4
Copy full SHA for 2622bf4

File tree

Expand file treeCollapse file tree

2 files changed

+61
-60
lines changed
Filter options
Expand file treeCollapse file tree

2 files changed

+61
-60
lines changed

‎doc/devel/testing.rst

Copy file name to clipboardExpand all lines: doc/devel/testing.rst
+34-54Lines changed: 34 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -143,60 +143,40 @@ The seed is John Hunter's birthday.
143143
Writing an image comparison test
144144
--------------------------------
145145

146-
Writing an image based test is only slightly more difficult than a
147-
simple test. The main consideration is that you must specify the
148-
"baseline", or expected, images in the
149-
:func:`~matplotlib.testing.decorators.image_comparison` decorator. For
150-
example, this test generates a single image and automatically tests it::
151-
152-
import numpy as np
153-
import matplotlib
154-
from matplotlib.testing.decorators import image_comparison
155-
import matplotlib.pyplot as plt
156-
157-
@image_comparison(baseline_images=['spines_axes_positions'],
158-
extensions=['png'])
159-
def test_spines_axes_positions():
160-
# SF bug 2852168
161-
fig = plt.figure()
162-
x = np.linspace(0,2*np.pi,100)
163-
y = 2*np.sin(x)
164-
ax = fig.add_subplot(1,1,1)
165-
ax.set_title('centered spines')
166-
ax.plot(x,y)
167-
ax.spines['right'].set_position(('axes',0.1))
168-
ax.yaxis.set_ticks_position('right')
169-
ax.spines['top'].set_position(('axes',0.25))
170-
ax.xaxis.set_ticks_position('top')
171-
ax.spines['left'].set_color('none')
172-
ax.spines['bottom'].set_color('none')
173-
174-
The first time this test is run, there will be no baseline image to
175-
compare against, so the test will fail. Copy the output images (in
176-
this case `result_images/test_category/spines_axes_positions.png`) to
177-
the correct subdirectory of `baseline_images` tree in the source
178-
directory (in this case
179-
`lib/matplotlib/tests/baseline_images/test_category`). Put this new
180-
file under source code revision control (with `git add`). When
181-
rerunning the tests, they should now pass.
182-
183-
The :func:`~matplotlib.testing.decorators.image_comparison` decorator
184-
defaults to generating ``png``, ``pdf`` and ``svg`` output, but in
185-
interest of keeping the size of the library from ballooning we should only
186-
include the ``svg`` or ``pdf`` outputs if the test is explicitly exercising
187-
a feature dependent on that backend.
188-
189-
There are two optional keyword arguments to the `image_comparison`
190-
decorator:
191-
192-
- `extensions`: If you only wish to test additional image formats (rather than
193-
just `png`), pass any additional file types in the list of the extensions to
194-
test. When copying the new baseline files be sure to only copy the output
195-
files, not their conversions to ``png``. For example only copy the files
196-
ending in ``pdf``, not in ``_pdf.png``.
197-
198-
- `tol`: This is the image matching tolerance, the default `1e-3`. If some
199-
variation is expected in the image between runs, this value may be adjusted.
146+
Writing an image-based test is only slightly more difficult than a simple
147+
test. The main consideration is that you must specify the "baseline", or
148+
expected, images in the `~matplotlib.testing.decorators.image_comparison`
149+
decorator. For example, this test generates a single image and automatically
150+
tests it::
151+
152+
from matplotlib.testing.decorators import image_comparison
153+
import matplotlib.pyplot as plt
154+
155+
@image_comparison(baseline_images=['line_dashes'], remove_text=True,
156+
extensions=['png'])
157+
def test_line_dashes():
158+
fig, ax = plt.subplots()
159+
ax.plot(range(10), linestyle=(0, (3, 3)), lw=5)
160+
161+
The first time this test is run, there will be no baseline image to compare
162+
against, so the test will fail. Copy the output images (in this case
163+
:file:`result_images/test_lines/test_line_dashes.png`) to the correct
164+
subdirectory of :file:`baseline_images` tree in the source directory (in this
165+
case :file:`lib/matplotlib/tests/baseline_images/test_lines`). Put this new
166+
file under source code revision control (with ``git add``). When rerunning
167+
the tests, they should now pass.
168+
169+
Baseline images take a lot of space in the Matplotlib repository.
170+
An alternative approach for image comparison tests is to use the
171+
`~matplotlib.testing.decorators.check_figures_equal` decorator, which should be
172+
used to decorate a function taking two `Figure` parameters and draws the same
173+
images on the figures using two different methods (the tested method and the
174+
baseline method). The decorator will arrange for setting up the figures and
175+
then collect the drawn results and compare them.
176+
177+
See the documentation of `~matplotlib.testing.decorators.image_comparison` and
178+
`~matplotlib.testing.decorators.check_figures_equal` for additional information
179+
about their use.
200180

201181
Known failing tests
202182
-------------------

‎lib/matplotlib/testing/decorators.py

Copy file name to clipboardExpand all lines: lib/matplotlib/testing/decorators.py
+27-6Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -348,8 +348,8 @@ def image_comparison(baseline_images, extensions=None, tol=0,
348348
style='_classic_test'):
349349
"""
350350
Compare images generated by the test with those specified in
351-
*baseline_images*, which must correspond else an
352-
ImageComparisonFailure exception will be raised.
351+
*baseline_images*, which must correspond, else an `ImageComparisonFailure`
352+
exception will be raised.
353353
354354
Arguments
355355
---------
@@ -361,10 +361,15 @@ def image_comparison(baseline_images, extensions=None, tol=0,
361361
either as a parameter or with `pytest.mark.usefixtures`. This value is
362362
only allowed when using pytest.
363363
364-
extensions : [ None | list ]
364+
extensions : None or list of str
365+
The list of extensions to test, e.g. ``['png', 'pdf']``.
365366
366-
If None, defaults to all supported extensions.
367-
Otherwise, a list of extensions to test, e.g. ``['png', 'pdf']``.
367+
If *None*, defaults to all supported extensions: png, pdf, and svg.
368+
369+
In order to keep the size of the test suite from ballooning, we only
370+
include the ``svg`` or ``pdf`` outputs if the test is explicitly
371+
exercising a feature dependent on that backend (see also the
372+
`check_figures_equal` decorator for that purpose).
368373
369374
tol : float, optional, default: 0
370375
The RMS threshold above which the test is considered failed.
@@ -374,7 +379,10 @@ def image_comparison(baseline_images, extensions=None, tol=0,
374379
pass.
375380
376381
remove_text : bool
377-
Remove the title and tick text from the figure before comparison.
382+
Remove the title and tick text from the figure before comparison. This
383+
is useful to make the baseline images independent of variations in text
384+
rendering between different versions of FreeType.
385+
378386
This does not remove other, more deliberate, text, such as legends and
379387
annotations.
380388
@@ -418,12 +426,25 @@ def check_figures_equal(*, extensions=("png", "pdf", "svg"), tol=0):
418426
and draw the test and reference images on them. After the function
419427
returns, the figures are saved and compared.
420428
429+
This decorator should be preferred over `image_comparison` when possible in
430+
order to keep the size of the test suite from ballooning.
431+
421432
Arguments
422433
---------
423434
extensions : list, default: ["png", "pdf", "svg"]
424435
The extensions to test.
425436
tol : float
426437
The RMS threshold above which the test is considered failed.
438+
439+
Examples
440+
--------
441+
Check that calling `Axes.plot` with a single argument plots it against
442+
``[0, 1, 2, ...]``::
443+
444+
@check_figures_equal()
445+
def test_plot(fig_test, fig_ref):
446+
fig_test.subplots().plot([1, 3, 5])
447+
fig_ref.subplots().plot([0, 1, 2], [1, 3, 5])
427448
"""
428449

429450
def decorator(func):

0 commit comments

Comments
0 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.