diff --git a/testing/run-write-tests.rst b/testing/run-write-tests.rst index 7efe8307b..58e56297d 100644 --- a/testing/run-write-tests.rst +++ b/testing/run-write-tests.rst @@ -17,14 +17,27 @@ 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 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 +45,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 +138,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 +164,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