Coveralls Python

Common errors

• No coverage data found.

  cause The `coverage.py` tool was not run, or it did not generate a `.coverage` file in the expected location, or the file was empty.
  fix Ensure `coverage run --source=your_module_name ...` is executed before `coveralls`. Verify a `.coverage` file exists and contains data.

• Not authenticated. Have you provided a repo_token?

  cause The `COVERALLS_REPO_TOKEN` environment variable was not set, or the `.coveralls.yml` file was missing/incorrect.
  fix Set the `COVERALLS_REPO_TOKEN` environment variable in your CI configuration or shell, or create a valid `.coveralls.yml` file in your project root with the token.

• KeyError: 'branch'

  cause This often happens when Coveralls cannot automatically detect CI environment variables (e.g., `TRAVIS`, `GITHUB_ACTIONS`) and crucial git information like 'branch' is missing.
  fix Ensure CI environment variables are correctly propagated, or manually provide git details via `.coveralls.yml` or specific environment variables like `COVERALLS_BRANCH`, `COVERALLS_COMMIT`.

Warnings

• gotcha python-coveralls relies on `coverage.py` to generate the `.coverage` data file. If this file is missing, empty, or not found in the expected location, `coveralls` will report 'No coverage data found'.
  Fix: Always run your tests with `coverage run` (e.g., `coverage run --source=your_package -m pytest`) before invoking `coveralls`. Verify a `.coverage` file is created and contains data.
• gotcha A `COVERALLS_REPO_TOKEN` environment variable or a `.coveralls.yml` file with a `repo_token` is required for authentication with Coveralls.io. Without it, the report will fail to upload.
  Fix: Set `COVERALLS_REPO_TOKEN` in your CI environment or locally (e.g., `export COVERALLS_REPO_TOKEN=YOUR_TOKEN`). For CI services, sometimes `CI` environment variables are sufficient, but providing the token is the most robust approach.
• breaking Python 2 support was dropped in version 2.0.0. Projects using Python 2 must use `python-coveralls<2.0.0`.
  Fix: Upgrade your project to Python 3 or pin `python-coveralls` to a version less than 2.0.0 (e.g., `pip install python-coveralls==1.11.0`).
• gotcha The `coveralls` command can fail to detect repository details (like branch name) if executed outside of a recognized CI environment or a Git repository, leading to `KeyError` or incomplete reports.
  Fix: Ensure the command runs in a Git repository context, or explicitly provide git details via environment variables (e.g., `COVERALLS_BRANCH`) or a `.coveralls.yml` configuration file.

Install

• pip install python-coveralls Install library

Imports

• Coveralls

  from coveralls import Coveralls

  While a `Coveralls` class exists, direct import and use in user application code is uncommon. The library is primarily used via its command-line interface (`coveralls`).

Quickstart

This quickstart demonstrates the typical workflow: first, generate coverage data using `coverage.py` after running your tests, and then use the `coveralls` command-line tool to send the `.coverage` report to Coveralls.io. Ensure the `COVERALLS_REPO_TOKEN` is set, especially in CI environments.

# 1. Install necessary packages
pip install coverage python-coveralls

# 2. Run your tests with coverage.py to generate .coverage data
#    Replace 'pytest' with your actual test runner (e.g., 'python -m unittest discover')
#    Replace 'your_module_name' with the actual name of your package/module to cover
coverage run --source=your_module_name -m pytest

# 3. Send the coverage report to Coveralls.io
#    Set your repository token as an environment variable.
#    In CI environments (e.g., GitHub Actions, Travis CI), this is often handled automatically
#    or provided securely. For local testing, ensure it's exported in your shell.
#    Using a placeholder; replace with your actual token.
export COVERALLS_REPO_TOKEN='YOUR_ACTUAL_COVERALLS_REPO_TOKEN'

#    Now run the coveralls command-line tool
coveralls