Skip to content

Commit

Permalink
docs: explain how to use --debug=trace
Browse files Browse the repository at this point in the history
  • Loading branch information
nedbat committed Jan 22, 2023
1 parent 82c2638 commit c51ac46
Show file tree
Hide file tree
Showing 3 changed files with 20 additions and 3 deletions.
3 changes: 2 additions & 1 deletion doc/cmd.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
16 changes: 16 additions & 0 deletions doc/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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 <cmd_run_debug>`, also settable as ``[run] debug=trace`` in the
:ref:`settings file <config_run_debug>`, 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?
.................................................

Expand Down
4 changes: 2 additions & 2 deletions doc/trouble.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit c51ac46

Please sign in to comment.