From 33f008d8e8e2fcb58b5490a87fd0679b04bfd667 Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Thu, 26 Oct 2023 15:30:06 -0500 Subject: [PATCH 1/2] add tabs for different system commands --- testing/run-write-tests.rst | 147 +++++++++++++++++++++++++++++++----- 1 file changed, 129 insertions(+), 18 deletions(-) diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 7efe8307b6..103368adb2 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -17,14 +17,29 @@ Running The shortest, simplest way of running the test suite is the following command from the root directory of your checkout (after you have -:ref:`built Python `):: +:ref:`built Python `): - ./python -m test +.. tab:: Unix -You may need to change this command as follows throughout this section. -On :ref:`most ` macOS systems, replace :file:`./python` -with :file:`./python.exe`. On Windows, use :file:`python.bat`. If using -Python 2.7, replace ``test`` with ``test.regrtest``. + .. code-block:: shell + + ./python -m test + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test + + This works on :ref:`most ` macOS systems. + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test + +If using Python 2.7, replace ``test`` with ``test.regrtest``. This will run the majority of tests, but exclude a small portion of them; these excluded tests use special kinds of resources: for example, accessing the @@ -32,25 +47,89 @@ Internet, or trying to play a sound or to display a graphical interface on your desktop. They are disabled by default so that running the test suite is not too intrusive. To enable some of these additional tests (and for other flags which can help debug various issues such as reference leaks), read -the help text:: +the help text: + +.. tab:: Unix + + .. code-block:: shell + + ./python -m test -h + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test -h - ./python -m test -h +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test -h If you want to run a single test file, simply specify the test file name (without the extension) as an argument. You also probably want to enable -verbose mode (using ``-v``), so that individual failures are detailed:: +verbose mode (using ``-v``), so that individual failures are detailed: + +.. tab:: Unix + + .. code-block:: shell + + ./python -m test -v test_abc + +.. tab:: macOS + + .. code-block:: shell - ./python -m test -v test_abc + ./python.exe -m test -v test_abc + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test -v test_abc To run a single test case, use the ``unittest`` module, providing the import -path to the test case:: +path to the test case: + +.. tab:: Unix + + .. code-block:: shell + + ./python -m unittest -v test.test_abc.TestABC_Py + +.. tab:: macOS - ./python -m unittest -v test.test_abc.TestABC_Py + .. code-block:: shell + + ./python.exe -m unittest -v test.test_abc.TestABC_Py + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m unittest -v test.test_abc.TestABC_Py Some test modules also support direct invocation, -which might be useful for IDEs and local debugging:: +which might be useful for IDEs and local debugging: + +.. tab:: Unix + + .. code-block:: shell + + ./python Lib/test/test_typing.py - ./python Lib/test/test_typing.py +.. tab:: macOS + + .. code-block:: shell + + ./python.exe Lib/test/test_typing.py + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat Lib/test/test_typing.py But, there are several important notes: @@ -61,9 +140,25 @@ But, there are several important notes: most likely it does not support direct invocation. If you have a multi-core or multi-CPU machine, you can enable parallel testing -using several Python processes so as to speed up things:: +using several Python processes so as to speed up things: + +.. tab:: Unix + + .. code-block:: shell - ./python -m test -j0 + ./python -m test -j0 + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -m test -j0 + +.. tab:: Windows + + .. code-block:: dosbatch + + .\python.bat -m test -j0 If you are running a version of Python prior to 3.3 you must specify the number of processes to run simultaneously (e.g. ``-j2``). @@ -71,9 +166,25 @@ of processes to run simultaneously (e.g. ``-j2``). .. _strenuous_testing: Finally, if you want to run tests under a more strenuous set of settings, you -can run ``test`` as:: +can run ``test`` as: + +.. tab:: Unix + + .. code-block:: shell + + ./python -bb -E -Wd -m test -r -w -uall + +.. tab:: macOS + + .. code-block:: shell + + ./python.exe -bb -E -Wd -m test -r -w -uall + +.. tab:: Windows + + .. code-block:: dosbatch - ./python -bb -E -Wd -m test -r -w -uall + .\python.bat -bb -E -Wd -m test -r -w -uall The various extra flags passed to Python cause it to be much stricter about various things (the ``-Wd`` flag should be ``-W error`` at some point, but the From 1f466d6e198351852a425520dc461ee223f7393a Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Thu, 26 Oct 2023 20:26:45 -0500 Subject: [PATCH 2/2] remove bit about running tests on Python 2.7 --- testing/run-write-tests.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 103368adb2..58e56297d0 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -39,8 +39,6 @@ from the root directory of your checkout (after you have .\python.bat -m test -If using Python 2.7, replace ``test`` with ``test.regrtest``. - This will run the majority of tests, but exclude a small portion of them; these excluded tests use special kinds of resources: for example, accessing the Internet, or trying to play a sound or to display a graphical interface on