Coverage Threshold

Common errors

• No .coverage file found at ...

  cause The `coverage.py` tool was not run, or the `.coverage` data file is not in the expected directory (usually the current working directory).
  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.

• ERROR: No section 'tool.coverage-threshold' found in pyproject.toml

  cause The `pyproject.toml` configuration file either does not exist, or it is missing the mandatory `[tool.coverage-threshold]` section.
  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] line = 90 branch = 80`).

• ModuleNotFoundError: No module named 'coverage_threshold'

  cause The `coverage-threshold` library has not been installed in your current Python environment.
  fix Install the package using pip: `pip install coverage-threshold`.

Warnings

• gotcha 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.
  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`.
• gotcha 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.
  Fix: Ensure your `coverage.py` installation is version `5.0.0` or higher. Upgrade with `pip install --upgrade coverage`.
• gotcha Incorrectly formatted or missing configuration in `pyproject.toml` or `.coverage.rc` can lead to errors or unexpected threshold checks.
  Fix: Refer to the official documentation for the correct `[tool.coverage-threshold]` section in `pyproject.toml` or the specific keys if using `.coverage.rc`.

Install

• pip install coverage-threshold Install stable version

Imports

• check_all_thresholds

  from coverage_threshold.lib import check_all_thresholds

• Config

  from coverage_threshold.model import Config

• CoverageReport

  from coverage_threshold.model import CoverageReport

Quickstart

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.

from coverage_threshold.lib import check_all_thresholds
from coverage_threshold.model import Config, CoverageReport

# Simulate a coverage report object
# In a real scenario, this data would be parsed from a .coverage file
mock_report = CoverageReport(
    line_coverage=95.0,
    branch_coverage=85.0,
    file_line_coverage={
        "app.py": 95.0,
        "another_module.py": 90.0
    },
    file_branch_coverage={
        "app.py": 85.0,
        "another_module.py": 80.0
    }
)

# Define the desired thresholds (mimicking pyproject.toml configuration)
config = Config(
    line_threshold=90.0,
    branch_threshold=80.0,
    exclude=[] # No file exclusions for this example
)

print(f"Checking report: Global Line={mock_report.line_coverage:.1f}%, Global Branch={mock_report.branch_coverage:.1f}%")
print(f"Against thresholds: Line={config.line_threshold:.1f}%, Branch={config.branch_threshold:.1f}%")

try:
    # This function will raise an exception if thresholds are not met
    check_all_thresholds(config, mock_report)
    print("\nSUCCESS: All coverage thresholds met!")
except Exception as e:
    print(f"\nFAILURE: Coverage thresholds not met: {e}")

print("\n--- Testing a failure scenario ---")
failing_report = CoverageReport(
    line_coverage=80.0, # This is below the 90% threshold
    branch_coverage=85.0,
    file_line_coverage={
        "app.py": 80.0,
        "another_module.py": 90.0
    },
    file_branch_coverage={
        "app.py": 85.0,
        "another_module.py": 80.0
    }
)

print(f"Checking failing report: Global Line={failing_report.line_coverage:.1f}%, Global Branch={failing_report.branch_coverage:.1f}%")
print(f"Against thresholds: Line={config.line_threshold:.1f}%, Branch={config.branch_threshold:.1f}%")

try:
    check_all_thresholds(config, failing_report)
    print("\nSUCCESS: All coverage thresholds met!")
except Exception as e:
    print(f"\nFAILURE: Coverage thresholds not met: {e}")