diff options
| -rw-r--r-- | coverage/plugin.py | 38 | ||||
| -rw-r--r-- | doc/contexts.rst | 23 |
2 files changed, 43 insertions, 18 deletions
diff --git a/coverage/plugin.py b/coverage/plugin.py index e817cf2f..5f66dfb9 100644 --- a/coverage/plugin.py +++ b/coverage/plugin.py @@ -14,6 +14,9 @@ behavior: * Configurers add custom configuration, using Python code to change the configuration. +* Dynamic context switchers decide when the dynamic context has changed, for + example, to record what test function produced the coverage. + To write a coverage.py plug-in, create a module with a subclass of :class:`~coverage.CoveragePlugin`. You will override methods in your class to participate in various aspects of coverage.py's processing. @@ -78,25 +81,29 @@ change the configuration. In your ``coverage_init`` function, use the ``add_configurer`` method to register your configurer. -Dynamic Contexts -================ +.. _dynamic_context_plugins: + +Dynamic Context Switchers +========================= .. versionadded:: 5.0 -Context plugins implement the :meth:`~coverage.CoveragePlugin.dynamic_context` method -to dynamically compute the context label for each measured frame. +Dynamic context switcher plugins implement the +:meth:`~coverage.CoveragePlugin.dynamic_context` method to dynamically compute +the context label for each measured frame. Computed context labels are useful when you want to group measured data without modifying the source code. -For example, you could write a plugin that check `frame.f_code` to inspect -the currently executed method, and set label to a fully qualified method -name if it's an instance method of `unittest.TestCase` and the method name -starts with 'test'. Such plugin would provide basic coverage grouping by test -and could be used with test runners that have no built-in coveragepy support. +For example, you could write a plugin that checks `frame.f_code` to inspect +the currently executed method, and set the context label to a fully qualified +method name if it's an instance method of `unittest.TestCase` and the method +name starts with 'test'. Such a plugin would provide basic coverage grouping +by test and could be used with test runners that have no built-in coveragepy +support. In your ``coverage_init`` function, use the ``add_dynamic_context`` method to -register your file tracer. +register your dynamic context switcher. """ @@ -161,12 +168,17 @@ class CoveragePlugin(object): _needs_to_implement(self, "file_reporter") def dynamic_context(self, frame): # pylint: disable=unused-argument - """Get dynamically computed context label for collected data. + """Get the dynamically computed context label for `frame`. Plug-in type: dynamic context. - This method is invoked for each frame. If it returns a string, - a new context label is set for this and deeper frames. + This method is invoked for each frame when outside of a dynamic + context, to see if a new dynamic context should be started. If it + returns a string, a new context label is set for this and deeper + frames. The dynamic context ends when this frame returns. + + Returns a string to start a new dynamic context, or None if no new + context should be started. """ return None diff --git a/doc/contexts.rst b/doc/contexts.rst index 1f1ce763..8222747c 100644 --- a/doc/contexts.rst +++ b/doc/contexts.rst @@ -4,7 +4,7 @@ .. _contexts: ==================== -Measurement Contexts +Measurement contexts ==================== .. :history: 20180921T085400, new for 5.0 @@ -32,15 +32,28 @@ 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>`. +:ref:`the coverage run command <cmd_run>`, or the ``[run] context`` setting in +the configuration file. Dynamic contexts ---------------- -Dynamic contexts are found during execution. There is currently support for -one kind: test function names. Set the ``dynamic_context`` option to -``test_function`` in the configuration file:: +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 +context, so that it can be analyzed later. + +There are two ways to enable dynamic contexts: + +* you can set the ``[run] dynamic_context`` option in your .coveragerc file, or + +* you can enable a :ref:`dynamic context switcher <dynamic_context_plugins>` + plugin. + +The ``[run] dynamic_context`` setting has only one option now. Set it to +``test_function`` to start a new dynamic context for every test function:: [run] dynamic_context = test_function |