diff options
| -rw-r--r-- | doc/cmd.rst | 18 | ||||
| -rw-r--r-- | doc/contexts.rst | 29 | ||||
| -rw-r--r-- | doc/python-coverage.1.txt | 13 |
3 files changed, 46 insertions, 14 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index 3551e90d..c6d5fe27 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -363,8 +363,12 @@ command line:: ------------------------------------------------------- TOTAL 76 10 87% -The ``--skip-covered`` switch will leave out any file with 100% coverage, -letting you focus on the files that still need attention. +The ``--skip-covered`` switch will skip any file with 100% coverage, letting +you focus on the files that still need attention. + +If you have :ref:`recorded contexts <contexts>`, the ``--contexts`` option lets +you choose which contexts to report on. See :ref:`context_reporting` for +details. Other common reporting options are described above in :ref:`cmd_reporting`. @@ -409,8 +413,14 @@ is a data file that is used to speed up reporting the next time. If you generate a new report into the same directory, coverage.py will skip generating unchanged pages, making the process faster. -The ``--skip-covered`` switch will leave out any file with 100% coverage, -letting you focus on the files that still need attention. +The ``--skip-covered`` switch will skip any file with 100% coverage, letting +you focus on the files that still need attention. + +If you have :ref:`recorded contexts <contexts>`, the ``--contexts`` option lets +you choose which contexts to report on, and the ``--show-contexts`` option will +annotate lines with the contexts that ran them. See :ref:`context_reporting` +for details. + .. _cmd_annotation: diff --git a/doc/contexts.rst b/doc/contexts.rst index f1796aae..e8aa4ed4 100644 --- a/doc/contexts.rst +++ b/doc/contexts.rst @@ -44,10 +44,10 @@ the configuration file. Dynamic contexts ---------------- -Dynamic contexts are found during execution. They started from the question, -"what test ran this line?," but have been generalized to allow any kind of -context tracking. As execution proceeds, the dynamic context changes -to record the context of execution. Separate data is recorded for each +Dynamic contexts are found during execution. They are most commonly used to +answer the question "what test ran this line?," but have been generalized to +allow any kind of context tracking. As execution proceeds, the dynamic context +changes to record the context of execution. Separate data is recorded for each context, so that it can be analyzed later. There are three ways to enable dynamic contexts: @@ -68,7 +68,7 @@ The ``[run] dynamic_context`` setting has only one option now. Set it to Each test function you run will be considered a separate dynamic context, and coverage data will be segregated for each. A test function is any function -whose names starts with "test". +whose name starts with "test". If you have both a static context and a dynamic context, they are joined with a pipe symbol to be recorded as a single string. @@ -80,10 +80,23 @@ then the code run by the test runner before (and between) tests will be in the empty context. +.. _context_reporting: + Context reporting ----------------- -There is currently no support for using contexts during reporting. I'm -interested to `hear your ideas`__ for what would be useful. +The ``coverage report`` and ``coverage html`` commands both accept +``--contexts`` option, a comma-separated list of shell-style wildcards. The +report will be limited to the contexts that match one of those contexts. + +The ``coverage html`` command also has ``--show-contexts``. If set, the HTML +report will include an annotation on each covered line indicating the number of +contexts that executed the line. Hovering over the annotation displays a list +of the contexts. + + +Raw data +-------- -__ https://nedbatchelder.com/site/aboutned.html +For more advanced reporting or analysis, the .coverage data file is a SQLite +database. TODO: explain the schema. diff --git a/doc/python-coverage.1.txt b/doc/python-coverage.1.txt index a415f080..1a06bf2e 100644 --- a/doc/python-coverage.1.txt +++ b/doc/python-coverage.1.txt @@ -8,7 +8,7 @@ measure code coverage of Python program execution :Author: Ned Batchelder <ned@nedbatchelder.com> :Author: |author| -:Date: 2018-05-28 +:Date: 2019-06-11 :Copyright: Apache 2.0 license, attribution and disclaimer required. :Manual section: 1 :Manual group: Coverage.py @@ -128,6 +128,9 @@ COMMAND REFERENCE Options: + \--contexts `PAT,...` + Only include contexts that match one of the patterns. + \-d `DIR`, --directory `DIR` Write the output files to `DIR`. @@ -137,6 +140,9 @@ COMMAND REFERENCE \-i, --ignore-errors Ignore errors while reading source files. + \--show-contexts + Annotate lines with the contexts that executed them. + \--skip-covered Skip files with 100% coverage. @@ -149,6 +155,9 @@ COMMAND REFERENCE Options: + \--contexts `PAT,...` + Only include contexts that match one of the patterns. + \--fail-under `MIN` Exit with a status of 2 if the total coverage is less than `MIN`. @@ -229,7 +238,7 @@ HISTORY The |command| command is a Python program which calls the ``coverage`` Python library to do all the work. -The library was originally developed by Gareth Rees, and is now developed +It was originally developed by Gareth Rees, and is now developed by Ned Batchelder and many others. This manual page was written by |author|. |