Configuration

This plugin provides a clean minimal set of command line options that are added to pytest. For further control of coverage use a coverage config file.

For example if tests are contained within the directory tree being measured the tests may be excluded if desired by using a .coveragerc file with the omit option set:

pytest --cov-config=.coveragerc
       --cov=myproj
       myproj/tests/

Where the .coveragerc file contains file globs:

[run]
omit = tests/*

For full details refer to the coverage config file documentation.

Note

Important Note

This plugin overrides the parallel option of coverage. Unless you also run coverage without pytest-cov it’s pointless to set those options in your .coveragerc.

If you use the --cov=something option (with a value) then coverage’s source option will also get overridden. If you have multiple sources it might be easier to set those in .coveragerc and always use --cov (without a value) instead of having a long command line with --cov=pkg1 --cov=pkg2 --cov=pkg3 ....

If you use the --cov-branch option then coverage’s branch option will also get overridden.

If you wish to always add pytest-cov with pytest, you can use addopts under the pytest or tool:pytest section of your setup.cfg, or the tool.pytest.ini_options section of your pyproject.toml file.

For example, in setup.cfg:

[tool:pytest]
addopts = --cov=<project-name> --cov-report html

Or for pyproject.toml:

[tool.pytest.ini_options]
addopts = "--cov=<project-name> --cov-report html"

Caveats

A unfortunate consequence of coverage.py’s history is that .coveragerc is a magic name: it’s the default file but it also means “try to also lookup coverage configuration in tox.ini or setup.cfg”.

In practical terms this means that if you have multiple configuration files around (tox.ini, pyproject.toml or setup.cfg) you might need to use --cov-config to make coverage use the correct configuration file.

Also, if you change the working directory and also use subprocesses in a test you might also need to use --cov-config to make pytest-cov will use the expected configuration file in the subprocess.

Reference

The complete list of command line options is:

--cov=PATH

Measure coverage for filesystem path. (multi-allowed)

--cov-report=type

Type of report to generate: term, term-missing, annotate, html, xml, json, lcov (multi-allowed). term, term- missing may be followed by “:skip-covered”. annotate, html, xml, json and lcov may be followed by “:DEST” where DEST specifies the output location. Use –cov-report= to not generate any output.

--cov-config=path

Config file for coverage. Default: .coveragerc

--no-cov-on-fail

Do not report coverage if test run fails. Default: False

--no-cov

Disable coverage report completely (useful for debuggers). Default: False

--cov-reset

Reset cov sources accumulated in options so far. Mostly useful for scripts and configuration files.

--cov-fail-under=MIN

Fail if the total coverage is less than MIN.

--cov-append

Do not delete coverage but append to current. Default: False

--cov-branch

Enable branch coverage.

--cov-context

Choose the method for setting the dynamic context.