feat: `coverage run` now sets the COVERAGE_RUN environment variable

5 files changed, 35 insertions, 7 deletions

diff --git a/CHANGES.rst b/CHANGES.rst
index 81e02732..95b34a77 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -23,12 +23,18 @@ This list is detailed and covers changes in each pre-release version.
 Unreleased
 ----------
 
-- When sorting human-readable names, numeric components are sorted correctly:
-  file10.py will appear after file9.py.  This applies to file names, module
-  names, environment variables, and test contexts.
+- Feature: Coverage now sets an environment variable, ``COVERAGE_RUN`` when
+  running your code with the ``coverage run`` command.  The value is not
+  important, and may change in the future.  Closes `issue 553`_.
 
-- Branch coverage measurement is faster, though you might only notice on
-  code that is executed many times, such as long-running loops.
+- Fix: When sorting human-readable names, numeric components are sorted
+  correctly: file10.py will appear after file9.py.  This applies to file names,
+  module names, environment variables, and test contexts.
+
+- Performance: Branch coverage measurement is faster, though you might only
+  notice on code that is executed many times, such as long-running loops.
+
+ .. _issue 553: https://github.com/nedbat/coveragepy/issues/553
 
 
 .. _changes_602:
diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index dfdbd1c7..5f972035 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -6,6 +6,7 @@
 
 import glob
 import optparse     # pylint: disable=deprecated-module
+import os
 import os.path
 import shlex
 import sys
@@ -739,6 +740,8 @@ class CoverageScript:
                     )
                     return ERR
 
+        os.environ["COVERAGE_RUN"] = "true"
+
         runner = PyRunner(args, as_module=bool(options.module))
         runner.prepare()
 
diff --git a/coverage/version.py b/coverage/version.py
index 8aa3bcf7..2b96b696 100644
--- a/coverage/version.py
+++ b/coverage/version.py
@@ -5,7 +5,7 @@
 # This file is exec'ed in setup.py, don't import anything!
 
 # Same semantics as sys.version_info.
-version_info = (6, 0, 3, "alpha", 0)
+version_info = (6, 1, 0, "alpha", 0)
 
 
 def _make_version(major, minor, micro, releaselevel, serial):
diff --git a/doc/cmd.rst b/doc/cmd.rst
index b4bf41ab..1a54043d 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -137,6 +137,10 @@ If your coverage results seem to be overlooking code that you know has been
 executed, try running coverage.py again with the ``--timid`` flag.  This uses a
 simpler but slower trace method, and might be needed in rare cases.
 
+Coverage.py sets an environment variable, ``COVERAGE_RUN`` to indicate that
+your code is running under coverage measurement.  The value is not relevant,
+and may change in the future.
+
 
 .. _cmd_warnings:
 
diff --git a/tests/test_process.py b/tests/test_process.py
index c9a2f8ee..29ce6071 100644
--- a/tests/test_process.py
+++ b/tests/test_process.py
@@ -39,7 +39,7 @@ class ProcessTest(CoverageTest):
         self.run_command("coverage run mycode.py")
         self.assert_exists(".coverage")
 
-    def test_environment(self):
+    def test_tests_dir_is_importable(self):
         # Checks that we can import modules from the tests directory at all!
         self.make_file("mycode.py", """\
             import covmod1
@@ -53,6 +53,21 @@ class ProcessTest(CoverageTest):
         self.assert_exists(".coverage")
         assert out == 'done\n'
 
+    def test_coverage_run_envvar_is_in_coveragerun(self):
+        # Test that we are setting COVERAGE_RUN when we run.
+        self.make_file("envornot.py", """\
+            import os
+            print(os.environ.get("COVERAGE_RUN", "nope"))
+            """)
+        self.del_environ("COVERAGE_RUN")
+        # Regular Python doesn't have the environment variable.
+        out = self.run_command("python envornot.py")
+        assert out == "nope\n"
+        self.del_environ("COVERAGE_RUN")
+        # But `coverage run` does have it.
+        out = self.run_command("coverage run envornot.py")
+        assert out == "true\n"
+
     def make_b_or_c_py(self):
         """Create b_or_c.py, used in a few of these tests."""
         # "b_or_c.py b" will run 6 lines.