feat: the debug output file can be specified in the config file. #1319

CHANGES.rst

@@ -20,8 +20,14 @@ development at the same time, such as 4.5.x and 5.0.
 Unreleased
 ----------
 
+- Added: the debug output file can now be specified with ``[run] debug_file``
+  in the configuration file.  Closes `issue 1319`_.
+
 - Typing: all product and test code has type annotations.
 
+.. _issue 1319: https://github.com/nedbat/coveragepy/issues/1319
+
+
 .. scriv-start-here
 
 .. _changes_7-0-5:

coverage/config.py

@@ -199,6 +199,7 @@ def __init__(self) -> None:
         self.cover_pylib = False
         self.data_file = ".coverage"
         self.debug: List[str] = []
+        self.debug_file: Optional[str] = None
         self.disable_warnings: List[str] = []
         self.dynamic_context: Optional[str] = None
         self.parallel = False
@@ -375,6 +376,7 @@ def copy(self) -> CoverageConfig:
         ('cover_pylib', 'run:cover_pylib', 'boolean'),
         ('data_file', 'run:data_file'),
         ('debug', 'run:debug', 'list'),
+        ('debug_file', 'run:debug_file'),
         ('disable_warnings', 'run:disable_warnings', 'list'),
         ('dynamic_context', 'run:dynamic_context'),
         ('parallel', 'run:parallel', 'boolean'),

coverage/control.py

@@ -303,10 +303,8 @@ def _init(self) -> None:
 
         self._inited = True
 
-        # Create and configure the debugging controller. COVERAGE_DEBUG_FILE
-        # is an environment variable, the name of a file to append debug logs
-        # to.
-        self._debug = DebugControl(self.config.debug, self._debug_file)
+        # Create and configure the debugging controller.
+        self._debug = DebugControl(self.config.debug, self._debug_file, self.config.debug_file)
 
         if "multiprocessing" in (self.config.concurrency or ()):
             # Multi-processing uses parallel for the subprocesses, so also use

coverage/debug.py

@@ -39,7 +39,12 @@ class DebugControl:
 
     show_repr_attr = False      # For AutoReprMixin
 
-    def __init__(self, options: Iterable[str], output: Optional[IO[str]]) -> None:
+    def __init__(
+        self,
+        options: Iterable[str],
+        output: Optional[IO[str]],
+        file_name: Optional[str] = None,
+    ) -> None:
         """Configure the options and output file for debugging."""
         self.options = list(options) + FORCED_DEBUG
         self.suppress_callers = False
@@ -49,6 +54,7 @@ def __init__(self, options: Iterable[str], output: Optional[IO[str]]) -> None:
             filters.append(add_pid_and_tid)
         self.output = DebugOutputFile.get_one(
             output,
+            file_name=file_name,
             show_process=self.should('process'),
             filters=filters,
         )
