diff options
| author |   Michał Górny <mgorny@gentoo.org> | 2023-09-21 17:59:55 +0200 |
|---|---|---|
| committer | Michał Górny <mgorny@gentoo.org> | 2023-09-21 17:59:55 +0200 |
| commit | 1c790c55a8e4bc6deef00910403334d5536fb2c8 (patch) | |
| tree | ea92dde291014707a012c085b27381a17742f1bb /guide/test.html | |
| parent | Update Guide to 8e5a339 (diff) | |
| download | python-1c790c55a8e4bc6deef00910403334d5536fb2c8.tar.gz python-1c790c55a8e4bc6deef00910403334d5536fb2c8.tar.bz2 python-1c790c55a8e4bc6deef00910403334d5536fb2c8.zip | |
Regen with Sphinx 7.2.6
Signed-off-by: Michał Górny <mgorny@gentoo.org>
Diffstat (limited to 'guide/test.html')
| -rw-r--r-- | guide/test.html | 88 |
1 files changed, 44 insertions, 44 deletions
diff --git a/guide/test.html b/guide/test.html index 0090c43..8b3a162 100644 --- a/guide/test.html +++ b/guide/test.html @@ -1,16 +1,16 @@ <!DOCTYPE html> -<html lang="en"> +<html lang="en" data-content_root="./"> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" /> <title>Tests in Python packages — Gentoo Python Guide documentation</title> - <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b3523f8e" /> + <link rel="stylesheet" type="text/css" href="_static/pygments.css?v=4f649999" /> <link rel="stylesheet" type="text/css" href="_static/alabaster.css?v=039e1c02" /> - <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js?v=b3ba4146"></script> + <script src="_static/documentation_options.js?v=5929fcd5"></script> <script src="_static/doctools.js?v=888ff710"></script> - <script src="_static/sphinx_highlight.js?v=4825356b"></script> + <script src="_static/sphinx_highlight.js?v=dc90522c"></script> <link rel="index" title="Index" href="genindex.html" /> <link rel="search" title="Search" href="search.html" /> <link rel="next" title="distutils-r1 legacy concepts" href="distutils-legacy.html" /> @@ -32,9 +32,9 @@ <div class="body" role="main"> <section id="tests-in-python-packages"> -<h1>Tests in Python packages<a class="headerlink" href="#tests-in-python-packages" title="Permalink to this heading">¶</a></h1> +<h1>Tests in Python packages<a class="headerlink" href="#tests-in-python-packages" title="Link to this heading">¶</a></h1> <section id="why-is-running-tests-important"> -<h2>Why is running tests important?<a class="headerlink" href="#why-is-running-tests-important" title="Permalink to this heading">¶</a></h2> +<h2>Why is running tests important?<a class="headerlink" href="#why-is-running-tests-important" title="Link to this heading">¶</a></h2> <p>Since Python performs only minimal build-time (or more precisely, import-time) checking of correctness, it is important to run tests of Python packages in order to catch any problems early. This is @@ -42,9 +42,9 @@ especially important for permitting others to verify support for new Python implementations.</p> </section> <section id="using-distutils-enable-tests"> -<span id="index-0"></span><h2>Using distutils_enable_tests<a class="headerlink" href="#using-distutils-enable-tests" title="Permalink to this heading">¶</a></h2> +<span id="index-0"></span><h2>Using distutils_enable_tests<a class="headerlink" href="#using-distutils-enable-tests" title="Link to this heading">¶</a></h2> <section id="basic-use-case"> -<h3>Basic use case<a class="headerlink" href="#basic-use-case" title="Permalink to this heading">¶</a></h3> +<h3>Basic use case<a class="headerlink" href="#basic-use-case" title="Link to this heading">¶</a></h3> <p>The simplest way of enabling tests is to call <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> in global scope, passing the test runner name as the first argument. This function takes care of declaring test phase, setting appropriate @@ -84,7 +84,7 @@ setting <code class="docutils literal notranslate"><span class="pre">RDEPEND</sp <p>See <a class="reference internal" href="#choosing-the-correct-test-runner">choosing the correct test runner</a> for more information.</p> </section> <section id="adding-more-test-dependencies"> -<h3>Adding more test dependencies<a class="headerlink" href="#adding-more-test-dependencies" title="Permalink to this heading">¶</a></h3> +<h3>Adding more test dependencies<a class="headerlink" href="#adding-more-test-dependencies" title="Link to this heading">¶</a></h3> <p>Additional test dependencies can be specified in <code class="docutils literal notranslate"><span class="pre">test?</span></code> conditional. The flag normally does not need to be explicitly declared, as <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> does that in the majority of cases.</p> @@ -125,7 +125,7 @@ can be rewritten as:</p> </div> </section> <section id="installing-the-package-before-running-tests"> -<h3>Installing the package before running tests<a class="headerlink" href="#installing-the-package-before-running-tests" title="Permalink to this heading">¶</a></h3> +<h3>Installing the package before running tests<a class="headerlink" href="#installing-the-package-before-running-tests" title="Link to this heading">¶</a></h3> <p>In PEP 517 mode, the eclass automatically exposes a venv-style install tree to the test phase. No explicit action in necessary.</p> <p>In the legacy mode, <code class="docutils literal notranslate"><span class="pre">distutils_enable_tests</span></code> has an optional @@ -134,7 +134,7 @@ to a temporary directory. More information can be found in the legacy section.</p> </section> <section id="customizing-the-test-phase"> -<h3>Customizing the test phase<a class="headerlink" href="#customizing-the-test-phase" title="Permalink to this heading">¶</a></h3> +<h3>Customizing the test phase<a class="headerlink" href="#customizing-the-test-phase" title="Link to this heading">¶</a></h3> <p>If additional pre-/post-test phase actions need to be performed, they can be easily injected via overriding <code class="docutils literal notranslate"><span class="pre">src_test()</span></code> and making it call <code class="docutils literal notranslate"><span class="pre">distutils-r1_src_test</span></code>:</p> @@ -222,7 +222,7 @@ of its logic.</p> so you must make sure to call it if you override <code class="docutils literal notranslate"><span class="pre">src_test</span></code>.</p> </section> <section id="customizing-the-test-phase-for-pytest"> -<span id="index-1"></span><h3>Customizing the test phase for pytest<a class="headerlink" href="#customizing-the-test-phase-for-pytest" title="Permalink to this heading">¶</a></h3> +<span id="index-1"></span><h3>Customizing the test phase for pytest<a class="headerlink" href="#customizing-the-test-phase-for-pytest" title="Link to this heading">¶</a></h3> <p>For the relatively frequent case of pytest-based packages needing additional customization, a <code class="docutils literal notranslate"><span class="pre">epytest</span></code> helper is provided. The helper runs <code class="docutils literal notranslate"><span class="pre">pytest</span></code> with a standard set of options and automatic handling @@ -239,7 +239,7 @@ python_test<span class="o">()</span><span class="w"> </span><span class="o">{</s </div> </section> <section id="running-tests-with-virtualx"> -<span id="index-2"></span><h3>Running tests with virtualx<a class="headerlink" href="#running-tests-with-virtualx" title="Permalink to this heading">¶</a></h3> +<span id="index-2"></span><h3>Running tests with virtualx<a class="headerlink" href="#running-tests-with-virtualx" title="Link to this heading">¶</a></h3> <p>Test suites requiring a display to work correctly can often be appeased usng Xvfb. If the package in question does not start Xvfb directly, <code class="docutils literal notranslate"><span class="pre">virtualx.eclass</span></code> can be used to do that. Whenever possible, it is @@ -275,7 +275,7 @@ this. In other contexts, <code class="docutils literal notranslate"><span class </section> </section> <section id="choosing-the-correct-test-runner"> -<h2>Choosing the correct test runner<a class="headerlink" href="#choosing-the-correct-test-runner" title="Permalink to this heading">¶</a></h2> +<h2>Choosing the correct test runner<a class="headerlink" href="#choosing-the-correct-test-runner" title="Link to this heading">¶</a></h2> <p>There are a few modules used to run tests in Python packages. The most common include the built-in <a class="reference external" href="https://docs.python.org/3/library/unittest.html">unittest</a> module, <a class="reference external" href="https://docs.pytest.org/en/latest/">pytest</a> and <a class="reference external" href="https://github.com/nose-devs/nose">nose</a>. There are also some rarely used test tools and domain-specific solutions, @@ -312,7 +312,7 @@ If you have some free time, convincing upstream to switch from nose to pytest is a worthwhile goal.</p> </section> <section id="undesirable-test-dependencies"> -<h2>Undesirable test dependencies<a class="headerlink" href="#undesirable-test-dependencies" title="Permalink to this heading">¶</a></h2> +<h2>Undesirable test dependencies<a class="headerlink" href="#undesirable-test-dependencies" title="Link to this heading">¶</a></h2> <p>There is a number of packages that are frequently listed as test dependencies upstream but have little to no value for Gentoo users. It is recommended to skip those test dependencies whenever possible. @@ -337,7 +337,7 @@ for the former, and an environment close enough to the latter. Do not use tox in ebuilds.</p> </section> <section id="missing-test-files-in-pypi-packages"> -<h2>Missing test files in PyPI packages<a class="headerlink" href="#missing-test-files-in-pypi-packages" title="Permalink to this heading">¶</a></h2> +<h2>Missing test files in PyPI packages<a class="headerlink" href="#missing-test-files-in-pypi-packages" title="Link to this heading">¶</a></h2> <p>One of the more common test-related problems is that PyPI packages (generated via <code class="docutils literal notranslate"><span class="pre">setup.py</span> <span class="pre">sdist</span></code>) often miss some or all test files. The latter results in no tests being run, the former in test failures @@ -351,7 +351,7 @@ tarball:</p> </div> </section> <section id="importerrors-for-c-extensions"> -<h2>ImportErrors for C extensions<a class="headerlink" href="#importerrors-for-c-extensions" title="Permalink to this heading">¶</a></h2> +<h2>ImportErrors for C extensions<a class="headerlink" href="#importerrors-for-c-extensions" title="Link to this heading">¶</a></h2> <p>Tests are often invoked in such a way that the Python packages and modules from the current directory take precedence over these found in the staging area or build directory. In fact, this is often @@ -440,7 +440,7 @@ missing its configuration (<code class="docutils literal notranslate"><span clas marks or misleading test suite problems.</p> </section> <section id="checklist-for-dealing-with-test-failures"> -<h2>Checklist for dealing with test failures<a class="headerlink" href="#checklist-for-dealing-with-test-failures" title="Permalink to this heading">¶</a></h2> +<h2>Checklist for dealing with test failures<a class="headerlink" href="#checklist-for-dealing-with-test-failures" title="Link to this heading">¶</a></h2> <p>If you see some test failures but do not have a guess as to why they would be happening, try the following for a start:</p> <ol class="arabic simple"> @@ -493,7 +493,7 @@ be skipped.</p></li> </ol> </section> <section id="skipping-problematic-tests"> -<h2>Skipping problematic tests<a class="headerlink" href="#skipping-problematic-tests" title="Permalink to this heading">¶</a></h2> +<h2>Skipping problematic tests<a class="headerlink" href="#skipping-problematic-tests" title="Link to this heading">¶</a></h2> <p>While generally it is preferable to fix tests, sometimes you will face failures that cannot be easily resolved. This especially applies to tests that are broken themselves rather than indicating real problems @@ -544,7 +544,7 @@ simply remove that file. If all tests belonging to the package are broken, you can use <code class="docutils literal notranslate"><span class="pre">RESTRICT=test</span></code> to disable testing altogether.</p> </section> <section id="tests-requiring-internet-access"> -<h2>Tests requiring Internet access<a class="headerlink" href="#tests-requiring-internet-access" title="Permalink to this heading">¶</a></h2> +<h2>Tests requiring Internet access<a class="headerlink" href="#tests-requiring-internet-access" title="Link to this heading">¶</a></h2> <p>One of more common causes of test failures are attempts to use Internet. With Portage blocking network access by default, packages performing tests against remote servers often fail.</p> @@ -584,7 +584,7 @@ distutils_enable_tests<span class="w"> </span>pytest </div> </section> <section id="tests-aborting-due-to-assertions"> -<h2>Tests aborting (due to assertions)<a class="headerlink" href="#tests-aborting-due-to-assertions" title="Permalink to this heading">¶</a></h2> +<h2>Tests aborting (due to assertions)<a class="headerlink" href="#tests-aborting-due-to-assertions" title="Link to this heading">¶</a></h2> <p>There are cases of package’s tests terminating with an unclear error message and backtrace similar to the following:</p> <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="o">=============================</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span>session<span class="w"> </span><span class="nv">starts</span><span class="w"> </span><span class="o">==============================</span> @@ -611,27 +611,27 @@ Current<span class="w"> </span>thread<span class="w"> </span>0x00007f748bc47740< an assertion. Since pytest does not print captured output when exiting due to a signal, you need to disable output capture (using <code class="docutils literal notranslate"><span class="pre">-s</span></code>) to get a more useful error, e.g.:</p> -<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ python3.7 -m pytest -s -=============================================================== test session starts =============================================================== -platform linux -- Python 3.7.8, pytest-6.0.1, py-1.9.0, pluggy-0.13.1 -rootdir: /tmp/sabyenc, configfile: pytest.ini -plugins: asyncio-0.14.0, forked-1.3.0, xdist-1.34.0, hypothesis-5.23.9, mock-3.2.0, flaky-3.7.0, timeout-1.4.2, freezegun-0.4.2 -collected 25 items - -tests/test_decoder.py .............python3.7: src/sabyenc3.c:596: decode_usenet_chunks: Assertion `PyByteArray_Check(PyList_GetItem(Py_input_list, lp))' failed. -Fatal Python error: Aborted - -Current thread 0x00007fb5db746740 (most recent call first): - File "/tmp/sabyenc/tests/testsupport.py", line 73 in sabyenc3_wrapper - File "/tmp/sabyenc/tests/test_decoder.py", line 117 in test_empty_size_pickles - File "/usr/lib/python3.7/site-packages/_pytest/python.py", line 180 in pytest_pyfunc_call - File "/usr/lib/python3.7/site-packages/pluggy/callers.py", line 187 in _multicall - File "/usr/lib/python3.7/site-packages/pluggy/manager.py", line 87 in <lambda> - [...] - File "/usr/lib/python3.7/site-packages/pytest/__main__.py", line 7 in <module> - File "/usr/lib/python3.7/runpy.py", line 85 in _run_code - File "/usr/lib/python3.7/runpy.py", line 193 in _run_module_as_main -Aborted (core dumped) +<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>python3.7<span class="w"> </span>-m<span class="w"> </span>pytest<span class="w"> </span>-s +<span class="o">===============================================================</span><span class="w"> </span><span class="nb">test</span><span class="w"> </span>session<span class="w"> </span><span class="nv">starts</span><span class="w"> </span><span class="o">===============================================================</span> +platform<span class="w"> </span>linux<span class="w"> </span>--<span class="w"> </span>Python<span class="w"> </span><span class="m">3</span>.7.8,<span class="w"> </span>pytest-6.0.1,<span class="w"> </span>py-1.9.0,<span class="w"> </span>pluggy-0.13.1 +rootdir:<span class="w"> </span>/tmp/sabyenc,<span class="w"> </span>configfile:<span class="w"> </span>pytest.ini +plugins:<span class="w"> </span>asyncio-0.14.0,<span class="w"> </span>forked-1.3.0,<span class="w"> </span>xdist-1.34.0,<span class="w"> </span>hypothesis-5.23.9,<span class="w"> </span>mock-3.2.0,<span class="w"> </span>flaky-3.7.0,<span class="w"> </span>timeout-1.4.2,<span class="w"> </span>freezegun-0.4.2 +collected<span class="w"> </span><span class="m">25</span><span class="w"> </span>items + +tests/test_decoder.py<span class="w"> </span>.............python3.7:<span class="w"> </span>src/sabyenc3.c:596:<span class="w"> </span>decode_usenet_chunks:<span class="w"> </span>Assertion<span class="w"> </span><span class="sb">`</span>PyByteArray_Check<span class="o">(</span>PyList_GetItem<span class="o">(</span>Py_input_list,<span class="w"> </span>lp<span class="o">))</span><span class="err">'</span><span class="w"> </span>failed. +Fatal<span class="w"> </span>Python<span class="w"> </span>error:<span class="w"> </span>Aborted + +Current<span class="w"> </span>thread<span class="w"> </span>0x00007fb5db746740<span class="w"> </span><span class="o">(</span>most<span class="w"> </span>recent<span class="w"> </span>call<span class="w"> </span>first<span class="o">)</span>: +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/tmp/sabyenc/tests/testsupport.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">73</span><span class="w"> </span><span class="k">in</span><span class="w"> </span>sabyenc3_wrapper +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/tmp/sabyenc/tests/test_decoder.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">117</span><span class="w"> </span><span class="k">in</span><span class="w"> </span>test_empty_size_pickles +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/usr/lib/python3.7/site-packages/_pytest/python.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">180</span><span class="w"> </span><span class="k">in</span><span class="w"> </span>pytest_pyfunc_call +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/usr/lib/python3.7/site-packages/pluggy/callers.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">187</span><span class="w"> </span><span class="k">in</span><span class="w"> </span>_multicall +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/usr/lib/python3.7/site-packages/pluggy/manager.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">87</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><lambda> +<span class="w"> </span><span class="o">[</span>...<span class="o">]</span> +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/usr/lib/python3.7/site-packages/pytest/__main__.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">7</span><span class="w"> </span><span class="k">in</span><span class="w"> </span><module> +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/usr/lib/python3.7/runpy.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">85</span><span class="w"> </span><span class="k">in</span><span class="w"> </span>_run_code +<span class="w"> </span>File<span class="w"> </span><span class="s2">"/usr/lib/python3.7/runpy.py"</span>,<span class="w"> </span>line<span class="w"> </span><span class="m">193</span><span class="w"> </span><span class="k">in</span><span class="w"> </span>_run_module_as_main +Aborted<span class="w"> </span><span class="o">(</span>core<span class="w"> </span>dumped<span class="o">)</span> </pre></div> </div> <p>Now the message clearly indicates the failed assertion.</p> @@ -647,7 +647,7 @@ $<span class="w"> </span>pytest<span class="w"> </span>-s </div> </section> <section id="installing-extra-dependencies-in-test-environment-pep-517-mode"> -<h2>Installing extra dependencies in test environment (PEP 517 mode)<a class="headerlink" href="#installing-extra-dependencies-in-test-environment-pep-517-mode" title="Permalink to this heading">¶</a></h2> +<h2>Installing extra dependencies in test environment (PEP 517 mode)<a class="headerlink" href="#installing-extra-dependencies-in-test-environment-pep-517-mode" title="Link to this heading">¶</a></h2> <p>Rarely, the test suite expects some package being installed that does not fit being packaged and installed system-wide. For example, isort’s tests use a few example plugins that are not useful to end @@ -774,7 +774,7 @@ into it for the purpose of testing. Note that <code class="docutils literal not ©2020, Michał Górny, license: CC BY 4.0. | - Powered by <a href="http://sphinx-doc.org/">Sphinx 7.1.2</a> + Powered by <a href="http://sphinx-doc.org/">Sphinx 7.2.6</a> & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.13</a> | |