Coveralls Python

Warnings

• breaking In version 4.0.0, the behavior of `config.ignore_errors` changed. When `config.ignore_errors` is Falsey, failures to parse Python files or look up file sources will now interrupt and early exit collection, matching default `coverage.py` behavior. Previously, these errors were manually muted or only reported after collecting multiple failures.
  Fix: Review your `coverage.py` configuration (e.g., `.coveragerc`) for the `ignore_errors` setting and adjust if you relied on the previous error-muting behavior.
• breaking In version 3.0.0, the configuration precedence was reversed. The new order (latest value used) is: CI Config, `COVERALLS_*` env vars, `.coveralls.yml` file, CLI flags. If you have the same fields set in multiple locations, verify your configuration after upgrading.
  Fix: Review all your configuration sources (CI settings, environment variables, `.coveralls.yml`, CLI flags) and ensure they produce the desired outcome under the new precedence rules.
• gotcha For Python 3.13+ and `coverage.py` v7+, the official Coveralls documentation recommends switching to their GitHub Action, CircleCI Orb, or Universal Coverage Reporter CLI tool, as direct `coveralls-python` integration may have lapsed support for the latest `coverage.py` formats.
  Fix: Consider migrating to an officially maintained Coveralls integration (e.g., GitHub Action) if you encounter issues with newer Python or `coverage.py` versions. Generate Cobertura XML reports with `coverage xml` and submit them via the official tools.
• gotcha The `coveralls` package depends on `coverage.py`. There have been known incompatibilities with specific `coverage.py` versions (e.g., v6.0.0-v6.1.1 were excluded in `coveralls` v3.3.1). Ensure you are using compatible versions of both libraries. `coveralls` v4.0.1 specifically added support for `coverage` v7.5+.
  Fix: Always install the latest `coveralls` version. If encountering issues, consult the `coveralls-python` and `coverage.py` release notes for compatibility details and ensure your `coverage.py` version is supported.
• gotcha The `COVERALLS_REPO_TOKEN` environment variable (or `repo_token` in `.coveralls.yml`) is crucial for submitting coverage data outside of officially supported CI environments like TravisCI or GitHub Actions. Without it, submissions will fail.
  Fix: Obtain your repository token from Coveralls.io and set it as an environment variable `COVERALLS_REPO_TOKEN` before running the `coveralls` command. Alternatively, configure it in a `.coveralls.yml` file (requires `coveralls[yaml]`).
• gotcha To avoid 'not a git repository' errors, particularly in CI environments, ensure `relative_files = True` is configured in your `coverage.py` configuration (e.g., in the `[run]` section of `.coveragerc`, `setup.cfg`, `tox.ini`, or `[tool.coverage.run]` in `pyproject.toml`).
  Fix: Add `relative_files = True` to your `coverage.py` configuration file. For `pyproject.toml`, ensure `coverage[toml]` is installed.
• deprecated Python 3.8 and 3.9 support was dropped in `coveralls` v4.0.2. Earlier versions dropped support for Python 3.7 and below, and Python 2.7/3.4.
  Fix: Upgrade to a supported Python version (>=3.10) for `coveralls` 4.x. If you must use older Python versions, pin `coveralls` to a compatible older version.

Install

• pip install coveralls Basic installation
• pip install coveralls[yaml] For .coveralls.yml configuration

Quickstart

After installing `coveralls` and collecting coverage data with `coverage.py` (e.g., by running `coverage run -m pytest`), you can submit the results to Coveralls.io. For non-CI environments or unsupported CI systems, ensure the `COVERALLS_REPO_TOKEN` environment variable is set.

import os

# Simulate running tests with coverage.py
# In a real scenario, you'd run your tests like:
# coverage run -m pytest
# For this example, we assume coverage.py has already generated .coverage data.

# Set the Coveralls repository token (replace with your actual token or use env var)
# This is often handled automatically in supported CI environments.
# For local testing or unsupported CIs, ensure COVERALLS_REPO_TOKEN is set.
# You can find this token on your project's dashboard in coveralls.io.
os.environ['COVERALLS_REPO_TOKEN'] = os.environ.get('COVERALLS_REPO_TOKEN', 'your_coveralls_repo_token_here')

# Run the coveralls command-line tool
import subprocess
try:
    # Typically, you'd run 'coverage run -m pytest' first, then 'coveralls'
    # For this example, we simulate the submission step after coverage data is assumed to exist.
    print("Attempting to submit coverage to Coveralls.io...")
    # The actual command would be: subprocess.run(["coveralls"], check=True)
    # We'll mock the output for a runnable example without actual submission.
    mock_output = "Submitting coverage to coveralls.io...\nCoverage submitted! Job #123.456 https://coveralls.io/jobs/1234567890"
    print(mock_output)
    # For an actual run:
    # result = subprocess.run(["coveralls"], capture_output=True, text=True, check=True)
    # print(result.stdout)
    # print(result.stderr)
except subprocess.CalledProcessError as e:
    print(f"Error submitting coverage: {e.stderr}")
except FileNotFoundError:
    print("Error: 'coveralls' command not found. Ensure coveralls is installed and in your PATH.")