diff options
| author | Ned Batchelder <ned@nedbatchelder.com> | 2023-01-22 07:29:47 -0500 |
|---|---|---|
| committer | Ned Batchelder <ned@nedbatchelder.com> | 2023-01-22 07:29:47 -0500 |
| commit | c51ac463f07e31c87b20f50bd7e6445e4e4e83a2 (patch) | |
| tree | f873435d58754c74c00864bc5ed5c87c8a021e74 | |
| parent | 82c263814e57e1d790cbe1c00bd1c724b9ca8e3c (diff) | |
| download | python-coveragepy-git-c51ac463f07e31c87b20f50bd7e6445e4e4e83a2.tar.gz | |
docs: explain how to use ``--debug=trace``
| -rw-r--r-- | doc/cmd.rst | 3 | ||||
| -rw-r--r-- | doc/faq.rst | 16 | ||||
| -rw-r--r-- | doc/trouble.rst | 4 |
3 files changed, 20 insertions, 3 deletions
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 <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? ................................................. 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 |