Minimal docs for dynamic contexts

2 files changed, 35 insertions, 6 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 089fec7f..b449797b 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -19,8 +19,27 @@ 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.
+  :ref:`contexts` for more information.
+
+- Dynamic contexts: specifying ``[run] dynamic_context = test_function`` in the
+  config file will record the test function name as a dynamic context during
+  execution.  This is the core of "Who Tests What" (`issue 170`_).  Things to
+  note:
+
+  - There is no reporting support yet.  Use SQLite to query the .coverage file
+    for information.  Ideas are welcome about how reporting could be extended
+    to use this data.
+
+  - There's a noticeable slow-down before any test is run.
+
+  - Data files will now be roughly N times larger, where N is the number of
+    tests you have.  Combining data files is therefore also N times slower.
+
+  - No other values for ``dynamic_context`` are recognized yet.  Let me know
+    what else would be useful.  I'd like to use a pytest plugin to get better
+    information directly from pytest, for example.
+
+.. _issue 170: https://github.com/nedbat/coveragepy/issues/170
 
 - Environment variable substitution in configuration files now supports two
   syntaxes for controlling the behavior of undefined variables: if ``VARNAME``
diff --git a/doc/contexts.rst b/doc/contexts.rst
index c1d4a173..1f1ce763 100644
--- a/doc/contexts.rst
+++ b/doc/contexts.rst
@@ -16,9 +16,8 @@ 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.
+for an entire run, and are set explicitly with an option.  Dynamic contexts
+change over the course of a single run.
 
 
 Static contexts
@@ -39,7 +38,18 @@ A static context is specified with the ``--context=CONTEXT`` option to
 Dynamic contexts
 ----------------
 
-Not implemented yet.
+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::
+
+    [run]
+    dynamic_context = test_function
+
+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".
+
+Ideas are welcome for other dynamic contexts that would be useful.
 
 
 Context reporting