Plugin support for dynamic context (#783)

* Introduce a new plugin type: dynamic context labels.

* Test dynamic context plugins

* Helper method to get full paths to measured files

* Get correct filenames on all OS

* Improve wording

1 files changed, 31 insertions, 0 deletions

diff --git a/coverage/plugin.py b/coverage/plugin.py
index f65d419c..e817cf2f 100644
--- a/coverage/plugin.py
+++ b/coverage/plugin.py
@@ -78,6 +78,26 @@ change the configuration.
 In your ``coverage_init`` function, use the ``add_configurer`` method to
 register your configurer.
 
+Dynamic Contexts
+================
+
+.. versionadded:: 5.0
+
+Context 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.
+
+In your ``coverage_init`` function, use the ``add_dynamic_context`` method to
+register your file tracer.
+
 """
 
 from coverage import files
@@ -140,6 +160,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.
+
+        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.
+
+        """
+        return None
+
     def find_executable_files(self, src_dir):       # pylint: disable=unused-argument
         """Yield all of the executable files in `src_dir`, recursively.