Skip to content

Commit

Permalink
Add inline tabs on Running and Writing Tests page for commands on dif…
Browse files Browse the repository at this point in the history
…ferent systems (#1206)

Remove bit about running tests on Python 2.7
  • Loading branch information
lancegoyke committed Oct 27, 2023
1 parent 2a6cbd2 commit cd06b15
Showing 1 changed file with 127 additions and 18 deletions.
145 changes: 127 additions & 18 deletions testing/run-write-tests.rst
Original file line number Diff line number Diff line change
Expand Up @@ -17,40 +17,117 @@ 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 <compiling>`)::
:ref:`built Python <compiling>`):

./python -m test
.. tab:: Unix

You may need to change this command as follows throughout this section.
On :ref:`most <mac-python.exe>` 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 <mac-python.exe>` macOS systems.

.. tab:: Windows

.. code-block:: dosbatch
.\python.bat -m test
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
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:

Expand All @@ -61,19 +138,51 @@ 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``).

.. _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
Expand Down

0 comments on commit cd06b15

Please sign in to comment.