diff --git a/testing/coverage.rst b/testing/coverage.rst index 0ebaf4b020..f0da943494 100644 --- a/testing/coverage.rst +++ b/testing/coverage.rst @@ -4,6 +4,14 @@ Increase test coverage ====================== +.. raw:: html + + + Python development follows a practice that all semantic changes and additions to the language and :abbr:`stdlib (standard library)` are accompanied by appropriate unit tests. Unfortunately Python was in existence for a long time @@ -87,23 +95,35 @@ just built, and this built version of Python will not see packages installed into your default version of Python. One option is to use a virtual environment to install coverage. -On Unix run:: +.. tab:: Unix + + Run: + + .. code-block:: shell + + ./python -m venv ../cpython-venv + source ../cpython-venv/bin/activate + pip install coverage + +.. tab:: macOS - ./python -m venv ../cpython-venv - source ../cpython-venv/bin/activate - pip install coverage + On :ref:`most ` macOS systems run: -On :ref:`most ` macOS systems run:: + .. code-block:: shell - ./python.exe -m venv ../cpython-venv - source ../cpython-venv/bin/activate - pip install coverage + ./python.exe -m venv ../cpython-venv + source ../cpython-venv/bin/activate + pip install coverage -On Windows run:: +.. tab:: Windows - python.bat -m venv ..\\cpython-venv - ..\\cpython-venv\\Scripts\\activate.bat - pip install coverage + Run: + + .. code-block:: dosbatch + + python.bat -m venv ..\\cpython-venv + ..\\cpython-venv\\Scripts\\activate.bat + pip install coverage You can now use python without the ./ for the rest of these instructions, as long as your venv is activated. For more info on venv see `Virtual Environment @@ -231,19 +251,49 @@ Measuring coverage of C code with gcov and lcov It's also possible to measure the function, line and branch coverage of Python's C code. Right now only GCC with `gcov`_ is supported. In order to -create an instrumented build of Python with gcov, run:: +create an instrumented build of Python with gcov, run: + +.. tab:: Unix/macOS + + .. code-block:: shell + + make coverage + +.. tab:: Windows - make coverage + .. code-block:: dosbatch + + .\make coverage Then run some code and gather coverage data with the ``gcov`` command. In -order to create a HTML report you can install `lcov`_. The command:: +order to create a HTML report you can install `lcov`_. The command: + +.. tab:: Unix/macOS + + .. code-block:: shell + + make coverage-lcov + +.. tab:: Windows + + .. code-block:: dosbatch - make coverage-lcov + .\make coverage-lcov assembles coverage data, removes 3rd party and system libraries and finally -creates a report. You can skip both steps and just run:: +creates a report. You can skip both steps and just run: + +.. tab:: Unix/macOS + + .. code-block:: shell + + make coverage-report + +.. tab:: Windows + + .. code-block:: dosbatch - make coverage-report + .\make coverage-report if you like to generate a coverage report for Python's stdlib tests. It takes about 20 to 30 minutes on a modern computer.