<divid="unreleased-message"> You are reading an old version of the documentation (v3.1.3). 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="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>
<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="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">compare_images</code><spanclass="sig-paren">(</span><em>expected</em>, <em>actual</em>, <em>tol</em>, <em>in_decorator=False</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>
<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
<emclass="property">class </em><codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">CleanupTest</code><spanclass="sig-paren">(</span><em>**kwargs</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#CleanupTest"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTest" title="Permalink to this definition">¶</a></dt>
<emclass="property">classmethod </em><codeclass="descname">setup_class</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTest.setup_class" title="Permalink to this definition">¶</a></dt>
<emclass="property">classmethod </em><codeclass="descname">teardown_class</code><spanclass="sig-paren">(</span><spanclass="sig-paren">)</span><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTest.teardown_class" title="Permalink to this definition">¶</a></dt>
<codeclass="descname">test</code><spanclass="sig-paren">(</span><em>self</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#CleanupTest.test"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.CleanupTest.test" title="Permalink to this definition">¶</a></dt>
<emclass="property">class </em><codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">CleanupTestCase</code><spanclass="sig-paren">(</span><em>methodName='runTest'</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>
<emclass="property">class </em><codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">ImageComparisonTest</code><spanclass="sig-paren">(</span><em>**kwargs</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#ImageComparisonTest"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.ImageComparisonTest" title="Permalink to this definition">¶</a></dt>
<p>This class generates tests for a nose-based testing framework. Ideally,
this class would not be public, and the only publicly visible API would
be the <aclass="reference internal" href="#matplotlib.testing.decorators.image_comparison" title="matplotlib.testing.decorators.image_comparison"><codeclass="xref py py-func docutils literal notranslate"><spanclass="pre">image_comparison()</span></code></a> decorator. Unfortunately, there are
existing downstream users of this class (e.g., pytest-mpl) so it cannot yet
be removed.</p>
<pclass="rubric">Notes</p>
<divclass="deprecated">
<p><spanclass="versionmodified">Deprecated since version 3.0.</span></p>
<codeclass="descname">nose_runner</code><spanclass="sig-paren">(</span><em>self</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#ImageComparisonTest.nose_runner"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.ImageComparisonTest.nose_runner" title="Permalink to this definition">¶</a></dt>
<codeclass="descname">setup</code><spanclass="sig-paren">(</span><em>self</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#ImageComparisonTest.setup"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.ImageComparisonTest.setup" title="Permalink to this definition">¶</a></dt>
<codeclass="descname">teardown</code><spanclass="sig-paren">(</span><em>self</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#ImageComparisonTest.teardown"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.ImageComparisonTest.teardown" title="Permalink to this definition">¶</a></dt>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">check_figures_equal</code><spanclass="sig-paren">(</span><em>*</em>, <em>extensions=('png'</em>, <em>'pdf'</em>, <em>'svg')</em>, <em>tol=0</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 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>
<dd><pclass="first last">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>ver</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="function">
<dtid="matplotlib.testing.decorators.cleanup">
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">cleanup</code><spanclass="sig-paren">(</span><em>style=None</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
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">image_comparison</code><spanclass="sig-paren">(</span><em>baseline_images</em>, <em>extensions=None</em>, <em>tol=0</em>, <em>freetype_version=None</em>, <em>remove_text=False</em>, <em>savefig_kwarg=None</em>, <em>style='_classic_test'</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-delimiter">:</span><spanclass="classifier">list or None</span></dt>
<dd><pclass="first">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>
<pclass="last">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-delimiter">:</span><spanclass="classifier">None or list of str</span></dt>
<dd><pclass="first">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>
<pclass="last">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>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">remove_ticks_and_titles</code><spanclass="sig-paren">(</span><em>figure</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">skip_if_command_unavailable</code><spanclass="sig-paren">(</span><em>cmd</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/decorators.html#skip_if_command_unavailable"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.decorators.skip_if_command_unavailable" title="Permalink to this definition">¶</a></dt>
<dd><p>[<em>Deprecated</em>] skips a test if a command is unavailable.</p>
<codeclass="descclassname">matplotlib.testing.decorators.</code><codeclass="descname">switch_backend</code><spanclass="sig-paren">(</span><em>backend</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 since version 3.1: </span></p>
<codeclass="descclassname">matplotlib.testing.disable_internet.</code><codeclass="descname">check_internet_off</code><spanclass="sig-paren">(</span><em>original_function</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/disable_internet.html#check_internet_off"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.disable_internet.check_internet_off" title="Permalink to this definition">¶</a></dt>
<dd><p>Wraps <codeclass="docutils literal notranslate"><spanclass="pre">original_function</span></code>, which in most cases is assumed
to be a <aclass="reference external" href="https://docs.python.org/3/library/socket.html#socket.socket" title="(in Python v3.8)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">socket.socket</span></code></a> method, to raise an <aclass="reference external" href="https://docs.python.org/3/library/exceptions.html#IOError" title="(in Python v3.8)"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">IOError</span></code></a> for any operations
<codeclass="descclassname">matplotlib.testing.disable_internet.</code><codeclass="descname">no_internet</code><spanclass="sig-paren">(</span><em>verbose=False</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/disable_internet.html#no_internet"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.disable_internet.no_internet" title="Permalink to this definition">¶</a></dt>
<dd><p>Context manager to temporarily disable internet access (if not already
disabled). If it was already disabled before entering the context manager
(i.e. <aclass="reference internal" href="#matplotlib.testing.disable_internet.turn_off_internet" title="matplotlib.testing.disable_internet.turn_off_internet"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">turn_off_internet</span></code></a> was called previously) then this is a no-op and
leaves internet access disabled until a manual call to <aclass="reference internal" href="#matplotlib.testing.disable_internet.turn_on_internet" title="matplotlib.testing.disable_internet.turn_on_internet"><codeclass="xref py py-obj docutils literal notranslate"><spanclass="pre">turn_on_internet</span></code></a>.</p>
<codeclass="descclassname">matplotlib.testing.disable_internet.</code><codeclass="descname">turn_off_internet</code><spanclass="sig-paren">(</span><em>verbose=False</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/disable_internet.html#turn_off_internet"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.disable_internet.turn_off_internet" title="Permalink to this definition">¶</a></dt>
<dd><p>Disable internet access via python by preventing connections from being
created using the socket module. Presumably this could be worked around by
using some other means of accessing the internet, but all default python
modules (urllib, requests, etc.) use socket [citation needed].</p>
<codeclass="descclassname">matplotlib.testing.disable_internet.</code><codeclass="descname">turn_on_internet</code><spanclass="sig-paren">(</span><em>verbose=False</em><spanclass="sig-paren">)</span><aclass="reference internal" href="../_modules/matplotlib/testing/disable_internet.html#turn_on_internet"><spanclass="viewcode-link">[source]</span></a><aclass="headerlink" href="#matplotlib.testing.disable_internet.turn_on_internet" title="Permalink to this definition">¶</a></dt>
<dd><p>Restore internet access. Not used, but kept in case it is needed.</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>