coverage-conditional-plugin

Conditional coverage based on any rules you define!

Some projects have different parts that relies on different environments:

Python version, some code is only executed on specific versions and ignored on others
OS version, some code might be Windows, Mac, or Linux only
External packages, some code is only executed when some 3rd party package is installed

Current best practice is to use # pragma: no cover for this places in our project. This project allows to use configurable pragmas that include code to the coverage if some condition evaluates to true, and fallback to ignoring this code when condition is false.

Read the announcing post.

Installation

pip install coverage-conditional-plugin

Then you will need to add to your setup.cfg or .coveragerc file some extra configuration:

[coverage:run]
# Here we specify plugins for coverage to be used:
plugins =
  coverage_conditional_plugin

[coverage:coverage_conditional_plugin]
# Here we specify files to conditionally omit:
omit =
  "sys_platform == 'win32'":
      "my_project/omit*.py"
      "my_project/win.py"
# Here we specify our pragma rules:
rules =
  "sys_version_info >= (3, 8)": py-gte-38
  "is_installed('mypy')": has-mypy

Or to your pyproject.toml:

[tool.coverage.run]
# Here we specify plugins for coverage to be used:
plugins = ["coverage_conditional_plugin"]

[tool.coverage.coverage_conditional_plugin.omit]
# Here we specify files to conditionally omit:
"my_project/omit*.py" = "sys_platform == 'win32'"

[tool.coverage.coverage_conditional_plugin.rules]
# Here we specify our pragma rules:
py-gte-38 = "sys_version_info >= (3, 8)"
has-mypy = "is_installed('mypy')"

Adapt rules to suit your needs!

Example

Imagine that we have this code:

try:  # pragma: has-django
    import django
except ImportError:  # pragma: has-no-django
    django = None

def run_if_django_is_installed():
    if django is not None:  # pragma: has-django
        ...

And here's the configuration you might use:

[coverage:coverage_conditional_plugin]
rules =
  "is_installed('django')": has-django
  "not is_installed('django')": has-no-django

When running tests with and without django installed you will have 100% coverage in both cases.

But, different lines will be included. With django installed it will include both try: and if django is not None: conditions.

When running without django installed, it will include except ImportError: line.

Writing pragma rules

Format for pragma rules is:

"pragma-condition": pragma-name

Code inside "pragma-condition" is evaluted with eval. Make sure that the input you pass there is trusted! "pragma-condition" must return bool value after evaluation.

We support all environment markers specified in PEP-496. See Strings and Version Numbers sections for available values. Also, we provide a bunch of additional markers:

sys_version_info is the same as sys.version_info
os_environ is the same as os.environ
is_installed is our custom function that tries to import the passed string, returns bool value
package_version is our custom function that tries to get package version from pkg_resources and returns its parsed version

Use get_env_info to get values for the current environment:

from coverage_conditional_plugin import get_env_info

get_env_info()

Writing omits

Omits allow entire files to be conditionally omitted from coverage measurement.

The TOML format for omits is:

[tool.coverage.coverage_conditional_plugin.omit]
"pragma-condition" = ["project/prefix*.py", "project/filename.py"]
# or
"pragma-condition" = "project/filename.py"

Note: ini format is not supported for omit configuration option, because there's no easy way to parse ini complex configuration. PRs with the fix are welcome!

File name patterns should follow coverage.py's [run] omit syntax. See coverage.py.

License