@@ -313,6 +319,7 @@ def __init__(
     def get_one(
         cls,
         fileobj: Optional[IO[str]] = None,
+        file_name: Optional[str] = None,
         show_process: bool = True,
         filters: Iterable[Callable[[str], str]] = (),
         interim: bool = False,
@@ -321,9 +328,9 @@ def get_one(
 
         If `fileobj` is provided, then a new DebugOutputFile is made with it.
 
-        If `fileobj` isn't provided, then a file is chosen
-        (COVERAGE_DEBUG_FILE, or stderr), and a process-wide singleton
-        DebugOutputFile is made.
+        If `fileobj` isn't provided, then a file is chosen (`file_name` if
+        provided, or COVERAGE_DEBUG_FILE, or stderr), and a process-wide
+        singleton DebugOutputFile is made.
 
         `show_process` controls whether the debug file adds process-level
         information, and filters is a list of other message filters to apply.
@@ -345,12 +352,14 @@ def get_one(
         singleton_module = sys.modules.get(cls.SYS_MOD_NAME)
         the_one, is_interim = getattr(singleton_module, cls.SINGLETON_ATTR, (None, True))
         if the_one is None or is_interim:
-            if fileobj is None:
-                debug_file_name = os.environ.get("COVERAGE_DEBUG_FILE", FORCED_DEBUG_FILE)
-                if debug_file_name in ("stdout", "stderr"):
-                    fileobj = getattr(sys, debug_file_name)
-                elif debug_file_name:
-                    fileobj = open(debug_file_name, "a")
+            if file_name is not None:
+                fileobj = open(file_name, "a", encoding="utf-8")
+            else:
+                file_name = os.environ.get("COVERAGE_DEBUG_FILE", FORCED_DEBUG_FILE)
+                if file_name in ("stdout", "stderr"):
+                    fileobj = getattr(sys, file_name)
+                elif file_name:
+                    fileobj = open(file_name, "a", encoding="utf-8")
                 else:
                     fileobj = sys.stderr
             the_one = cls(fileobj, show_process, filters)

doc/cmd.rst

@@ -1056,8 +1056,9 @@ Debug options can also be set with the ``COVERAGE_DEBUG`` environment variable,
 a comma-separated list of these options, or in the :ref:`config_run_debug`
 section of the .coveragerc file.
 
-The debug output goes to stderr, unless the ``COVERAGE_DEBUG_FILE`` environment
-variable names a different file, which will be appended to.  This can be useful
-because many test runners capture output, which could hide important details.
-``COVERAGE_DEBUG_FILE`` accepts the special names ``stdout`` and ``stderr`` to
-write to those destinations.
+The debug output goes to stderr, unless the :ref:`config_run_debug_file`
+setting or the ``COVERAGE_DEBUG_FILE`` environment variable names a different
+file, which will be appended to.  This can be useful because many test runners
+capture output, which could hide important details.  ``COVERAGE_DEBUG_FILE``
+accepts the special names ``stdout`` and ``stderr`` to write to those
+destinations.

doc/config.rst

@@ -203,6 +203,15 @@ include a short string at the end, the name of the warning. See
 <cmd_run_debug>` for details.
 
 
+.. _config_run_debug_file:
+
+[run] debug_file
+................
+
+(string) A file name to write debug output to.  See :ref:`the run --debug
+option <cmd_run_debug>` for details.
+
+
 .. _config_run_dynamic_context:
 
 [run] dynamic_context

tests/test_debug.py

@@ -186,17 +186,7 @@ def test_debug_config(self) -> None:
 
     def test_debug_sys(self) -> None:
         out_text = self.f1_debug_output(["sys"])
-
-        labels = """
-            coverage_version coverage_module coverage_paths stdlib_paths third_party_paths
-            tracer configs_attempted config_file configs_read data_file
-            python platform implementation executable
-            pid cwd path environment command_line cover_match pylib_match
-            """.split()
-        for label in labels:
-            label_pat = fr"^\s*{label}: "
-            msg = f"Incorrect lines for {label!r}"
-            assert 1 == len(re_lines(label_pat, out_text)), msg
+        assert_good_debug_sys(out_text)
 
     def test_debug_sys_ctracer(self) -> None:
         out_text = self.f1_debug_output(["sys"])
@@ -216,6 +206,51 @@ def test_debug_pybehave(self) -> None:
         assert vtuple[:5] == sys.version_info
 
 
+def assert_good_debug_sys(out_text: str) -> None:
+    """Assert that `str` is good output for debug=sys."""
+    labels = """
+        coverage_version coverage_module coverage_paths stdlib_paths third_party_paths
+        tracer configs_attempted config_file configs_read data_file
+        python platform implementation executable
+        pid cwd path environment command_line cover_match pylib_match
+        """.split()
+    for label in labels:
+        label_pat = fr"^\s*{label}: "
+        msg = f"Incorrect lines for {label!r}"
+        assert 1 == len(re_lines(label_pat, out_text)), msg
+
+
+# When measuring ourselves, the debug output has already been established, so
+# these tests won't work.
+@pytest.mark.skipif(env.METACOV, reason="Can't redirect debug output during metacov")
+class DebugOutputTest(CoverageTest):
+    """Tests that we can direct debug output where we want."""
+
+    def debug_sys(self) -> None:
+        """Run just enough coverage to get full debug=sys output."""
+        cov = coverage.Coverage(debug=["sys"])
+        cov.start()
+        cov.stop()
+
+    def test_stderr_default(self) -> None:
+        self.debug_sys()
+        assert_good_debug_sys(self.stderr())
+
+    def test_envvar(self) -> None:
+        self.set_environ("COVERAGE_DEBUG_FILE", "debug.out")
+        self.debug_sys()
+        assert self.stderr() == ""
+        with open("debug.out") as f:
+            assert_good_debug_sys(f.read())
+
+    def test_config_file(self) -> None:
+        self.make_file(".coveragerc", "[run]\ndebug_file = lotsa_info.txt")
+        self.debug_sys()
+        assert self.stderr() == ""
+        with open("lotsa_info.txt") as f:
+            assert_good_debug_sys(f.read())
+
+
 def f_one(*args: Any, **kwargs: Any) -> str:
     """First of the chain of functions for testing `short_stack`."""
     return f_two(*args, **kwargs)