<divid="unreleased-message"> You are reading an old version of the documentation (v3.2.2). For the latest version see <ahref="https://matplotlib.org/stable/api/testing_api.html">https://matplotlib.org/stable/api/testing_api.html</a></div>
<h1><codeclass="docutils literal notranslate"><spanclass="pre">matplotlib.testing</span></code><aclass="headerlink" href="#matplotlib-testing" title="Permalink to this headline">¶</a></h1>
<divclass="section" id="id1">
<h2><aclass="reference internal" href="#module-matplotlib.testing" title="matplotlib.testing"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.testing</span></code></a><aclass="headerlink" href="#id1" title="Permalink to this headline">¶</a></h2>
<spanclass="target" id="module-matplotlib.testing"></span><p>Helper functions for testing.</p>
<dlclass="py function">
<dtid="matplotlib.testing.is_called_from_pytest">
<codeclass="descclassname">matplotlib.testing.</code><codeclass="descname">is_called_from_pytest</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing.html#is_called_from_pytest"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.is_called_from_pytest" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>] Whether we are in a pytest run.</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified deprecated">Deprecated since version 3.2.</span></p>
<codeclass="descclassname">matplotlib.testing.</code><codeclass="descname">set_font_settings_for_testing</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing.html#set_font_settings_for_testing"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.set_font_settings_for_testing" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib.testing.</code><codeclass="descname">set_reproducibility_for_testing</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing.html#set_reproducibility_for_testing"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.set_reproducibility_for_testing" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py function">
<dtid="matplotlib.testing.setup">
<codeclass="descclassname">matplotlib.testing.</code><codeclass="descname">setup</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing.html#setup"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.setup" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib.testing.compare.</code><codeclass="descname">comparable_formats</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/compare.html#comparable_formats"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.compare.comparable_formats" title="Permalink to this definition">¶</a></dt>
<dd><p>Return the list of file formats that <aclass="reference internal" href="#matplotlib.testing.compare.compare_images" title="matplotlib.testing.compare.compare_images"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">compare_images</span></code></a> can compare
<codeclass="descclassname">matplotlib.testing.compare.</code><codeclass="descname">compare_images</code><spanclass="sig-paren">(</span><em><spanclass="n">expected</span></em>, <em><spanclass="n">actual</span></em>, <em><spanclass="n">tol</span></em>, <em><spanclass="n">in_decorator</span><spanclass="o">=</span><spanclass="default_value">False</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/compare.html#compare_images"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.compare.compare_images" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare two "image" files checking differences within a tolerance.</p>
<p>The two given filenames may point to files which are convertible to
PNG via the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">converter</span></code> dictionary. The underlying RMS is calculated
with the <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">calculate_rms</span></code> function.</p>
<dt><strong>expected</strong><spanclass="classifier">str</span></dt><dd><p>The filename of the expected image.</p>
</dd>
<dt><strong>actual</strong><spanclass="classifier">str</span></dt><dd><p>The filename of the actual image.</p>
</dd>
<dt><strong>tol</strong><spanclass="classifier">float</span></dt><dd><p>The tolerance (a color value difference, where 255 is the
maximal difference). The test fails if the average pixel
difference is greater than this value.</p>
</dd>
<dt><strong>in_decorator</strong><spanclass="classifier">bool</span></dt><dd><p>Determines the output format. If called from image_comparison
decorator, this should be True. (default=False)</p>
</dd>
</dl>
</td>
</tr>
<trclass="field-even field"><thclass="field-name">Returns:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>comparison_result</strong><spanclass="classifier">None or dict or str</span></dt><dd><p>Return <em>None</em> if the images are equal within the given tolerance.</p>
<p>If the images differ, the return value depends on <em>in_decorator</em>.
If <em>in_decorator</em> is true, a dict with the following entries is
returned:</p>
<ulclass="simple">
<li><em>rms</em>: The RMS of the image difference.</li>
<li><em>expected</em>: The filename of the expected image.</li>
<li><em>actual</em>: The filename of the actual image.</li>
<li><em>diff_image</em>: The filename of the difference image.</li>
<li><em>tol</em>: The comparison tolerance.</li>
</ul>
<p>Otherwise, a human-readable multi-line string representation of this
<emclass="property">class </em><codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">CleanupTestCase</code><spanclass="sig-paren">(</span><em><spanclass="n">methodName</span><spanclass="o">=</span><spanclass="default_value">'runTest'</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#CleanupTestCase"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTestCase" title="Permalink to this definition">¶</a></dt>
<emclass="property">classmethod </em><codeclass="descname">setUpClass</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#CleanupTestCase.setUpClass"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTestCase.setUpClass" title="Permalink to this definition">¶</a></dt>
<dd><p>Hook method for setting up class fixture before running tests in the class.</p>
<emclass="property">classmethod </em><codeclass="descname">tearDownClass</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#CleanupTestCase.tearDownClass"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTestCase.tearDownClass" title="Permalink to this definition">¶</a></dt>
<dd><p>Hook method for deconstructing the class fixture after running all tests in the class.</p>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">check_figures_equal</code><spanclass="sig-paren">(</span><em><spanclass="o">*</span></em>, <em><spanclass="n">extensions</span><spanclass="o">=</span><spanclass="default_value">'png', 'pdf', 'svg'</span></em>, <em><spanclass="n">tol</span><spanclass="o">=</span><spanclass="default_value">0</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#check_figures_equal"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.check_figures_equal" title="Permalink to this definition">¶</a></dt>
<dd><p>Decorator for test cases that generate and compare two figures.</p>
<p>The decorated function must take two keyword arguments, <em>fig_test</em>
and <em>fig_ref</em>, and draw the test and reference images on them.
After the function returns, the figures are saved and compared.</p>
<p>This decorator should be preferred over <aclass="reference internal" href="#matplotlib.testing.decorators.image_comparison" title="matplotlib.testing.decorators.image_comparison"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">image_comparison</span></code></a> when possible in
order to keep the size of the test suite from ballooning.</p>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>extensions</strong><spanclass="classifier">list, default: ["png", "pdf", "svg"]</span></dt><dd><p>The extensions to test.</p>
</dd>
<dt><strong>tol</strong><spanclass="classifier">float</span></dt><dd><p>The RMS threshold above which the test is considered failed.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Examples</p>
<p>Check that calling <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Axes.plot</span></code> with a single argument plots it against
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">check_freetype_version</code><spanclass="sig-paren">(</span><em><spanclass="n">ver</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#check_freetype_version"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.check_freetype_version" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dlclass="py function">
<dtid="matplotlib.testing.decorators.cleanup">
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">cleanup</code><spanclass="sig-paren">(</span><em><spanclass="n">style</span><spanclass="o">=</span><spanclass="default_value">None</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#cleanup"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.cleanup" title="Permalink to this definition">¶</a></dt>
<dd><p>A decorator to ensure that any global state is reset before
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>style</strong><spanclass="classifier">str, dict, or list, optional</span></dt><dd><p>The style(s) to apply. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">["classic",</span>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">image_comparison</code><spanclass="sig-paren">(</span><em><spanclass="n">baseline_images</span></em>, <em><spanclass="n">extensions</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">tol</span><spanclass="o">=</span><spanclass="default_value">0</span></em>, <em><spanclass="n">freetype_version</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">remove_text</span><spanclass="o">=</span><spanclass="default_value">False</span></em>, <em><spanclass="n">savefig_kwarg</span><spanclass="o">=</span><spanclass="default_value">None</span></em>, <em><spanclass="n">style</span><spanclass="o">=</span><spanclass="default_value">'classic', '_classic_test_patch'</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#image_comparison"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.image_comparison" title="Permalink to this definition">¶</a></dt>
<dd><p>Compare images generated by the test with those specified in
<em>baseline_images</em>, which must correspond, else an <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">ImageComparisonFailure</span></code>
<trclass="field-odd field"><thclass="field-name">Parameters:</th><tdclass="field-body"><dlclass="first last docutils">
<dt><strong>baseline_images</strong><spanclass="classifier">list or None</span></dt><dd><p>A list of strings specifying the names of the images generated by
calls to <codeclass="xref py py-meth docutils literal notranslate"><spanclass="pre">matplotlib.figure.savefig()</span></code>.</p>
<p>If <em>None</em>, the test function must use the <codeclass="docutils literal notranslate"><spanclass="pre">baseline_images</span></code> fixture,
either as a parameter or with <codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pytest.mark.usefixtures</span></code>. This value is
only allowed when using pytest.</p>
</dd>
<dt><strong>extensions</strong><spanclass="classifier">None or list of str</span></dt><dd><p>The list of extensions to test, e.g. <codeclass="docutils literal notranslate"><spanclass="pre">['png',</span><spanclass="pre">'pdf']</span></code>.</p>
<p>If <em>None</em>, defaults to all supported extensions: png, pdf, and svg.</p>
<p>When testing a single extension, it can be directly included in the
names passed to <em>baseline_images</em>. In that case, <em>extensions</em> must not
be set.</p>
<p>In order to keep the size of the test suite from ballooning, we only
include the <codeclass="docutils literal notranslate"><spanclass="pre">svg</span></code> or <codeclass="docutils literal notranslate"><spanclass="pre">pdf</span></code> outputs if the test is explicitly
exercising a feature dependent on that backend (see also the
<aclass="reference internal" href="#matplotlib.testing.decorators.check_figures_equal" title="matplotlib.testing.decorators.check_figures_equal"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">check_figures_equal</span></code></a> decorator for that purpose).</p>
</dd>
<dt><strong>tol</strong><spanclass="classifier">float, optional, default: 0</span></dt><dd><p>The RMS threshold above which the test is considered failed.</p>
</dd>
<dt><strong>freetype_version</strong><spanclass="classifier">str or tuple</span></dt><dd><p>The expected freetype version or range of versions for this test to
pass.</p>
</dd>
<dt><strong>remove_text</strong><spanclass="classifier">bool</span></dt><dd><p>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.</p>
<p>This does not remove other, more deliberate, text, such as legends and
annotations.</p>
</dd>
<dt><strong>savefig_kwarg</strong><spanclass="classifier">dict</span></dt><dd><p>Optional arguments that are passed to the savefig method.</p>
</dd>
<dt><strong>style</strong><spanclass="classifier">str, dict, or list</span></dt><dd><p>The optional style(s) to apply to the image test. The test itself
can also apply additional styles if desired. Defaults to <codeclass="docutils literal notranslate"><spanclass="pre">["classic",</span>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">remove_ticks_and_titles</code><spanclass="sig-paren">(</span><em><spanclass="n">figure</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#remove_ticks_and_titles"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.remove_ticks_and_titles" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">switch_backend</code><spanclass="sig-paren">(</span><em><spanclass="n">backend</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#switch_backend"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.switch_backend" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>]</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified deprecated">Deprecated since version 3.1: </span></p>
<emclass="property">exception </em><codeclass="descclassname">matplotlib.testing.exceptions.</code><codeclass="descname">ImageComparisonFailure</code><aclass="reference internal" href="../_modules/matplotlib/testing/exceptions.html#ImageComparisonFailure"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.exceptions.ImageComparisonFailure" title="Permalink to this definition">¶</a></dt>