{"id":5887,"library":"covdefaults","title":"covdefaults","description":"covdefaults is a coverage.py plugin that provides sensible, opinionated default settings to streamline test coverage configuration. It automatically sets defaults for aspects like branch coverage, source directory, common file omission patterns, and reporting options (e.g., `show_missing=True`, `fail_under=100`). The current version is 2.3.0, released on March 5, 2023, and it maintains an active release cadence.","status":"active","version":"2.3.0","language":"en","source_language":"en","source_url":"https://github.com/asottile/covdefaults","tags":["coverage","plugin","testing","defaults"],"install":[{"cmd":"pip install covdefaults","lang":"bash","label":"Install covdefaults"}],"dependencies":[{"reason":"covdefaults is a plugin for coverage.py and requires it to function.","package":"coverage","optional":false}],"imports":[{"note":"covdefaults is enabled by adding its name to the `plugins` list under the `[run]` section of your coverage configuration.","symbol":"covdefaults","correct":"This library is a coverage.py plugin and is configured via coverage's configuration files (e.g., pyproject.toml, .coveragerc), not directly imported into Python code."}],"quickstart":{"code":"pyproject.toml\n\n[tool.poetry]\nname = \"my-project\"\nversion = \"0.1.0\"\ndescription = \"\"\nauthors = [\"Your Name <you@example.com>\"]\nreadme = \"README.md\"\n\n[tool.poetry.dependencies]\npython = \">=3.7,<4.0\"\ncoverage = {extras = [\"toml\"], version = \">=6.0.2\"}\n\n[tool.poetry.group.dev.dependencies]\npip = \"*\"\npytest = \"*\"\ncovdefaults = \"*\"\n\n[tool.coverage.run]\nplugins = [\"covdefaults\"]\n\n# Optional: Customize or override specific defaults\n# source = [\".\"]\n# omit = [\".venv/*\"]\n\n# Optional: Customize reporting\n# [tool.coverage.report]\n# fail_under = 90","lang":"toml","description":"To enable covdefaults, add it to the `plugins` list in your `pyproject.toml` (or `.coveragerc`, `setup.cfg`, `tox.ini`). This example assumes a Poetry project with pytest and coverage installed. covdefaults will then apply its default settings for coverage measurement and reporting. You can override specific defaults by explicitly setting them in your coverage configuration."},"warnings":[{"fix":"Always consult the `covdefaults` documentation or source for the exact behavior of specific settings when overriding. Test your coverage configuration thoroughly to ensure the desired defaults are applied or overridden correctly.","message":"Overriding default options in coverage.py configuration files (e.g., `pyproject.toml`, `.coveragerc`) behaves differently for various settings. Some options, like `run:source` and `report:fail_under`, will entirely prevent `covdefaults` from applying its default if you set them manually. Other options, like `run:omit` and `report:exclude_lines`, will extend the defaults provided by `covdefaults` rather than overwriting them.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Use `[covdefaults] subtract_omit` only when you explicitly want to un-omit a file that `covdefaults` would normally omit. To add new patterns to the `omit` list, use the standard `[run] omit` option in your coverage configuration.","message":"The `[covdefaults] subtract_omit` option, when used in your configuration, removes specific patterns from `covdefaults`'s default `omit` list. Users sometimes mistakenly believe it adds to the `omit` list, leading to files being included in coverage that they intended to exclude.","severity":"gotcha","affected_versions":"All versions"},{"fix":"For consistent coverage behavior, prefer to define your `coverage.py` configuration (including `covdefaults` activation and overrides) in a configuration file (like `pyproject.toml`) rather than relying heavily on `pytest-cov` command-line arguments that duplicate configuration file settings. This ensures a single source of truth for your coverage setup.","message":"When using `pytest-cov`, its command-line options (e.g., `--cov=something`, `--cov-branch`) can override the `source` and `branch` settings provided by `coverage.py` or `covdefaults`. This can lead to unexpected coverage behavior if not managed carefully.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Consolidate your coverage configuration into a single file, preferably `pyproject.toml`, to avoid ambiguity. If using multiple files is unavoidable, be mindful of the precedence order and clearly document where your primary coverage settings reside.","message":"Coverage.py, and by extension `covdefaults`, respects a specific order of precedence for configuration files: `.coveragerc`, `.coveragerc.toml`, `setup.cfg`, `tox.ini`, and `pyproject.toml`. If multiple files are present, only the first one found that contains `coverage.py` settings will be used. This can cause confusion if you expect settings from one file to be merged or to override settings in another.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}