Team Ai
Apppublic

parthtamu/rag-code-assistant

sourceHugging Faceupdated 7mo agoView on Hugging Face
0likes
test.html2274 linesDownload Raw Back to docs
1<!DOCTYPE html>2 3<html lang="en" data-content_root="../">4  <head>5    <meta charset="utf-8" />6    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />7<meta property="og:title" content="test — Regression tests package for Python" />8<meta property="og:type" content="website" />9<meta property="og:url" content="https://docs.python.org/3/library/test.html" />10<meta property="og:site_name" content="Python documentation" />11<meta property="og:description" content="The test package contains all regression tests for Python as well as the modules test.support and test.regrtest. test.support is used to enhance your tests while test.regrtest drives the testing su..." />12<meta property="og:image:width" content="1146" />13<meta property="og:image:height" content="600" />14<meta property="og:image" content="https://docs.python.org/3.15/_images/social_previews/summary_library_test_e9cd7467.png" />15<meta property="og:image:alt" content="The test package contains all regression tests for Python as well as the modules test.support and test.regrtest. test.support is used to enhance your tests while test.regrtest drives the testing su..." />16<meta name="description" content="The test package contains all regression tests for Python as well as the modules test.support and test.regrtest. test.support is used to enhance your tests while test.regrtest drives the testing su..." />17<meta name="twitter:card" content="summary_large_image" />18<meta name="theme-color" content="#3776ab">19 20    <title>test — Regression tests package for Python &#8212; Python 3.15.0a6 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">21    22    <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=b86133f3" />23    <link rel="stylesheet" type="text/css" href="../_static/classic.css?v=234b1a7c" />24    <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=89a2f22a" />25    <link rel="stylesheet" type="text/css" href="../_static/profiling-sampling-visualization.css?v=0c2600ae" />26    <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=5349f25f" />27    28    <script src="../_static/documentation_options.js?v=6b7c9ff5"></script>29    <script src="../_static/doctools.js?v=9bcbadda"></script>30    <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>31    <script src="../_static/profiling-sampling-visualization.js?v=9811ed04"></script>32    33    <script src="../_static/sidebar.js"></script>34    35    <link rel="search" type="application/opensearchdescription+xml"36          title="Search within Python 3.15.0a6 documentation"37          href="../_static/opensearch.xml"/>38    <link rel="author" title="About these documents" href="../about.html" />39    <link rel="index" title="Index" href="../genindex.html" />40    <link rel="search" title="Search" href="../search.html" />41    <link rel="copyright" title="Copyright" href="../copyright.html" />42    <link rel="next" title="Debugging and profiling" href="debug.html" />43    <link rel="prev" title="unittest.mock — getting started" href="unittest.mock-examples.html" />44    45      46      <script defer file-types="bz2,epub,zip" data-domain="docs.python.org" src="https://analytics.python.org/js/script.file-downloads.outbound-links.js"></script>47      48      <link rel="canonical" href="https://docs.python.org/3/library/test.html">49      50    51 52    53    <style>54      @media only screen {55        table.full-width-table {56            width: 100%;57        }58      }59    </style>60<link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">61    <link rel="shortcut icon" type="image/png" href="../_static/py.svg">62            <script type="text/javascript" src="../_static/copybutton.js"></script>63            <script type="text/javascript" src="../_static/menu.js"></script>64            <script type="text/javascript" src="../_static/search-focus.js"></script>65            <script type="text/javascript" src="../_static/themetoggle.js"></script> 66            <script type="text/javascript" src="../_static/rtd_switcher.js"></script>67            <meta name="readthedocs-addons-api-version" content="1">68 69  </head>70<body>71<div class="mobile-nav">72    <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"73           aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu">74    <nav class="nav-content" role="navigation">75        <label for="menuToggler" class="toggler__label">76            <span></span>77        </label>78        <span class="nav-items-wrapper">79            <a href="https://www.python.org/" class="nav-logo">80                <img src="../_static/py.svg" alt="Python logo">81            </a>82            <span class="version_switcher_placeholder"></span>83            <form role="search" class="search" action="../search.html" method="get">84                <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">85                    <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>86                </svg>87                <input placeholder="Quick search" aria-label="Quick search" type="search" name="q">88                <input type="submit" value="Go">89            </form>90        </span>91    </nav>92    <div class="menu-wrapper">93        <nav class="menu" role="navigation" aria-label="main navigation">94            <div class="language_switcher_placeholder"></div>95            96<label class="theme-selector-label">97    Theme98    <select class="theme-selector" oninput="activateTheme(this.value)">99        <option value="auto" selected>Auto</option>100        <option value="light">Light</option>101        <option value="dark">Dark</option>102    </select>103</label>104  <div>105    <h3><a href="../contents.html">Table of Contents</a></h3>106    <ul>107<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> — Regression tests package for Python</a><ul>108<li><a class="reference internal" href="#writing-unit-tests-for-the-test-package">Writing Unit Tests for the <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package</a></li>109<li><a class="reference internal" href="#module-test.regrtest">Running tests using the command-line interface</a></li>110</ul>111</li>112<li><a class="reference internal" href="#module-test.support"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> — Utilities for the Python test suite</a></li>113<li><a class="reference internal" href="#module-test.support.socket_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.socket_helper</span></code> — Utilities for socket tests</a></li>114<li><a class="reference internal" href="#module-test.support.script_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.script_helper</span></code> — Utilities for the Python execution tests</a></li>115<li><a class="reference internal" href="#module-test.support.bytecode_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.bytecode_helper</span></code> — Support tools for testing correct bytecode generation</a></li>116<li><a class="reference internal" href="#module-test.support.threading_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.threading_helper</span></code> — Utilities for threading tests</a></li>117<li><a class="reference internal" href="#module-test.support.os_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.os_helper</span></code> — Utilities for os tests</a></li>118<li><a class="reference internal" href="#module-test.support.import_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.import_helper</span></code> — Utilities for import tests</a></li>119<li><a class="reference internal" href="#module-test.support.warnings_helper"><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support.warnings_helper</span></code> — Utilities for warnings tests</a></li>120</ul>121 122  </div>123  <div>124    <h4>Previous topic</h4>125    <p class="topless"><a href="unittest.mock-examples.html"126                          title="previous chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest.mock</span></code> — getting started</a></p>127  </div>128  <div>129    <h4>Next topic</h4>130    <p class="topless"><a href="debug.html"131                          title="next chapter">Debugging and profiling</a></p>132  </div>133  <script>134    document.addEventListener('DOMContentLoaded', () => {135        const title = document.querySelector('meta[property="og:title"]').content;136        const elements = document.querySelectorAll('.improvepage');137        const pageurl = window.location.href.split('?')[0];138        elements.forEach(element => {139            const url = new URL(element.href.split('?')[0].replace("-nojs", ""));140            url.searchParams.set('pagetitle', title);141            url.searchParams.set('pageurl', pageurl);142            url.searchParams.set('pagesource', "library/test.rst");143            element.href = url.toString();144        });145    });146  </script>147  <div role="note" aria-label="source link">148    <h3>This page</h3>149    <ul class="this-page-menu">150      <li><a href="../bugs.html">Report a bug</a></li>151      <li><a class="improvepage" href="../improve-page-nojs.html">Improve this page</a></li>152      <li>153        <a href="https://github.com/python/cpython/blob/main/Doc/library/test.rst?plain=1"154            rel="nofollow">Show source155        </a>156      </li>157      158    </ul>159  </div>160        </nav>161    </div>162</div>163 164  165    <div class="related" role="navigation" aria-label="Related">166      <h3>Navigation</h3>167      <ul>168        <li class="right" style="margin-right: 10px">169          <a href="../genindex.html" title="General Index"170             accesskey="I">index</a></li>171        <li class="right" >172          <a href="../py-modindex.html" title="Python Module Index"173             >modules</a> |</li>174        <li class="right" >175          <a href="debug.html" title="Debugging and profiling"176             accesskey="N">next</a> |</li>177        <li class="right" >178          <a href="unittest.mock-examples.html" title="unittest.mock — getting started"179             accesskey="P">previous</a> |</li>180 181          <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"></li>182          <li><a href="https://www.python.org/">Python</a> &#187;</li>183          <li class="switchers">184            <div class="language_switcher_placeholder"></div>185            <div class="version_switcher_placeholder"></div>186          </li>187          <li>188              189          </li>190    <li id="cpython-language-and-version">191      <a href="../index.html">3.15.0a6 Documentation</a> &#187;192    </li>193 194          <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>195          <li class="nav-item nav-item-2"><a href="development.html" accesskey="U">Development Tools</a> &#187;</li>196        <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> — Regression tests package for Python</a></li>197                <li class="right">198                    199 200    <div class="inline-search" role="search">201        <form class="inline-search" action="../search.html" method="get">202          <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box">203          <input type="submit" value="Go">204        </form>205    </div>206                     |207                </li>208            <li class="right">209<label class="theme-selector-label">210    Theme211    <select class="theme-selector" oninput="activateTheme(this.value)">212        <option value="auto" selected>Auto</option>213        <option value="light">Light</option>214        <option value="dark">Dark</option>215    </select>216</label> |</li>217            218      </ul>219    </div>    220 221    <div class="document">222      <div class="documentwrapper">223        <div class="bodywrapper">224          <div class="body" role="main">225            226  <section id="module-test">227<span id="test-regression-tests-package-for-python"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> — Regression tests package for Python<a class="headerlink" href="#module-test" title="Link to this heading">¶</a></h1>228<div class="admonition note">229<p class="admonition-title">Note</p>230<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package is meant for internal use by Python only. It is231documented for the benefit of the core developers of Python. Any use of232this package outside of Python’s standard library is discouraged as code233mentioned here can change or be removed without notice between releases of234Python.</p>235</div>236<hr class="docutils" />237<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package contains all regression tests for Python as well as the238modules <a class="reference internal" href="#module-test.support" title="test.support: Support for Python's regression test suite."><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code></a> and <a class="reference internal" href="#module-test.regrtest" title="test.regrtest: Drives the regression test suite."><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code></a>.239<code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> is used to enhance your tests while240<code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code> drives the testing suite.</p>241<p>Each module in the <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package whose name starts with <code class="docutils literal notranslate"><span class="pre">test_</span></code> is a242testing suite for a specific module or feature. All new tests should be written243using the <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> or <a class="reference internal" href="doctest.html#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> module.  Some older tests are244written using a “traditional” testing style that compares output printed to245<code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code>; this style of test is considered deprecated.</p>246<div class="admonition seealso">247<p class="admonition-title">See also</p>248<dl class="simple">249<dt>Module <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a></dt><dd><p>Writing PyUnit regression tests.</p>250</dd>251<dt>Module <a class="reference internal" href="doctest.html#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a></dt><dd><p>Tests embedded in documentation strings.</p>252</dd>253</dl>254</div>255<section id="writing-unit-tests-for-the-test-package">256<span id="writing-tests"></span><h2>Writing Unit Tests for the <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package<a class="headerlink" href="#writing-unit-tests-for-the-test-package" title="Link to this heading">¶</a></h2>257<p>It is preferred that tests that use the <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> module follow a few258guidelines. One is to name the test module by starting it with <code class="docutils literal notranslate"><span class="pre">test_</span></code> and end259it with the name of the module being tested. The test methods in the test module260should start with <code class="docutils literal notranslate"><span class="pre">test_</span></code> and end with a description of what the method is261testing. This is needed so that the methods are recognized by the test driver as262test methods. Also, no documentation string for the method should be included. A263comment (such as <code class="docutils literal notranslate"><span class="pre">#</span> <span class="pre">Tests</span> <span class="pre">function</span> <span class="pre">returns</span> <span class="pre">only</span> <span class="pre">True</span> <span class="pre">or</span> <span class="pre">False</span></code>) should be used264to provide documentation for test methods. This is done because documentation265strings get printed out if they exist and thus what test is being run is not266stated.</p>267<p>A basic boilerplate is often used:</p>268<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">unittest</span>269<span class="kn">from</span><span class="w"> </span><span class="nn">test</span><span class="w"> </span><span class="kn">import</span> <span class="n">support</span>270 271<span class="k">class</span><span class="w"> </span><span class="nc">MyTestCase1</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>272 273    <span class="c1"># Only use setUp() and tearDown() if necessary</span>274 275    <span class="k">def</span><span class="w"> </span><span class="nf">setUp</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>276        <span class="o">...</span> <span class="n">code</span> <span class="n">to</span> <span class="n">execute</span> <span class="ow">in</span> <span class="n">preparation</span> <span class="k">for</span> <span class="n">tests</span> <span class="o">...</span>277 278    <span class="k">def</span><span class="w"> </span><span class="nf">tearDown</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>279        <span class="o">...</span> <span class="n">code</span> <span class="n">to</span> <span class="n">execute</span> <span class="n">to</span> <span class="n">clean</span> <span class="n">up</span> <span class="n">after</span> <span class="n">tests</span> <span class="o">...</span>280 281    <span class="k">def</span><span class="w"> </span><span class="nf">test_feature_one</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>282        <span class="c1"># Test feature one.</span>283        <span class="o">...</span> <span class="n">testing</span> <span class="n">code</span> <span class="o">...</span>284 285    <span class="k">def</span><span class="w"> </span><span class="nf">test_feature_two</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>286        <span class="c1"># Test feature two.</span>287        <span class="o">...</span> <span class="n">testing</span> <span class="n">code</span> <span class="o">...</span>288 289    <span class="o">...</span> <span class="n">more</span> <span class="n">test</span> <span class="n">methods</span> <span class="o">...</span>290 291<span class="k">class</span><span class="w"> </span><span class="nc">MyTestCase2</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>292    <span class="o">...</span> <span class="n">same</span> <span class="n">structure</span> <span class="k">as</span> <span class="n">MyTestCase1</span> <span class="o">...</span>293 294<span class="o">...</span> <span class="n">more</span> <span class="n">test</span> <span class="n">classes</span> <span class="o">...</span>295 296<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>297    <span class="n">unittest</span><span class="o">.</span><span class="n">main</span><span class="p">()</span>298</pre></div>299</div>300<p>This code pattern allows the testing suite to be run by <a class="reference internal" href="#module-test.regrtest" title="test.regrtest: Drives the regression test suite."><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code></a>,301on its own as a script that supports the <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> CLI, or via the302<code class="docutils literal notranslate"><span class="pre">python</span> <span class="pre">-m</span> <span class="pre">unittest</span></code> CLI.</p>303<p>The goal for regression testing is to try to break code. This leads to a few304guidelines to be followed:</p>305<ul>306<li><p>The testing suite should exercise all classes, functions, and constants. This307includes not just the external API that is to be presented to the outside308world but also “private” code.</p></li>309<li><p>Whitebox testing (examining the code being tested when the tests are being310written) is preferred. Blackbox testing (testing only the published user311interface) is not complete enough to make sure all boundary and edge cases312are tested.</p></li>313<li><p>Make sure all possible values are tested including invalid ones. This makes314sure that not only all valid values are acceptable but also that improper315values are handled correctly.</p></li>316<li><p>Exhaust as many code paths as possible. Test where branching occurs and thus317tailor input to make sure as many different paths through the code are taken.</p></li>318<li><p>Add an explicit test for any bugs discovered for the tested code. This will319make sure that the error does not crop up again if the code is changed in the320future.</p></li>321<li><p>Make sure to clean up after your tests (such as close and remove all temporary322files).</p></li>323<li><p>If a test is dependent on a specific condition of the operating system then324verify the condition already exists before attempting the test.</p></li>325<li><p>Import as few modules as possible and do it as soon as possible. This326minimizes external dependencies of tests and also minimizes possible anomalous327behavior from side-effects of importing a module.</p></li>328<li><p>Try to maximize code reuse. On occasion, tests will vary by something as small329as what type of input is used. Minimize code duplication by subclassing a330basic test class with a class that specifies the input:</p>331<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">class</span><span class="w"> </span><span class="nc">TestFuncAcceptsSequencesMixin</span><span class="p">:</span>332 333    <span class="n">func</span> <span class="o">=</span> <span class="n">mySuperWhammyFunction</span>334 335    <span class="k">def</span><span class="w"> </span><span class="nf">test_func</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>336        <span class="bp">self</span><span class="o">.</span><span class="n">func</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">arg</span><span class="p">)</span>337 338<span class="k">class</span><span class="w"> </span><span class="nc">AcceptLists</span><span class="p">(</span><span class="n">TestFuncAcceptsSequencesMixin</span><span class="p">,</span> <span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>339    <span class="n">arg</span> <span class="o">=</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span>340 341<span class="k">class</span><span class="w"> </span><span class="nc">AcceptStrings</span><span class="p">(</span><span class="n">TestFuncAcceptsSequencesMixin</span><span class="p">,</span> <span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>342    <span class="n">arg</span> <span class="o">=</span> <span class="s1">&#39;abc&#39;</span>343 344<span class="k">class</span><span class="w"> </span><span class="nc">AcceptTuples</span><span class="p">(</span><span class="n">TestFuncAcceptsSequencesMixin</span><span class="p">,</span> <span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>345    <span class="n">arg</span> <span class="o">=</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">)</span>346</pre></div>347</div>348<p>When using this pattern, remember that all classes that inherit from349<a class="reference internal" href="unittest.html#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a> are run as tests.  The <code class="xref py py-class docutils literal notranslate"><span class="pre">TestFuncAcceptsSequencesMixin</span></code> class in the example above350does not have any data and so can’t be run by itself, thus it does not351inherit from <code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code>.</p>352</li>353</ul>354<div class="admonition seealso">355<p class="admonition-title">See also</p>356<dl class="simple">357<dt>Test Driven Development</dt><dd><p>A book by Kent Beck on writing tests before code.</p>358</dd>359</dl>360</div>361</section>362<section id="module-test.regrtest">363<span id="running-tests-using-the-command-line-interface"></span><span id="regrtest"></span><h2>Running tests using the command-line interface<a class="headerlink" href="#module-test.regrtest" title="Link to this heading">¶</a></h2>364<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package can be run as a script to drive Python’s regression365test suite, thanks to the <a class="reference internal" href="../using/cmdline.html#cmdoption-m"><code class="xref std std-option docutils literal notranslate"><span class="pre">-m</span></code></a> option: <strong class="program">python -m test</strong>. Under366the hood, it uses <code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code>; the call <strong class="program">python -m367test.regrtest</strong> used in previous Python versions still works.  Running the368script by itself automatically starts running all regression tests in the369<code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> package. It does this by finding all modules in the package whose370name starts with <code class="docutils literal notranslate"><span class="pre">test_</span></code>, importing them, and executing the function371<code class="xref py py-func docutils literal notranslate"><span class="pre">test_main()</span></code> if present or loading the tests via372unittest.TestLoader.loadTestsFromModule if <code class="docutils literal notranslate"><span class="pre">test_main</span></code> does not exist.  The373names of tests to execute may also be passed to the script. Specifying a single374regression test (<strong class="program">python -m test test_spam</strong>) will minimize output and375only print whether the test passed or failed.</p>376<p>Running <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> directly allows what resources are available for377tests to use to be set. You do this by using the <code class="docutils literal notranslate"><span class="pre">-u</span></code> command-line378option. Specifying <code class="docutils literal notranslate"><span class="pre">all</span></code> as the value for the <code class="docutils literal notranslate"><span class="pre">-u</span></code> option enables all379possible resources: <strong class="program">python -m test -uall</strong>.380If all but one resource is desired (a more common case), a381comma-separated list of resources that are not desired may be listed after382<code class="docutils literal notranslate"><span class="pre">all</span></code>. The command <strong class="program">python -m test -uall,-audio,-largefile</strong>383will run <code class="xref py py-mod docutils literal notranslate"><span class="pre">test</span></code> with all resources except the <code class="docutils literal notranslate"><span class="pre">audio</span></code> and384<code class="docutils literal notranslate"><span class="pre">largefile</span></code> resources. For a list of all resources and more command-line385options, run <strong class="program">python -m test -h</strong>.</p>386<p>Some other ways to execute the regression tests depend on what platform the387tests are being executed on. On Unix, you can run <strong class="program">make test</strong> at the388top-level directory where Python was built. On Windows,389executing <strong class="program">rt.bat</strong> from your <code class="file docutils literal notranslate"><span class="pre">PCbuild</span></code> directory will run all390regression tests.</p>391<div class="versionadded">392<p><span class="versionmodified added">Added in version 3.14: </span>Output is colorized by default and can be393<a class="reference internal" href="../using/cmdline.html#using-on-controlling-color"><span class="std std-ref">controlled using environment variables</span></a>.</p>394</div>395</section>396</section>397<section id="module-test.support">398<span id="test-support-utilities-for-the-python-test-suite"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> — Utilities for the Python test suite<a class="headerlink" href="#module-test.support" title="Link to this heading">¶</a></h1>399<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> module provides support for Python’s regression400test suite.</p>401<div class="admonition note">402<p class="admonition-title">Note</p>403<p><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> is not a public module.  It is documented here to help404Python developers write tests.  The API of this module is subject to change405without backwards compatibility concerns between releases.</p>406</div>407<p>This module defines the following exceptions:</p>408<dl class="py exception">409<dt class="sig sig-object py" id="test.support.TestFailed">410<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">TestFailed</span></span><a class="headerlink" href="#test.support.TestFailed" title="Link to this definition">¶</a></dt>411<dd><p>Exception to be raised when a test fails. This is deprecated in favor of412<a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a>-based tests and <a class="reference internal" href="unittest.html#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a>’s assertion413methods.</p>414</dd></dl>415 416<dl class="py exception">417<dt class="sig sig-object py" id="test.support.ResourceDenied">418<em class="property"><span class="k"><span class="pre">exception</span></span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">ResourceDenied</span></span><a class="headerlink" href="#test.support.ResourceDenied" title="Link to this definition">¶</a></dt>419<dd><p>Subclass of <a class="reference internal" href="unittest.html#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">unittest.SkipTest</span></code></a>. Raised when a resource (such as a420network connection) is not available. Raised by the <a class="reference internal" href="#test.support.requires" title="test.support.requires"><code class="xref py py-func docutils literal notranslate"><span class="pre">requires()</span></code></a>421function.</p>422</dd></dl>423 424<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> module defines the following constants:</p>425<dl class="py data">426<dt class="sig sig-object py" id="test.support.verbose">427<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">verbose</span></span><a class="headerlink" href="#test.support.verbose" title="Link to this definition">¶</a></dt>428<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> when verbose output is enabled. Should be checked when more429detailed information is desired about a running test. <em>verbose</em> is set by430<a class="reference internal" href="#module-test.regrtest" title="test.regrtest: Drives the regression test suite."><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code></a>.</p>431</dd></dl>432 433<dl class="py data">434<dt class="sig sig-object py" id="test.support.is_jython">435<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_jython</span></span><a class="headerlink" href="#test.support.is_jython" title="Link to this definition">¶</a></dt>436<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if the running interpreter is Jython.</p>437</dd></dl>438 439<dl class="py data">440<dt class="sig sig-object py" id="test.support.is_android">441<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_android</span></span><a class="headerlink" href="#test.support.is_android" title="Link to this definition">¶</a></dt>442<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> is <code class="docutils literal notranslate"><span class="pre">android</span></code>.</p>443</dd></dl>444 445<dl class="py data">446<dt class="sig sig-object py" id="test.support.is_emscripten">447<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_emscripten</span></span><a class="headerlink" href="#test.support.is_emscripten" title="Link to this definition">¶</a></dt>448<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> is <code class="docutils literal notranslate"><span class="pre">emscripten</span></code>.</p>449</dd></dl>450 451<dl class="py data">452<dt class="sig sig-object py" id="test.support.is_wasi">453<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_wasi</span></span><a class="headerlink" href="#test.support.is_wasi" title="Link to this definition">¶</a></dt>454<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> is <code class="docutils literal notranslate"><span class="pre">wasi</span></code>.</p>455</dd></dl>456 457<dl class="py data">458<dt class="sig sig-object py" id="test.support.is_apple_mobile">459<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_apple_mobile</span></span><a class="headerlink" href="#test.support.is_apple_mobile" title="Link to this definition">¶</a></dt>460<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> is <code class="docutils literal notranslate"><span class="pre">ios</span></code>, <code class="docutils literal notranslate"><span class="pre">tvos</span></code>, or <code class="docutils literal notranslate"><span class="pre">watchos</span></code>.</p>461</dd></dl>462 463<dl class="py data">464<dt class="sig sig-object py" id="test.support.is_apple">465<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_apple</span></span><a class="headerlink" href="#test.support.is_apple" title="Link to this definition">¶</a></dt>466<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if <code class="docutils literal notranslate"><span class="pre">sys.platform</span></code> is <code class="docutils literal notranslate"><span class="pre">darwin</span></code> or <code class="docutils literal notranslate"><span class="pre">is_apple_mobile</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>467</dd></dl>468 469<dl class="py data">470<dt class="sig sig-object py" id="test.support.unix_shell">471<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">unix_shell</span></span><a class="headerlink" href="#test.support.unix_shell" title="Link to this definition">¶</a></dt>472<dd><p>Path for shell if not on Windows; otherwise <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>473</dd></dl>474 475<dl class="py data">476<dt class="sig sig-object py" id="test.support.LOOPBACK_TIMEOUT">477<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">LOOPBACK_TIMEOUT</span></span><a class="headerlink" href="#test.support.LOOPBACK_TIMEOUT" title="Link to this definition">¶</a></dt>478<dd><p>Timeout in seconds for tests using a network server listening on the network479local loopback interface like <code class="docutils literal notranslate"><span class="pre">127.0.0.1</span></code>.</p>480<p>The timeout is long enough to prevent test failure: it takes into account481that the client and the server can run in different threads or even482different processes.</p>483<p>The timeout should be long enough for <a class="reference internal" href="socket.html#socket.socket.connect" title="socket.socket.connect"><code class="xref py py-meth docutils literal notranslate"><span class="pre">connect()</span></code></a>,484<a class="reference internal" href="socket.html#socket.socket.recv" title="socket.socket.recv"><code class="xref py py-meth docutils literal notranslate"><span class="pre">recv()</span></code></a> and <a class="reference internal" href="socket.html#socket.socket.send" title="socket.socket.send"><code class="xref py py-meth docutils literal notranslate"><span class="pre">send()</span></code></a> methods of485<a class="reference internal" href="socket.html#socket.socket" title="socket.socket"><code class="xref py py-class docutils literal notranslate"><span class="pre">socket.socket</span></code></a>.</p>486<p>Its default value is 5 seconds.</p>487<p>See also <a class="reference internal" href="#test.support.INTERNET_TIMEOUT" title="test.support.INTERNET_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">INTERNET_TIMEOUT</span></code></a>.</p>488</dd></dl>489 490<dl class="py data">491<dt class="sig sig-object py" id="test.support.INTERNET_TIMEOUT">492<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">INTERNET_TIMEOUT</span></span><a class="headerlink" href="#test.support.INTERNET_TIMEOUT" title="Link to this definition">¶</a></dt>493<dd><p>Timeout in seconds for network requests going to the internet.</p>494<p>The timeout is short enough to prevent a test to wait for too long if the495internet request is blocked for whatever reason.</p>496<p>Usually, a timeout using <code class="xref py py-data docutils literal notranslate"><span class="pre">INTERNET_TIMEOUT</span></code> should not mark a test as497failed, but skip the test instead: see498<a class="reference internal" href="#test.support.socket_helper.transient_internet" title="test.support.socket_helper.transient_internet"><code class="xref py py-func docutils literal notranslate"><span class="pre">transient_internet()</span></code></a>.</p>499<p>Its default value is 1 minute.</p>500<p>See also <a class="reference internal" href="#test.support.LOOPBACK_TIMEOUT" title="test.support.LOOPBACK_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">LOOPBACK_TIMEOUT</span></code></a>.</p>501</dd></dl>502 503<dl class="py data">504<dt class="sig sig-object py" id="test.support.SHORT_TIMEOUT">505<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">SHORT_TIMEOUT</span></span><a class="headerlink" href="#test.support.SHORT_TIMEOUT" title="Link to this definition">¶</a></dt>506<dd><p>Timeout in seconds to mark a test as failed if the test takes “too long”.</p>507<p>The timeout value depends on the regrtest <code class="docutils literal notranslate"><span class="pre">--timeout</span></code> command line option.</p>508<p>If a test using <code class="xref py py-data docutils literal notranslate"><span class="pre">SHORT_TIMEOUT</span></code> starts to fail randomly on slow509buildbots, use <a class="reference internal" href="#test.support.LONG_TIMEOUT" title="test.support.LONG_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">LONG_TIMEOUT</span></code></a> instead.</p>510<p>Its default value is 30 seconds.</p>511</dd></dl>512 513<dl class="py data">514<dt class="sig sig-object py" id="test.support.LONG_TIMEOUT">515<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">LONG_TIMEOUT</span></span><a class="headerlink" href="#test.support.LONG_TIMEOUT" title="Link to this definition">¶</a></dt>516<dd><p>Timeout in seconds to detect when a test hangs.</p>517<p>It is long enough to reduce the risk of test failure on the slowest Python518buildbots. It should not be used to mark a test as failed if the test takes519“too long”.  The timeout value depends on the regrtest <code class="docutils literal notranslate"><span class="pre">--timeout</span></code> command520line option.</p>521<p>Its default value is 5 minutes.</p>522<p>See also <a class="reference internal" href="#test.support.LOOPBACK_TIMEOUT" title="test.support.LOOPBACK_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">LOOPBACK_TIMEOUT</span></code></a>, <a class="reference internal" href="#test.support.INTERNET_TIMEOUT" title="test.support.INTERNET_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">INTERNET_TIMEOUT</span></code></a> and523<a class="reference internal" href="#test.support.SHORT_TIMEOUT" title="test.support.SHORT_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">SHORT_TIMEOUT</span></code></a>.</p>524</dd></dl>525 526<dl class="py data">527<dt class="sig sig-object py" id="test.support.PGO">528<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">PGO</span></span><a class="headerlink" href="#test.support.PGO" title="Link to this definition">¶</a></dt>529<dd><p>Set when tests can be skipped when they are not useful for PGO.</p>530</dd></dl>531 532<dl class="py data">533<dt class="sig sig-object py" id="test.support.PIPE_MAX_SIZE">534<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">PIPE_MAX_SIZE</span></span><a class="headerlink" href="#test.support.PIPE_MAX_SIZE" title="Link to this definition">¶</a></dt>535<dd><p>A constant that is likely larger than the underlying OS pipe buffer size,536to make writes blocking.</p>537</dd></dl>538 539<dl class="py data">540<dt class="sig sig-object py" id="test.support.Py_DEBUG">541<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">Py_DEBUG</span></span><a class="headerlink" href="#test.support.Py_DEBUG" title="Link to this definition">¶</a></dt>542<dd><p><code class="docutils literal notranslate"><span class="pre">True</span></code> if Python was built with the <a class="reference internal" href="../c-api/intro.html#c.Py_DEBUG" title="Py_DEBUG"><code class="xref c c-macro docutils literal notranslate"><span class="pre">Py_DEBUG</span></code></a> macro543defined, that is, if544Python was <a class="reference internal" href="../using/configure.html#debug-build"><span class="std std-ref">built in debug mode</span></a>.</p>545<div class="versionadded">546<p><span class="versionmodified added">Added in version 3.12.</span></p>547</div>548</dd></dl>549 550<dl class="py data">551<dt class="sig sig-object py" id="test.support.SOCK_MAX_SIZE">552<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">SOCK_MAX_SIZE</span></span><a class="headerlink" href="#test.support.SOCK_MAX_SIZE" title="Link to this definition">¶</a></dt>553<dd><p>A constant that is likely larger than the underlying OS socket buffer size,554to make writes blocking.</p>555</dd></dl>556 557<dl class="py data">558<dt class="sig sig-object py" id="test.support.TEST_SUPPORT_DIR">559<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">TEST_SUPPORT_DIR</span></span><a class="headerlink" href="#test.support.TEST_SUPPORT_DIR" title="Link to this definition">¶</a></dt>560<dd><p>Set to the top level directory that contains <code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code>.</p>561</dd></dl>562 563<dl class="py data">564<dt class="sig sig-object py" id="test.support.TEST_HOME_DIR">565<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">TEST_HOME_DIR</span></span><a class="headerlink" href="#test.support.TEST_HOME_DIR" title="Link to this definition">¶</a></dt>566<dd><p>Set to the top level directory for the test package.</p>567</dd></dl>568 569<dl class="py data">570<dt class="sig sig-object py" id="test.support.TEST_DATA_DIR">571<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">TEST_DATA_DIR</span></span><a class="headerlink" href="#test.support.TEST_DATA_DIR" title="Link to this definition">¶</a></dt>572<dd><p>Set to the <code class="docutils literal notranslate"><span class="pre">data</span></code> directory within the test package.</p>573</dd></dl>574 575<dl class="py data">576<dt class="sig sig-object py" id="test.support.MAX_Py_ssize_t">577<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">MAX_Py_ssize_t</span></span><a class="headerlink" href="#test.support.MAX_Py_ssize_t" title="Link to this definition">¶</a></dt>578<dd><p>Set to <a class="reference internal" href="sys.html#sys.maxsize" title="sys.maxsize"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.maxsize</span></code></a> for big memory tests.</p>579</dd></dl>580 581<dl class="py data">582<dt class="sig sig-object py" id="test.support.max_memuse">583<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">max_memuse</span></span><a class="headerlink" href="#test.support.max_memuse" title="Link to this definition">¶</a></dt>584<dd><p>Set by <a class="reference internal" href="#test.support.set_memlimit" title="test.support.set_memlimit"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_memlimit()</span></code></a> as the memory limit for big memory tests.585Limited by <a class="reference internal" href="#test.support.MAX_Py_ssize_t" title="test.support.MAX_Py_ssize_t"><code class="xref py py-data docutils literal notranslate"><span class="pre">MAX_Py_ssize_t</span></code></a>.</p>586</dd></dl>587 588<dl class="py data">589<dt class="sig sig-object py" id="test.support.real_max_memuse">590<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">real_max_memuse</span></span><a class="headerlink" href="#test.support.real_max_memuse" title="Link to this definition">¶</a></dt>591<dd><p>Set by <a class="reference internal" href="#test.support.set_memlimit" title="test.support.set_memlimit"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_memlimit()</span></code></a> as the memory limit for big memory tests.  Not592limited by <a class="reference internal" href="#test.support.MAX_Py_ssize_t" title="test.support.MAX_Py_ssize_t"><code class="xref py py-data docutils literal notranslate"><span class="pre">MAX_Py_ssize_t</span></code></a>.</p>593</dd></dl>594 595<dl class="py data">596<dt class="sig sig-object py" id="test.support.MISSING_C_DOCSTRINGS">597<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">MISSING_C_DOCSTRINGS</span></span><a class="headerlink" href="#test.support.MISSING_C_DOCSTRINGS" title="Link to this definition">¶</a></dt>598<dd><p>Set to <code class="docutils literal notranslate"><span class="pre">True</span></code> if Python is built without docstrings (the599<code class="xref c c-macro docutils literal notranslate"><span class="pre">WITH_DOC_STRINGS</span></code> macro is not defined).600See the <a class="reference internal" href="../using/configure.html#cmdoption-without-doc-strings"><code class="xref std std-option docutils literal notranslate"><span class="pre">configure</span> <span class="pre">--without-doc-strings</span></code></a> option.</p>601<p>See also the <a class="reference internal" href="#test.support.HAVE_DOCSTRINGS" title="test.support.HAVE_DOCSTRINGS"><code class="xref py py-data docutils literal notranslate"><span class="pre">HAVE_DOCSTRINGS</span></code></a> variable.</p>602</dd></dl>603 604<dl class="py data">605<dt class="sig sig-object py" id="test.support.HAVE_DOCSTRINGS">606<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">HAVE_DOCSTRINGS</span></span><a class="headerlink" href="#test.support.HAVE_DOCSTRINGS" title="Link to this definition">¶</a></dt>607<dd><p>Set to <code class="docutils literal notranslate"><span class="pre">True</span></code> if function docstrings are available.608See the <a class="reference internal" href="../using/cmdline.html#cmdoption-O"><code class="xref std std-option docutils literal notranslate"><span class="pre">python</span> <span class="pre">-OO</span></code></a> option, which strips docstrings of functions implemented in Python.</p>609<p>See also the <a class="reference internal" href="#test.support.MISSING_C_DOCSTRINGS" title="test.support.MISSING_C_DOCSTRINGS"><code class="xref py py-data docutils literal notranslate"><span class="pre">MISSING_C_DOCSTRINGS</span></code></a> variable.</p>610</dd></dl>611 612<dl class="py data">613<dt class="sig sig-object py" id="test.support.TEST_HTTP_URL">614<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">TEST_HTTP_URL</span></span><a class="headerlink" href="#test.support.TEST_HTTP_URL" title="Link to this definition">¶</a></dt>615<dd><p>Define the URL of a dedicated HTTP server for the network tests.</p>616</dd></dl>617 618<dl class="py data">619<dt class="sig sig-object py" id="test.support.ALWAYS_EQ">620<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">ALWAYS_EQ</span></span><a class="headerlink" href="#test.support.ALWAYS_EQ" title="Link to this definition">¶</a></dt>621<dd><p>Object that is equal to anything.  Used to test mixed type comparison.</p>622</dd></dl>623 624<dl class="py data">625<dt class="sig sig-object py" id="test.support.NEVER_EQ">626<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">NEVER_EQ</span></span><a class="headerlink" href="#test.support.NEVER_EQ" title="Link to this definition">¶</a></dt>627<dd><p>Object that is not equal to anything (even to <a class="reference internal" href="#test.support.ALWAYS_EQ" title="test.support.ALWAYS_EQ"><code class="xref py py-data docutils literal notranslate"><span class="pre">ALWAYS_EQ</span></code></a>).628Used to test mixed type comparison.</p>629</dd></dl>630 631<dl class="py data">632<dt class="sig sig-object py" id="test.support.LARGEST">633<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">LARGEST</span></span><a class="headerlink" href="#test.support.LARGEST" title="Link to this definition">¶</a></dt>634<dd><p>Object that is greater than anything (except itself).635Used to test mixed type comparison.</p>636</dd></dl>637 638<dl class="py data">639<dt class="sig sig-object py" id="test.support.SMALLEST">640<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">SMALLEST</span></span><a class="headerlink" href="#test.support.SMALLEST" title="Link to this definition">¶</a></dt>641<dd><p>Object that is less than anything (except itself).642Used to test mixed type comparison.</p>643</dd></dl>644 645<p>The <code class="xref py py-mod docutils literal notranslate"><span class="pre">test.support</span></code> module defines the following functions:</p>646<dl class="py function">647<dt class="sig sig-object py" id="test.support.busy_retry">648<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">busy_retry</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">err_msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">error</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.busy_retry" title="Link to this definition">¶</a></dt>649<dd><p>Run the loop body until <code class="docutils literal notranslate"><span class="pre">break</span></code> stops the loop.</p>650<p>After <em>timeout</em> seconds, raise an <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a> if <em>error</em> is true,651or just stop the loop if <em>error</em> is false.</p>652<p>Example:</p>653<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">support</span><span class="o">.</span><span class="n">busy_retry</span><span class="p">(</span><span class="n">support</span><span class="o">.</span><span class="n">SHORT_TIMEOUT</span><span class="p">):</span>654    <span class="k">if</span> <span class="n">check</span><span class="p">():</span>655        <span class="k">break</span>656</pre></div>657</div>658<p>Example of error=False usage:</p>659<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">support</span><span class="o">.</span><span class="n">busy_retry</span><span class="p">(</span><span class="n">support</span><span class="o">.</span><span class="n">SHORT_TIMEOUT</span><span class="p">,</span> <span class="n">error</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>660    <span class="k">if</span> <span class="n">check</span><span class="p">():</span>661        <span class="k">break</span>662<span class="k">else</span><span class="p">:</span>663    <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s1">&#39;my custom error&#39;</span><span class="p">)</span>664</pre></div>665</div>666</dd></dl>667 668<dl class="py function">669<dt class="sig sig-object py" id="test.support.sleeping_retry">670<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">sleeping_retry</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">timeout</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">err_msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="positional-only-separator o"><abbr title="Positional-only parameter separator (PEP 570)"><span class="pre">/</span></abbr></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">init_delay</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0.010</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">max_delay</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">1.0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">error</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.sleeping_retry" title="Link to this definition">¶</a></dt>671<dd><p>Wait strategy that applies exponential backoff.</p>672<p>Run the loop body until <code class="docutils literal notranslate"><span class="pre">break</span></code> stops the loop. Sleep at each loop673iteration, but not at the first iteration. The sleep delay is doubled at674each iteration (up to <em>max_delay</em> seconds).</p>675<p>See <a class="reference internal" href="#test.support.busy_retry" title="test.support.busy_retry"><code class="xref py py-func docutils literal notranslate"><span class="pre">busy_retry()</span></code></a> documentation for the parameters usage.</p>676<p>Example raising an exception after SHORT_TIMEOUT seconds:</p>677<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">support</span><span class="o">.</span><span class="n">sleeping_retry</span><span class="p">(</span><span class="n">support</span><span class="o">.</span><span class="n">SHORT_TIMEOUT</span><span class="p">):</span>678    <span class="k">if</span> <span class="n">check</span><span class="p">():</span>679        <span class="k">break</span>680</pre></div>681</div>682<p>Example of error=False usage:</p>683<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">_</span> <span class="ow">in</span> <span class="n">support</span><span class="o">.</span><span class="n">sleeping_retry</span><span class="p">(</span><span class="n">support</span><span class="o">.</span><span class="n">SHORT_TIMEOUT</span><span class="p">,</span> <span class="n">error</span><span class="o">=</span><span class="kc">False</span><span class="p">):</span>684    <span class="k">if</span> <span class="n">check</span><span class="p">():</span>685        <span class="k">break</span>686<span class="k">else</span><span class="p">:</span>687    <span class="k">raise</span> <span class="ne">RuntimeError</span><span class="p">(</span><span class="s1">&#39;my custom error&#39;</span><span class="p">)</span>688</pre></div>689</div>690</dd></dl>691 692<dl class="py function">693<dt class="sig sig-object py" id="test.support.is_resource_enabled">694<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">is_resource_enabled</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">resource</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.is_resource_enabled" title="Link to this definition">¶</a></dt>695<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if <em>resource</em> is enabled and available. The list of696available resources is only set when <a class="reference internal" href="#module-test.regrtest" title="test.regrtest: Drives the regression test suite."><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code></a> is executing the697tests.</p>698</dd></dl>699 700<dl class="py function">701<dt class="sig sig-object py" id="test.support.get_resource_value">702<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">get_resource_value</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">resource</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.get_resource_value" title="Link to this definition">¶</a></dt>703<dd><p>Return the value specified for <em>resource</em> (as <code class="samp docutils literal notranslate"><span class="pre">-u</span> <em><span class="pre">resource</span></em><span class="pre">=</span><em><span class="pre">value</span></em></code>).704Return <code class="docutils literal notranslate"><span class="pre">None</span></code> if <em>resource</em> is disabled or no value is specified.</p>705</dd></dl>706 707<dl class="py function">708<dt class="sig sig-object py" id="test.support.python_is_optimized">709<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">python_is_optimized</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.python_is_optimized" title="Link to this definition">¶</a></dt>710<dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> if Python was not built with <code class="docutils literal notranslate"><span class="pre">-O0</span></code> or <code class="docutils literal notranslate"><span class="pre">-Og</span></code>.</p>711</dd></dl>712 713<dl class="py function">714<dt class="sig sig-object py" id="test.support.with_pymalloc">715<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">with_pymalloc</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.with_pymalloc" title="Link to this definition">¶</a></dt>716<dd><p>Return <code class="xref py py-const docutils literal notranslate"><span class="pre">_testcapi.WITH_PYMALLOC</span></code>.</p>717</dd></dl>718 719<dl class="py function">720<dt class="sig sig-object py" id="test.support.requires">721<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">resource</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.requires" title="Link to this definition">¶</a></dt>722<dd><p>Raise <a class="reference internal" href="#test.support.ResourceDenied" title="test.support.ResourceDenied"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceDenied</span></code></a> if <em>resource</em> is not available. <em>msg</em> is the723argument to <code class="xref py py-exc docutils literal notranslate"><span class="pre">ResourceDenied</span></code> if it is raised. Always returns724<code class="docutils literal notranslate"><span class="pre">True</span></code> if called by a function whose <code class="docutils literal notranslate"><span class="pre">__name__</span></code> is <code class="docutils literal notranslate"><span class="pre">'__main__'</span></code>.725Used when tests are executed by <a class="reference internal" href="#module-test.regrtest" title="test.regrtest: Drives the regression test suite."><code class="xref py py-mod docutils literal notranslate"><span class="pre">test.regrtest</span></code></a>.</p>726</dd></dl>727 728<dl class="py function">729<dt class="sig sig-object py" id="test.support.sortdict">730<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">sortdict</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">dict</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.sortdict" title="Link to this definition">¶</a></dt>731<dd><p>Return a repr of <em>dict</em> with keys sorted.</p>732</dd></dl>733 734<dl class="py function">735<dt class="sig sig-object py" id="test.support.findfile">736<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">findfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">subdir</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.findfile" title="Link to this definition">¶</a></dt>737<dd><p>Return the path to the file named <em>filename</em>. If no match is found738<em>filename</em> is returned. This does not equal a failure since it could be the739path to the file.</p>740<p>Setting <em>subdir</em> indicates a relative path to use to find the file741rather than looking directly in the path directories.</p>742</dd></dl>743 744<dl class="py function">745<dt class="sig sig-object py" id="test.support.get_pagesize">746<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">get_pagesize</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.get_pagesize" title="Link to this definition">¶</a></dt>747<dd><p>Get size of a page in bytes.</p>748<div class="versionadded">749<p><span class="versionmodified added">Added in version 3.12.</span></p>750</div>751</dd></dl>752 753<dl class="py function">754<dt class="sig sig-object py" id="test.support.setswitchinterval">755<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">setswitchinterval</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">interval</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.setswitchinterval" title="Link to this definition">¶</a></dt>756<dd><p>Set the <a class="reference internal" href="sys.html#sys.setswitchinterval" title="sys.setswitchinterval"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.setswitchinterval()</span></code></a> to the given <em>interval</em>.  Defines757a minimum interval for Android systems to prevent the system from hanging.</p>758</dd></dl>759 760<dl class="py function">761<dt class="sig sig-object py" id="test.support.check_impl_detail">762<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">check_impl_detail</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">guards</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.check_impl_detail" title="Link to this definition">¶</a></dt>763<dd><p>Use this check to guard CPython’s implementation-specific tests or to764run them only on the implementations guarded by the arguments.  This765function returns <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code> depending on the host platform.766Example usage:</p>767<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">check_impl_detail</span><span class="p">()</span>               <span class="c1"># Only on CPython (default).</span>768<span class="n">check_impl_detail</span><span class="p">(</span><span class="n">jython</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>    <span class="c1"># Only on Jython.</span>769<span class="n">check_impl_detail</span><span class="p">(</span><span class="n">cpython</span><span class="o">=</span><span class="kc">False</span><span class="p">)</span>  <span class="c1"># Everywhere except CPython.</span>770</pre></div>771</div>772</dd></dl>773 774<dl class="py function">775<dt class="sig sig-object py" id="test.support.set_memlimit">776<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">set_memlimit</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">limit</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.set_memlimit" title="Link to this definition">¶</a></dt>777<dd><p>Set the values for <a class="reference internal" href="#test.support.max_memuse" title="test.support.max_memuse"><code class="xref py py-data docutils literal notranslate"><span class="pre">max_memuse</span></code></a> and <a class="reference internal" href="#test.support.real_max_memuse" title="test.support.real_max_memuse"><code class="xref py py-data docutils literal notranslate"><span class="pre">real_max_memuse</span></code></a> for big778memory tests.</p>779</dd></dl>780 781<dl class="py function">782<dt class="sig sig-object py" id="test.support.record_original_stdout">783<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">record_original_stdout</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">stdout</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.record_original_stdout" title="Link to this definition">¶</a></dt>784<dd><p>Store the value from <em>stdout</em>.  It is meant to hold the stdout at the785time the regrtest began.</p>786</dd></dl>787 788<dl class="py function">789<dt class="sig sig-object py" id="test.support.get_original_stdout">790<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">get_original_stdout</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.get_original_stdout" title="Link to this definition">¶</a></dt>791<dd><p>Return the original stdout set by <a class="reference internal" href="#test.support.record_original_stdout" title="test.support.record_original_stdout"><code class="xref py py-func docutils literal notranslate"><span class="pre">record_original_stdout()</span></code></a> or792<code class="docutils literal notranslate"><span class="pre">sys.stdout</span></code> if it’s not set.</p>793</dd></dl>794 795<dl class="py function">796<dt class="sig sig-object py" id="test.support.args_from_interpreter_flags">797<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">args_from_interpreter_flags</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.args_from_interpreter_flags" title="Link to this definition">¶</a></dt>798<dd><p>Return a list of command line arguments reproducing the current settings799in <code class="docutils literal notranslate"><span class="pre">sys.flags</span></code> and <code class="docutils literal notranslate"><span class="pre">sys.warnoptions</span></code>.</p>800</dd></dl>801 802<dl class="py function">803<dt class="sig sig-object py" id="test.support.optim_args_from_interpreter_flags">804<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">optim_args_from_interpreter_flags</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.optim_args_from_interpreter_flags" title="Link to this definition">¶</a></dt>805<dd><p>Return a list of command line arguments reproducing the current806optimization settings in <code class="docutils literal notranslate"><span class="pre">sys.flags</span></code>.</p>807</dd></dl>808 809<dl class="py function">810<dt class="sig sig-object py" id="test.support.captured_stdin">811<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">captured_stdin</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.captured_stdin" title="Link to this definition">¶</a></dt>812<dt class="sig sig-object py" id="test.support.captured_stdout">813<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">captured_stdout</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.captured_stdout" title="Link to this definition">¶</a></dt>814<dt class="sig sig-object py" id="test.support.captured_stderr">815<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">captured_stderr</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.captured_stderr" title="Link to this definition">¶</a></dt>816<dd><p>A context managers that temporarily replaces the named stream with817<a class="reference internal" href="io.html#io.StringIO" title="io.StringIO"><code class="xref py py-class docutils literal notranslate"><span class="pre">io.StringIO</span></code></a> object.</p>818<p>Example use with output streams:</p>819<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">captured_stdout</span><span class="p">()</span> <span class="k">as</span> <span class="n">stdout</span><span class="p">,</span> <span class="n">captured_stderr</span><span class="p">()</span> <span class="k">as</span> <span class="n">stderr</span><span class="p">:</span>820    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;hello&quot;</span><span class="p">)</span>821    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;error&quot;</span><span class="p">,</span> <span class="n">file</span><span class="o">=</span><span class="n">sys</span><span class="o">.</span><span class="n">stderr</span><span class="p">)</span>822<span class="k">assert</span> <span class="n">stdout</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;hello</span><span class="se">\n</span><span class="s2">&quot;</span>823<span class="k">assert</span> <span class="n">stderr</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()</span> <span class="o">==</span> <span class="s2">&quot;error</span><span class="se">\n</span><span class="s2">&quot;</span>824</pre></div>825</div>826<p>Example use with input stream:</p>827<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">captured_stdin</span><span class="p">()</span> <span class="k">as</span> <span class="n">stdin</span><span class="p">:</span>828    <span class="n">stdin</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="s1">&#39;hello</span><span class="se">\n</span><span class="s1">&#39;</span><span class="p">)</span>829    <span class="n">stdin</span><span class="o">.</span><span class="n">seek</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>830    <span class="c1"># call test code that consumes from sys.stdin</span>831    <span class="n">captured</span> <span class="o">=</span> <span class="nb">input</span><span class="p">()</span>832<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">captured</span><span class="p">,</span> <span class="s2">&quot;hello&quot;</span><span class="p">)</span>833</pre></div>834</div>835</dd></dl>836 837<dl class="py function">838<dt class="sig sig-object py" id="test.support.disable_faulthandler">839<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">disable_faulthandler</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.disable_faulthandler" title="Link to this definition">¶</a></dt>840<dd><p>A context manager that temporary disables <a class="reference internal" href="faulthandler.html#module-faulthandler" title="faulthandler: Dump the Python traceback."><code class="xref py py-mod docutils literal notranslate"><span class="pre">faulthandler</span></code></a>.</p>841</dd></dl>842 843<dl class="py function">844<dt class="sig sig-object py" id="test.support.gc_collect">845<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">gc_collect</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.gc_collect" title="Link to this definition">¶</a></dt>846<dd><p>Force as many objects as possible to be collected.  This is needed because847timely deallocation is not guaranteed by the garbage collector.  This means848that <code class="docutils literal notranslate"><span class="pre">__del__</span></code> methods may be called later than expected and weakrefs849may remain alive for longer than expected.</p>850</dd></dl>851 852<dl class="py function">853<dt class="sig sig-object py" id="test.support.disable_gc">854<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">disable_gc</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.disable_gc" title="Link to this definition">¶</a></dt>855<dd><p>A context manager that disables the garbage collector on entry. On856exit, the garbage collector is restored to its prior state.</p>857</dd></dl>858 859<dl class="py function">860<dt class="sig sig-object py" id="test.support.swap_attr">861<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">swap_attr</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new_val</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.swap_attr" title="Link to this definition">¶</a></dt>862<dd><p>Context manager to swap out an attribute with a new object.</p>863<p>Usage:</p>864<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">swap_attr</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s2">&quot;attr&quot;</span><span class="p">,</span> <span class="mi">5</span><span class="p">):</span>865    <span class="o">...</span>866</pre></div>867</div>868<p>This will set <code class="docutils literal notranslate"><span class="pre">obj.attr</span></code> to 5 for the duration of the <code class="docutils literal notranslate"><span class="pre">with</span></code> block,869restoring the old value at the end of the block.  If <code class="docutils literal notranslate"><span class="pre">attr</span></code> doesn’t870exist on <code class="docutils literal notranslate"><span class="pre">obj</span></code>, it will be created and then deleted at the end of the871block.</p>872<p>The old value (or <code class="docutils literal notranslate"><span class="pre">None</span></code> if it doesn’t exist) will be assigned to the873target of the “as” clause, if there is one.</p>874</dd></dl>875 876<dl class="py function">877<dt class="sig sig-object py" id="test.support.swap_item">878<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">swap_item</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">attr</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">new_val</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.swap_item" title="Link to this definition">¶</a></dt>879<dd><p>Context manager to swap out an item with a new object.</p>880<p>Usage:</p>881<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">swap_item</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="s2">&quot;item&quot;</span><span class="p">,</span> <span class="mi">5</span><span class="p">):</span>882    <span class="o">...</span>883</pre></div>884</div>885<p>This will set <code class="docutils literal notranslate"><span class="pre">obj[&quot;item&quot;]</span></code> to 5 for the duration of the <code class="docutils literal notranslate"><span class="pre">with</span></code> block,886restoring the old value at the end of the block. If <code class="docutils literal notranslate"><span class="pre">item</span></code> doesn’t887exist on <code class="docutils literal notranslate"><span class="pre">obj</span></code>, it will be created and then deleted at the end of the888block.</p>889<p>The old value (or <code class="docutils literal notranslate"><span class="pre">None</span></code> if it doesn’t exist) will be assigned to the890target of the “as” clause, if there is one.</p>891</dd></dl>892 893<dl class="py function">894<dt class="sig sig-object py" id="test.support.flush_std_streams">895<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">flush_std_streams</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.flush_std_streams" title="Link to this definition">¶</a></dt>896<dd><p>Call the <code class="docutils literal notranslate"><span class="pre">flush()</span></code> method on <a class="reference internal" href="sys.html#sys.stdout" title="sys.stdout"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stdout</span></code></a> and then on897<a class="reference internal" href="sys.html#sys.stderr" title="sys.stderr"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.stderr</span></code></a>. It can be used to make sure that the logs order is898consistent before writing into stderr.</p>899<div class="versionadded">900<p><span class="versionmodified added">Added in version 3.11.</span></p>901</div>902</dd></dl>903 904<dl class="py function">905<dt class="sig sig-object py" id="test.support.print_warning">906<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">print_warning</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.print_warning" title="Link to this definition">¶</a></dt>907<dd><p>Print a warning into <a class="reference internal" href="sys.html#sys.__stderr__" title="sys.__stderr__"><code class="xref py py-data docutils literal notranslate"><span class="pre">sys.__stderr__</span></code></a>. Format the message as:908<code class="docutils literal notranslate"><span class="pre">f&quot;Warning</span> <span class="pre">--</span> <span class="pre">{msg}&quot;</span></code>. If <em>msg</em> is made of multiple lines, add909<code class="docutils literal notranslate"><span class="pre">&quot;Warning</span> <span class="pre">--</span> <span class="pre">&quot;</span></code> prefix to each line.</p>910<div class="versionadded">911<p><span class="versionmodified added">Added in version 3.9.</span></p>912</div>913</dd></dl>914 915<dl class="py function">916<dt class="sig sig-object py" id="test.support.wait_process">917<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">wait_process</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pid</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">exitcode</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">timeout</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.wait_process" title="Link to this definition">¶</a></dt>918<dd><p>Wait until process <em>pid</em> completes and check that the process exit code is919<em>exitcode</em>.</p>920<p>Raise an <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a> if the process exit code is not equal to921<em>exitcode</em>.</p>922<p>If the process runs longer than <em>timeout</em> seconds (<a class="reference internal" href="#test.support.SHORT_TIMEOUT" title="test.support.SHORT_TIMEOUT"><code class="xref py py-data docutils literal notranslate"><span class="pre">SHORT_TIMEOUT</span></code></a> by923default), kill the process and raise an <a class="reference internal" href="exceptions.html#AssertionError" title="AssertionError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AssertionError</span></code></a>. The timeout924feature is not available on Windows.</p>925<div class="versionadded">926<p><span class="versionmodified added">Added in version 3.9.</span></p>927</div>928</dd></dl>929 930<dl class="py function">931<dt class="sig sig-object py" id="test.support.calcobjsize">932<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">calcobjsize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fmt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.calcobjsize" title="Link to this definition">¶</a></dt>933<dd><p>Return the size of the <a class="reference internal" href="../c-api/structures.html#c.PyObject" title="PyObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyObject</span></code></a> whose structure members are934defined by <em>fmt</em>. The returned value includes the size of the Python object header and alignment.</p>935</dd></dl>936 937<dl class="py function">938<dt class="sig sig-object py" id="test.support.calcvobjsize">939<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">calcvobjsize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">fmt</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.calcvobjsize" title="Link to this definition">¶</a></dt>940<dd><p>Return the size of the <a class="reference internal" href="../c-api/structures.html#c.PyVarObject" title="PyVarObject"><code class="xref c c-type docutils literal notranslate"><span class="pre">PyVarObject</span></code></a> whose structure members are941defined by <em>fmt</em>. The returned value includes the size of the Python object header and alignment.</p>942</dd></dl>943 944<dl class="py function">945<dt class="sig sig-object py" id="test.support.checksizeof">946<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">checksizeof</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">o</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">size</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.checksizeof" title="Link to this definition">¶</a></dt>947<dd><p>For testcase <em>test</em>, assert that the <code class="docutils literal notranslate"><span class="pre">sys.getsizeof</span></code> for <em>o</em> plus the GC948header size equals <em>size</em>.</p>949</dd></dl>950 951<dl class="py function">952<dt class="sig sig-object py" id="test.support.anticipate_failure">953<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">anticipate_failure</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">condition</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.anticipate_failure" title="Link to this definition">¶</a></dt>954<dd><p>A decorator to conditionally mark tests with955<a class="reference internal" href="unittest.html#unittest.expectedFailure" title="unittest.expectedFailure"><code class="xref py py-func docutils literal notranslate"><span class="pre">unittest.expectedFailure()</span></code></a>. Any use of this decorator should956have an associated comment identifying the relevant tracker issue.</p>957</dd></dl>958 959<dl class="py function">960<dt class="sig sig-object py" id="test.support.system_must_validate_cert">961<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">system_must_validate_cert</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.system_must_validate_cert" title="Link to this definition">¶</a></dt>962<dd><p>A decorator that skips the decorated test on TLS certification validation failures.</p>963</dd></dl>964 965<dl class="py function">966<dt class="sig sig-object py" id="test.support.run_with_locale">967<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">run_with_locale</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">catstr</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">locales</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.run_with_locale" title="Link to this definition">¶</a></dt>968<dd><p>A decorator for running a function in a different locale, correctly969resetting it after it has finished.  <em>catstr</em> is the locale category as970a string (for example <code class="docutils literal notranslate"><span class="pre">&quot;LC_ALL&quot;</span></code>).  The <em>locales</em> passed will be tried971sequentially, and the first valid locale will be used.</p>972</dd></dl>973 974<dl class="py function">975<dt class="sig sig-object py" id="test.support.run_with_tz">976<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">run_with_tz</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">tz</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.run_with_tz" title="Link to this definition">¶</a></dt>977<dd><p>A decorator for running a function in a specific timezone, correctly978resetting it after it has finished.</p>979</dd></dl>980 981<dl class="py function">982<dt class="sig sig-object py" id="test.support.requires_freebsd_version">983<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_freebsd_version</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">min_version</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.requires_freebsd_version" title="Link to this definition">¶</a></dt>984<dd><p>Decorator for the minimum version when running test on FreeBSD.  If the985FreeBSD version is less than the minimum, the test is skipped.</p>986</dd></dl>987 988<dl class="py function">989<dt class="sig sig-object py" id="test.support.requires_linux_version">990<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_linux_version</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">min_version</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.requires_linux_version" title="Link to this definition">¶</a></dt>991<dd><p>Decorator for the minimum version when running test on Linux.  If the992Linux version is less than the minimum, the test is skipped.</p>993</dd></dl>994 995<dl class="py function">996<dt class="sig sig-object py" id="test.support.requires_mac_version">997<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_mac_version</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">min_version</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.requires_mac_version" title="Link to this definition">¶</a></dt>998<dd><p>Decorator for the minimum version when running test on macOS.  If the999macOS version is less than the minimum, the test is skipped.</p>1000</dd></dl>1001 1002<dl class="py function">1003<dt class="sig sig-object py" id="test.support.requires_gil_enabled">1004<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_gil_enabled</span></span><a class="headerlink" href="#test.support.requires_gil_enabled" title="Link to this definition">¶</a></dt>1005<dd><p>Decorator for skipping tests on the free-threaded build.  If the1006<a class="reference internal" href="../glossary.html#term-GIL"><span class="xref std std-term">GIL</span></a> is disabled, the test is skipped.</p>1007</dd></dl>1008 1009<dl class="py function">1010<dt class="sig sig-object py" id="test.support.requires_IEEE_754">1011<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_IEEE_754</span></span><a class="headerlink" href="#test.support.requires_IEEE_754" title="Link to this definition">¶</a></dt>1012<dd><p>Decorator for skipping tests on non-IEEE 754 platforms.</p>1013</dd></dl>1014 1015<dl class="py function">1016<dt class="sig sig-object py" id="test.support.requires_zlib">1017<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_zlib</span></span><a class="headerlink" href="#test.support.requires_zlib" title="Link to this definition">¶</a></dt>1018<dd><p>Decorator for skipping tests if <a class="reference internal" href="zlib.html#module-zlib" title="zlib: Low-level interface to compression and decompression routines compatible with gzip."><code class="xref py py-mod docutils literal notranslate"><span class="pre">zlib</span></code></a> doesn’t exist.</p>1019</dd></dl>1020 1021<dl class="py function">1022<dt class="sig sig-object py" id="test.support.requires_gzip">1023<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_gzip</span></span><a class="headerlink" href="#test.support.requires_gzip" title="Link to this definition">¶</a></dt>1024<dd><p>Decorator for skipping tests if <a class="reference internal" href="gzip.html#module-gzip" title="gzip: Interfaces for gzip compression and decompression using file objects."><code class="xref py py-mod docutils literal notranslate"><span class="pre">gzip</span></code></a> doesn’t exist.</p>1025</dd></dl>1026 1027<dl class="py function">1028<dt class="sig sig-object py" id="test.support.requires_bz2">1029<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_bz2</span></span><a class="headerlink" href="#test.support.requires_bz2" title="Link to this definition">¶</a></dt>1030<dd><p>Decorator for skipping tests if <a class="reference internal" href="bz2.html#module-bz2" title="bz2: Interfaces for bzip2 compression and decompression."><code class="xref py py-mod docutils literal notranslate"><span class="pre">bz2</span></code></a> doesn’t exist.</p>1031</dd></dl>1032 1033<dl class="py function">1034<dt class="sig sig-object py" id="test.support.requires_lzma">1035<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_lzma</span></span><a class="headerlink" href="#test.support.requires_lzma" title="Link to this definition">¶</a></dt>1036<dd><p>Decorator for skipping tests if <a class="reference internal" href="lzma.html#module-lzma" title="lzma: A Python wrapper for the liblzma compression library."><code class="xref py py-mod docutils literal notranslate"><span class="pre">lzma</span></code></a> doesn’t exist.</p>1037</dd></dl>1038 1039<dl class="py function">1040<dt class="sig sig-object py" id="test.support.requires_resource">1041<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_resource</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">resource</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.requires_resource" title="Link to this definition">¶</a></dt>1042<dd><p>Decorator for skipping tests if <em>resource</em> is not available.</p>1043</dd></dl>1044 1045<dl class="py function">1046<dt class="sig sig-object py" id="test.support.requires_docstrings">1047<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_docstrings</span></span><a class="headerlink" href="#test.support.requires_docstrings" title="Link to this definition">¶</a></dt>1048<dd><p>Decorator for only running the test if <a class="reference internal" href="#test.support.HAVE_DOCSTRINGS" title="test.support.HAVE_DOCSTRINGS"><code class="xref py py-data docutils literal notranslate"><span class="pre">HAVE_DOCSTRINGS</span></code></a>.</p>1049</dd></dl>1050 1051<dl class="py function">1052<dt class="sig sig-object py" id="test.support.requires_limited_api">1053<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">requires_limited_api</span></span><a class="headerlink" href="#test.support.requires_limited_api" title="Link to this definition">¶</a></dt>1054<dd><p>Decorator for only running the test if <a class="reference internal" href="../c-api/stable.html#limited-c-api"><span class="std std-ref">Limited C API</span></a>1055is available.</p>1056</dd></dl>1057 1058<dl class="py function">1059<dt class="sig sig-object py" id="test.support.cpython_only">1060<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">cpython_only</span></span><a class="headerlink" href="#test.support.cpython_only" title="Link to this definition">¶</a></dt>1061<dd><p>Decorator for tests only applicable to CPython.</p>1062</dd></dl>1063 1064<dl class="py function">1065<dt class="sig sig-object py" id="test.support.impl_detail">1066<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">impl_detail</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">guards</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.impl_detail" title="Link to this definition">¶</a></dt>1067<dd><p>Decorator for invoking <a class="reference internal" href="#test.support.check_impl_detail" title="test.support.check_impl_detail"><code class="xref py py-func docutils literal notranslate"><span class="pre">check_impl_detail()</span></code></a> on <em>guards</em>.  If that1068returns <code class="docutils literal notranslate"><span class="pre">False</span></code>, then uses <em>msg</em> as the reason for skipping the test.</p>1069</dd></dl>1070 1071<dl class="py function">1072<dt class="sig sig-object py" id="test.support.thread_unsafe">1073<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">thread_unsafe</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">reason</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.thread_unsafe" title="Link to this definition">¶</a></dt>1074<dd><p>Decorator for marking tests as thread-unsafe.  This test always runs in one1075thread even when invoked with <code class="docutils literal notranslate"><span class="pre">--parallel-threads</span></code>.</p>1076</dd></dl>1077 1078<dl class="py function">1079<dt class="sig sig-object py" id="test.support.no_tracing">1080<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">no_tracing</span></span><a class="headerlink" href="#test.support.no_tracing" title="Link to this definition">¶</a></dt>1081<dd><p>Decorator to temporarily turn off tracing for the duration of the test.</p>1082</dd></dl>1083 1084<dl class="py function">1085<dt class="sig sig-object py" id="test.support.refcount_test">1086<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">refcount_test</span></span><a class="headerlink" href="#test.support.refcount_test" title="Link to this definition">¶</a></dt>1087<dd><p>Decorator for tests which involve reference counting.  The decorator does1088not run the test if it is not run by CPython.  Any trace function is unset1089for the duration of the test to prevent unexpected refcounts caused by1090the trace function.</p>1091</dd></dl>1092 1093<dl class="py function">1094<dt class="sig sig-object py" id="test.support.bigmemtest">1095<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">bigmemtest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">size</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">memuse</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">dry_run</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.bigmemtest" title="Link to this definition">¶</a></dt>1096<dd><p>Decorator for bigmem tests.</p>1097<p><em>size</em> is a requested size for the test (in arbitrary, test-interpreted1098units.)  <em>memuse</em> is the number of bytes per unit for the test, or a good1099estimate of it.  For example, a test that needs two byte buffers, of 4 GiB1100each, could be decorated with <code class="docutils literal notranslate"><span class="pre">&#64;bigmemtest(size=_4G,</span> <span class="pre">memuse=2)</span></code>.</p>1101<p>The <em>size</em> argument is normally passed to the decorated test method as an1102extra argument.  If <em>dry_run</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, the value passed to the test1103method may be less than the requested value.  If <em>dry_run</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, it1104means the test doesn’t support dummy runs when <code class="docutils literal notranslate"><span class="pre">-M</span></code> is not specified.</p>1105</dd></dl>1106 1107<dl class="py function">1108<dt class="sig sig-object py" id="test.support.bigaddrspacetest">1109<span class="sig-prename descclassname"><span class="pre">&#64;</span></span><span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">bigaddrspacetest</span></span><a class="headerlink" href="#test.support.bigaddrspacetest" title="Link to this definition">¶</a></dt>1110<dd><p>Decorator for tests that fill the address space.</p>1111</dd></dl>1112 1113<dl class="py function">1114<dt class="sig sig-object py" id="test.support.linked_to_musl">1115<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">linked_to_musl</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.linked_to_musl" title="Link to this definition">¶</a></dt>1116<dd><p>Return <code class="docutils literal notranslate"><span class="pre">False</span></code> if there is no evidence the interpreter was compiled with1117<code class="docutils literal notranslate"><span class="pre">musl</span></code>, otherwise return a version triple, either <code class="docutils literal notranslate"><span class="pre">(0,</span> <span class="pre">0,</span> <span class="pre">0)</span></code> if the1118version is unknown, or the actual version if it is known.  Intended for use1119in <code class="docutils literal notranslate"><span class="pre">skip</span></code> decorators.  <code class="docutils literal notranslate"><span class="pre">emscripten</span></code> and <code class="docutils literal notranslate"><span class="pre">wasi</span></code> are assumed to be1120compiled with <code class="docutils literal notranslate"><span class="pre">musl</span></code>; otherwise <code class="docutils literal notranslate"><span class="pre">platform.libc_ver</span></code> is checked.</p>1121</dd></dl>1122 1123<dl class="py function">1124<dt class="sig sig-object py" id="test.support.check_syntax_error">1125<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">check_syntax_error</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">testcase</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">statement</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">errtext</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">''</span></span></em>, <em class="sig-param"><span class="keyword-only-separator o"><abbr title="Keyword-only parameters separator (PEP 3102)"><span class="pre">*</span></abbr></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">offset</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.check_syntax_error" title="Link to this definition">¶</a></dt>1126<dd><p>Test for syntax errors in <em>statement</em> by attempting to compile <em>statement</em>.1127<em>testcase</em> is the <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> instance for the test.  <em>errtext</em> is the1128regular expression which should match the string representation of the1129raised <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>.  If <em>lineno</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, compares to1130the line of the exception.  If <em>offset</em> is not <code class="docutils literal notranslate"><span class="pre">None</span></code>, compares to1131the offset of the exception.</p>1132</dd></dl>1133 1134<dl class="py function">1135<dt class="sig sig-object py" id="test.support.open_urlresource">1136<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">open_urlresource</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">url</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">args</span></span></em>, <em class="sig-param"><span class="o"><span class="pre">**</span></span><span class="n"><span class="pre">kw</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.open_urlresource" title="Link to this definition">¶</a></dt>1137<dd><p>Open <em>url</em>.  If open fails, raises <a class="reference internal" href="#test.support.TestFailed" title="test.support.TestFailed"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TestFailed</span></code></a>.</p>1138</dd></dl>1139 1140<dl class="py function">1141<dt class="sig sig-object py" id="test.support.reap_children">1142<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">reap_children</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.reap_children" title="Link to this definition">¶</a></dt>1143<dd><p>Use this at the end of <code class="docutils literal notranslate"><span class="pre">test_main</span></code> whenever sub-processes are started.1144This will help ensure that no extra children (zombies) stick around to1145hog resources and create problems when looking for refleaks.</p>1146</dd></dl>1147 1148<dl class="py function">1149<dt class="sig sig-object py" id="test.support.get_attribute">1150<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">get_attribute</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">obj</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.get_attribute" title="Link to this definition">¶</a></dt>1151<dd><p>Get an attribute, raising <a class="reference internal" href="unittest.html#unittest.SkipTest" title="unittest.SkipTest"><code class="xref py py-exc docutils literal notranslate"><span class="pre">unittest.SkipTest</span></code></a> if <a class="reference internal" href="exceptions.html#AttributeError" title="AttributeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">AttributeError</span></code></a>1152is raised.</p>1153</dd></dl>1154 1155<dl class="py function">1156<dt class="sig sig-object py" id="test.support.catch_unraisable_exception">1157<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">catch_unraisable_exception</span></span><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#test.support.catch_unraisable_exception" title="Link to this definition">¶</a></dt>1158<dd><p>Context manager catching unraisable exception using1159<a class="reference internal" href="sys.html#sys.unraisablehook" title="sys.unraisablehook"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.unraisablehook()</span></code></a>.</p>1160<p>Storing the exception value (<code class="docutils literal notranslate"><span class="pre">cm.unraisable.exc_value</span></code>) creates a1161reference cycle. The reference cycle is broken explicitly when the context1162manager exits.</p>1163<p>Storing the object (<code class="docutils literal notranslate"><span class="pre">cm.unraisable.object</span></code>) can resurrect it if it is set1164to an object which is being finalized. Exiting the context manager clears1165the stored object.</p>1166<p>Usage:</p>1167<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">support</span><span class="o">.</span><span class="n">catch_unraisable_exception</span><span class="p">()</span> <span class="k">as</span> <span class="n">cm</span><span class="p">:</span>1168    <span class="c1"># code creating an &quot;unraisable exception&quot;</span>1169    <span class="o">...</span>1170 1171    <span class="c1"># check the unraisable exception: use cm.unraisable</span>1172    <span class="o">...</span>1173 1174<span class="c1"># cm.unraisable attribute no longer exists at this point</span>1175<span class="c1"># (to break a reference cycle)</span>1176</pre></div>1177</div>1178<div class="versionadded">1179<p><span class="versionmodified added">Added in version 3.8.</span></p>1180</div>1181</dd></dl>1182 1183<dl class="py function">1184<dt class="sig sig-object py" id="test.support.load_package_tests">1185<span class="sig-prename descclassname"><span class="pre">test.support.</span></span><span class="sig-name descname"><span class="pre">load_package_tests</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">pkg_dir</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">loader</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">standard_tests</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pattern</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#test.support.load_package_tests" title="Link to this definition">¶</a></dt>1186<dd><p>Generic implementation of the <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> <code class="docutils literal notranslate"><span class="pre">load_tests</span></code> protocol for1187use in test packages.  <em>pkg_dir</em> is the root directory of the package;1188<em>loader</em>, <em>standard_tests</em>, and <em>pattern</em> are the arguments expected by1189<code class="docutils literal notranslate"><span class="pre">load_tests</span></code>.  In simple cases, the test package’s <code class="docutils literal notranslate"><span class="pre">__init__.py</span></code>1190can be the following:</p>1191<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span><span class="w"> </span><span class="nn">os</span>1192<span class="kn">from</span><span class="w"> </span><span class="nn">test.support</span><span class="w"> </span><span class="kn">import</span> <span class="n">load_package_tests</span>1193 1194<span class="k">def</span><span class="w"> </span><span class="nf">load_tests</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">):</span>1195    <span class="k">return</span> <span class="n">load_package_tests</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="vm">__file__</span><span class="p">),</span> <span class="o">*</span><span class="n">args</span><span class="p">)</span>1196</pre></div>1197</div>1198</dd></dl>1199 1200<dl class="py function">

Showing the first 1,200 of 2274 lines. Download the file for the rest.