{"id":9625,"library":"coverage-threshold","title":"Coverage Threshold","description":"coverage-threshold is a Python library that provides command-line and programmatic tools to enforce coverage percentage limits (lines, branches) based on data generated by the `coverage.py` library. It's currently at version 0.6.2 and has a moderate release cadence, focusing on stability and integration with CI/CD pipelines.","status":"active","version":"0.6.2","language":"en","source_language":"en","source_url":"https://github.com/DeanWay/coverage-threshold","tags":["coverage","testing","ci","quality-assurance","code-quality"],"install":[{"cmd":"pip install coverage-threshold","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Requires coverage.py to generate and parse coverage data files.","package":"coverage","version":">=5.0.0","optional":false}],"imports":[{"symbol":"check_all_thresholds","correct":"from coverage_threshold.lib import check_all_thresholds"},{"symbol":"Config","correct":"from coverage_threshold.model import Config"},{"symbol":"CoverageReport","correct":"from coverage_threshold.model import CoverageReport"}],"quickstart":{"code":"from coverage_threshold.lib import check_all_thresholds\nfrom coverage_threshold.model import Config, CoverageReport\n\n# Simulate a coverage report object\n# In a real scenario, this data would be parsed from a .coverage file\nmock_report = CoverageReport(\n    line_coverage=95.0,\n    branch_coverage=85.0,\n    file_line_coverage={\n        \"app.py\": 95.0,\n        \"another_module.py\": 90.0\n    },\n    file_branch_coverage={\n        \"app.py\": 85.0,\n        \"another_module.py\": 80.0\n    }\n)\n\n# Define the desired thresholds (mimicking pyproject.toml configuration)\nconfig = Config(\n    line_threshold=90.0,\n    branch_threshold=80.0,\n    exclude=[] # No file exclusions for this example\n)\n\nprint(f\"Checking report: Global Line={mock_report.line_coverage:.1f}%, Global Branch={mock_report.branch_coverage:.1f}%\")\nprint(f\"Against thresholds: Line={config.line_threshold:.1f}%, Branch={config.branch_threshold:.1f}%\")\n\ntry:\n    # This function will raise an exception if thresholds are not met\n    check_all_thresholds(config, mock_report)\n    print(\"\\nSUCCESS: All coverage thresholds met!\")\nexcept Exception as e:\n    print(f\"\\nFAILURE: Coverage thresholds not met: {e}\")\n\nprint(\"\\n--- Testing a failure scenario ---\")\nfailing_report = CoverageReport(\n    line_coverage=80.0, # This is below the 90% threshold\n    branch_coverage=85.0,\n    file_line_coverage={\n        \"app.py\": 80.0,\n        \"another_module.py\": 90.0\n    },\n    file_branch_coverage={\n        \"app.py\": 85.0,\n        \"another_module.py\": 80.0\n    }\n)\n\nprint(f\"Checking failing report: Global Line={failing_report.line_coverage:.1f}%, Global Branch={failing_report.branch_coverage:.1f}%\")\nprint(f\"Against thresholds: Line={config.line_threshold:.1f}%, Branch={config.branch_threshold:.1f}%\")\n\ntry:\n    check_all_thresholds(config, failing_report)\n    print(\"\\nSUCCESS: All coverage thresholds met!\")\nexcept Exception as e:\n    print(f\"\\nFAILURE: Coverage thresholds not met: {e}\")","lang":"python","description":"This quickstart demonstrates how to use `coverage-threshold` programmatically with mock coverage data. In a real application, the `CoverageReport` object would be generated by parsing an actual `.coverage` file after `coverage.py` has run. The `check_all_thresholds` function raises an exception if any thresholds are not met."},"warnings":[{"fix":"Always ensure you run `coverage run` (or a similar command via your test runner) to generate the `.coverage` data file before invoking `coverage-threshold`.","message":"The `coverage-threshold` tool does not run coverage itself; it requires a `.coverage` data file to already exist. Running `coverage-threshold` directly without prior coverage generation will fail.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your `coverage.py` installation is version `5.0.0` or higher. Upgrade with `pip install --upgrade coverage`.","message":"Using an incompatible `coverage.py` version (older than 5.0.0) can lead to errors when `coverage-threshold` attempts to parse the `.coverage` data file.","severity":"gotcha","affected_versions":"All (especially with `coverage.py < 5.0.0`)"},{"fix":"Refer to the official documentation for the correct `[tool.coverage-threshold]` section in `pyproject.toml` or the specific keys if using `.coverage.rc`.","message":"Incorrectly formatted or missing configuration in `pyproject.toml` or `.coverage.rc` can lead to errors or unexpected threshold checks.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"First, run your tests with `coverage run` (e.g., `coverage run -m pytest`) to generate the `.coverage` file in your project's root directory.","cause":"The `coverage.py` tool was not run, or the `.coverage` data file is not in the expected directory (usually the current working directory).","error":"No .coverage file found at ..."},{"fix":"Create or update your `pyproject.toml` to include a `[tool.coverage-threshold]` section, specifying your desired `line` and `branch` thresholds (e.g., `[tool.coverage-threshold]\nline = 90\nbranch = 80`).","cause":"The `pyproject.toml` configuration file either does not exist, or it is missing the mandatory `[tool.coverage-threshold]` section.","error":"ERROR: No section 'tool.coverage-threshold' found in pyproject.toml"},{"fix":"Install the package using pip: `pip install coverage-threshold`.","cause":"The `coverage-threshold` library has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'coverage_threshold'"}]}