<divid="unreleased-message"> You are reading an old version of the documentation (v3.4.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="matplotlib-test">
<h2><aclass="reference internal" href="#matplotlib.test" title="matplotlib.test"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">matplotlib.test()</span></code></a><aclass="headerlink" href="#matplotlib-test" title="Permalink to this headline">¶</a></h2>
<dlclass="py function">
<dtid="matplotlib.test">
<codeclass="descclassname">matplotlib.</code><codeclass="descname">test</code><spanclass="sig-paren">(</span><em>verbosity=None</em>, <em>coverage=False</em>, <em>*</em>, <em>recursionlimit=<deprecated parameter></em>, <em>**kwargs</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib.html#test"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.test" title="Permalink to this definition">¶</a></dt>
<dd><p>Run the matplotlib test suite.</p>
</dd></dl>
</div>
<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>
<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>
<spanid="matplotlib-testing-compare"></span><h2><aclass="reference internal" href="#module-matplotlib.testing.compare" title="matplotlib.testing.compare"><codeclass="xref py py-mod docutils literal notranslate"><spanclass="pre">matplotlib.testing.compare</span></code></a><aclass="headerlink" href="#module-matplotlib.testing.compare" title="Permalink to this headline">¶</a></h2>
<p>Utilities for comparing image results.</p>
<dlclass="py function">
<dtid="matplotlib.testing.compare.calculate_rms">
<codeclass="descclassname">matplotlib.testing.compare.</code><codeclass="descname">calculate_rms</code><spanclass="sig-paren">(</span><em><spanclass="n">expected_image</span></em>, <em><spanclass="n">actual_image</span></em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/compare.html#calculate_rms"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.compare.calculate_rms" title="Permalink to this definition">¶</a></dt>
<dd><p>Calculate the per-pixel errors, then compute the root mean square error.</p>
<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 <aclass="reference internal" href="#matplotlib.testing.compare.calculate_rms" title="matplotlib.testing.compare.calculate_rms"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">calculate_rms</span></code></a> function.</p>
<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>
<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>
<trclass="field-even field"><thclass="field-name">Raises:</th><tdclass="field-body"><dlclass="first last docutils">
<dt>RuntimeError</dt><dd><p>If any new figures are created (and not subsequently closed) inside
the test function.</p>
</dd>
</dl>
</td>
</tr>
</tbody>
</table>
<pclass="rubric">Examples</p>
<p>Check that calling <aclass="reference internal" href="_as_gen/matplotlib.axes.Axes.plot.html#matplotlib.axes.Axes.plot" title="matplotlib.axes.Axes.plot"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">Axes.plot</span></code></a> 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
<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 <aclass="reference external" href="https://pytest.org/en/stable/reference.html#pytest.mark.usefixtures" title="(in pytest v6.2.4)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">pytest.mark.usefixtures</span></code></a>. 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, default: 0</span></dt><dd><p>The RMS threshold above which the test is considered failed.</p>
<p>Due to expected small differences in floating-point calculations, on
32-bit systems an additional 0.06 is added to this threshold.</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>
<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>