From c51ac463f07e31c87b20f50bd7e6445e4e4e83a2 Mon Sep 17 00:00:00 2001 From: Ned Batchelder Date: Sun, 22 Jan 2023 07:29:47 -0500 Subject: docs: explain how to use ``--debug=trace`` --- doc/cmd.rst | 3 ++- doc/faq.rst | 16 ++++++++++++++++ doc/trouble.rst | 4 ++-- 3 files changed, 20 insertions(+), 3 deletions(-) (limited to 'doc') diff --git a/doc/cmd.rst b/doc/cmd.rst index c1f52ee7..b86650a0 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -1057,6 +1057,7 @@ 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. +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. diff --git a/doc/faq.rst b/doc/faq.rst index 849f132c..8252eeb9 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -11,6 +11,22 @@ FAQ and other help Frequently asked questions -------------------------- +Q: Why are some of my files not measured? +......................................... + +Coverage.py has a number of mechanisms for deciding which files to measure and +which to skip. If your files aren't being measured, use the ``--debug=trace`` +:ref:`option `, also settable as ``[run] debug=trace`` in the +:ref:`settings file `, or as ``COVERAGE_DEBUG=trace`` in an +environment variable. + +This will write a line for each file considered, indicating whether it is +traced or not, and if not, why not. Be careful though: the output might be +swallowed by your test runner. If so, a ``COVERAGE_DEBUG_FILE=/tmp/cov.out`` +environemnt variable can direct the output to a file insttead to ensure you see +everything. + + Q: Why do unexecutable lines show up as executed? ................................................. diff --git a/doc/trouble.rst b/doc/trouble.rst index 9c371df1..8776e6f8 100644 --- a/doc/trouble.rst +++ b/doc/trouble.rst @@ -25,8 +25,8 @@ bug tracker`_ directly to see if there is some mention of it. Things that don't work ---------------------- -There are a number of popular modules, packages, and libraries that prevent -coverage.py from working properly: +There are a few modules or functions that prevent coverage.py from working +properly: * `execv`_, or one of its variants. These end the current program and replace it with a new one. This doesn't save the collected coverage data, so your -- cgit v1.2.1