NAME
Devel::Cover::Report::Coveralls - coveralls backend for Devel::Cover
USAGE
GitHub Actions
1. Add your repo to Coveralls. https://coveralls.io/repos/new
2. Add a workflow, e.g. .github/workflows/test.yml. The GITHUB_TOKEN of the workflow is enough to send the report; you do not need the repo token of Coveralls.
name: test
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: shogo82148/actions-setup-perl@v1
with:
perl-version: '5.42'
- run: cpanm -n --installdeps .
- run: cpanm -n Devel::Cover::Report::Coveralls
- run: cover -test -report coveralls
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3. Push the change to GitHub. Coveralls shows the build, and on a pull request it reports the coverage back to the pull request.
To send the coverage of several jobs (a matrix) as one build, mark each job as parallel, give each its own flag name, and close the build when all of them are done. The build is the run of the workflow, so the jobs and the closing step agree on it without any setting.
jobs:
test:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
perl-version: ['5.20', '5.30', '5.42']
steps:
- uses: actions/checkout@v7
- uses: shogo82148/actions-setup-perl@v1
with:
perl-version: ${{ matrix.perl-version }}
- run: cpanm -n --installdeps .
- run: cpanm -n Devel::Cover::Report::Coveralls
- run: cover -test -report coveralls
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
COVERALLS_PARALLEL: true
COVERALLS_FLAG_NAME: perl-${{ matrix.perl-version }}
finish:
needs: test
if: ${{ always() }}
runs-on: ubuntu-latest
steps:
- uses: coverallsapp/github-action@v2
with:
parallel-finished: true
Travis CI
1. Add your repo to Coveralls. https://coveralls.io/repos/new
2. In the settings of your repository on Travis CI, set the environment variable COVERALLS_REPO_TOKEN to the repo token shown on your project page in Coveralls.
3. Add the settings to .travis.yml:
language: perl
perl:
- "5.30"
before_install:
- cpanm -n Devel::Cover::Report::Coveralls
script:
- perl Build.PL && ./Build build && cover -test -report coveralls
4. Push the change. Coveralls shows the build.
Other CI services
GitLab CI, CircleCI, Jenkins, Azure Pipelines, Drone and Semaphore are detected from their environment variables, and the build number, branch, commit and pull request they give are sent.
1. Get the repo token from your project page in Coveralls.
2. Give it to the job as COVERALLS_REPO_TOKEN, as a secret variable of the CI service. Or write it in .coveralls.yml in the directory you run cover from, and do not commit that file to a public repository:
repo_token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
3. Run cover -test -report coveralls in the job.
When the report cannot be sent
cover -report coveralls prints the error and exits with a non-zero status, so the job fails. To keep the job green, e.g. on pull requests from forks, which get no secrets, set "COVERALLS_NO_FAIL".
DESCRIPTION
https://coveralls.io/ is service to publish your coverage stats online with a lot of nice features. This module provides seamless integration with Devel::Cover in your perl projects.
ENVIRONMENT
Set these environment variables to control the behaviour. Various other variables, set by particular CI environments, will be interpreted silently and correctly.
COVERALLS_REPO_TOKEN
The Coveralls authentication token for this particular repo. It is used before repo_token in .coveralls.yml. On GitHub Actions, GITHUB_TOKEN is used when neither is set.
COVERALLS_ENDPOINT
If you have an enterprise installation, set this to change from the default of https://coveralls.io. The rest of the URL (/api, etc) won't change, and will be correct.
COVERALLS_FLAG_NAME
Describe the particular tests being done, e.g. Unit or Functional. On GitHub Actions it is also added to the job ID, so give each leg of a matrix that reports to the same parallel build its own flag name.
COVERALLS_PARALLEL
Set this to true when several jobs send their coverage to one build. Any value other than empty, false and 0 turns it on. Coveralls then keeps the build open until the parallel build webhook is called, so call it when all the jobs are done. The jobs must send the same build number; the CI services above give one per run (on GitHub Actions, the run of the workflow).
See https://docs.coveralls.io/api-parallel-build-webhook
COVERALLS_NO_FAIL
When the report cannot be sent to Coveralls (the upload fails, or there is no repo token), cover -report coveralls prints the error and exits with a non-zero status, so that the CI job fails. Set this to true to exit 0 instead, e.g. when coverage is optional for the build or pull requests from forks get no repo token. When cover makes several reports, the ones after coveralls are not made after a failure, so put coveralls last. Any value other than empty, false and 0 turns it on.
COVERALLS_PERL_SERVICE_NAME
Sends this as the name of the CI service, in place of the one detected (e.g. github).
SEE ALSO
https://coveralls.io/ https://docs.coveralls.io/ https://github.com/coagulant/coveralls-python Devel::Cover
EXAMPLE
https://coveralls.io/github/kan/coveralls-perl
LICENSE
Copyright (C) Kan Fushihara
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
AUTHOR
Kan Fushihara <kan.fushihara@gmail.com>