diff options
| -rw-r--r-- | CHANGES.rst | 5 | ||||
| -rw-r--r-- | README.rst | 6 | ||||
| -rw-r--r-- | doc/cmd.rst | 6 | ||||
| -rw-r--r-- | doc/config.rst | 5 | ||||
| -rw-r--r-- | doc/contexts.rst | 51 | ||||
| -rw-r--r-- | doc/index.rst | 1 |
6 files changed, 71 insertions, 3 deletions
diff --git a/CHANGES.rst b/CHANGES.rst index 8f8cd32b..089fec7f 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -17,6 +17,11 @@ Change history for Coverage.py Unreleased ---------- +- Context support: static contexts let you specify a label for a coverage run, + which is recorded in the data, and retained when you combine files. See + :ref:`contexts` for more information. Currently, only static contexts are + supported, with no reporting features. + - Environment variable substitution in configuration files now supports two syntaxes for controlling the behavior of undefined variables: if ``VARNAME`` is not defined, ``${VARNAME?}`` will raise an error, and ``${VARNAME-default @@ -19,7 +19,8 @@ library to determine which lines are executable, and which have been executed. Coverage.py runs on many versions of Python: -* CPython 2.7 and 3.4 through 3.7. +* CPython 2.7. +* CPython 3.4 through 3.7. * PyPy2 6.0 and PyPy3 6.0. * Jython 2.7.1, though not for reporting. * IronPython 2.7.7, though not for reporting. @@ -31,7 +32,8 @@ Documentation is on `Read the Docs`_. Code repository and issue tracker are on .. _GitHub: https://github.com/nedbat/coveragepy -**New in 5.0:** SQLite data storage, dropped support for Python 2.6 and 3.3. +**New in 5.0:** SQLite data storage, contexts, dropped support for Python 2.6 +and 3.3. New in 4.5: Configurator plug-ins. diff --git a/doc/cmd.rst b/doc/cmd.rst index 908b2ee9..0d1a05b5 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -69,7 +69,7 @@ control, and can provide options that other invocation techniques (like test runner plugins) may not offer. See :ref:`config` for more details. -.. _cmd_execution: +.. _cmd_run: Execution --------- @@ -118,6 +118,10 @@ configuration file for all options. .. _gevent: http://www.gevent.org/ .. _eventlet: http://eventlet.net/ +You can specify a :ref:`static context <contexts>` for a coverage run with +``--context``. This can be any label you want, and will be recorded with the +data. See :ref:`contexts` for more information. + By default, coverage.py does not measure code installed with the Python interpreter, for example, the standard library. If you want to measure that code as well as your own, add the ``-L`` (or ``--pylib``) flag. diff --git a/doc/config.rst b/doc/config.rst index 666a1321..b8117a43 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -132,6 +132,11 @@ Before version 4.2, this option only accepted a single string. .. versionadded:: 4.0 +``context`` (string): the static context to record for this coverage run. See +:ref:`contexts` for more information + +.. versionadded:: 5.0 + ``data_file`` (string, default ".coverage"): the name of the data file to use for storing or reporting coverage. This value can include a path to another directory. diff --git a/doc/contexts.rst b/doc/contexts.rst new file mode 100644 index 00000000..c1d4a173 --- /dev/null +++ b/doc/contexts.rst @@ -0,0 +1,51 @@ +.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0 +.. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt + +.. _contexts: + +==================== +Measurement Contexts +==================== + +.. :history: 20180921T085400, new for 5.0 + +.. versionadded:: 5.0 + +Coverage.py measures whether code was run, but it can also record the context +in which it was run. This can provide more information to help you understand +the behavior of your tests. + +There are two kinds of context: static and dynamic. Static contexts are fixed +for an entire run, and are set explicitly with an option. + +Dynamic contexts are coming soon. + + +Static contexts +--------------- + +A static context is set by an option when you run coverage.py. The value is +fixed for the duration of a run. They can be any text you like, for example, +"python3" or "with_numpy". The context is recorded with the data. + +When you :ref:`combine multiple data files <cmd_combining>` together, they can +have differing contexts. All of the information is retained, so that the +different contexts are correctly recorded in the combined file. + +A static context is specified with the ``--context=CONTEXT`` option to +:ref:`coverage run <cmd_run>`. + + +Dynamic contexts +---------------- + +Not implemented yet. + + +Context reporting +----------------- + +There is currently no support for using contexts during reporting. I'm +interested to `hear your ideas`__ for what would be useful. + +__ https://nedbatchelder.com/site/aboutned.html diff --git a/doc/index.rst b/doc/index.rst index 0a795011..149eba07 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -206,6 +206,7 @@ More information excluding branch subprocess + contexts api howitworks plugins |