cov

README

Cov

Cov is a simple code coverage checker for Golang. It's like codacy or codecov (at least regarding features that people usually want), but not SaaS, in a few lines of code.

It has no reports other than a tree view showing which package is up to standard and which are not, the coverage and the required threshold. The idea is to block merging and let people fix locally the coverage with any tool they like.

It will report as a status check the status of the run.

Github action

This repository contains a Github action that can be used directly with your Github workflow. You need to make sure one of your steps generates a coverage file (usually using go test -coverprofile=coverage.out) then add a new step:

    name: build-go
    on:
      push:
        branches:
        - master
      pull_request:
    jobs:
      build:
        steps:
        - uses: actions/checkout@v3
        - uses: actions/setup-go@v3
        - name: test
          run: go test -coverprofile=coverage.out ./...
        - uses: PaloAltoNetworks/cov@3.0.0
          with:
            cov_mode: coverage

If you want to publish a status check on the commit, you need a second workflow file that has the permission to send a status check on the target repository:

name: cov
on:
  workflow_run:
    workflows: ["build-go"]
    types: ["completed"]
jobs:
  cov:
    steps:
      - uses: PaloAltoNetworks/cov@3.0.0
        with:
          cov_mode: send-status
          workflow_run_id: ${{github.event.workflow_run.id}}
          workflow_head_sha: ${{github.event.workflow_run.head_sha}}

NOTE: You want two files to prevent eventual staling of secrets. The first one is triggered on pull_request, which will make the workflow run in the context of the pull request head, and will run in the context of the fork originating the pull request. The second is triggered on workflow_run, which will this time run in the context of the pull request target, and will have the permission to send a status check.

Parameters

There are several parameters you can tweak:

Operation mode

Cov works in a 2 step process. First it will check the coverage then generate a cov report, that then can be used to send a status check on the commit triggering the job (default: coverage).

• cov_mode: coverage: check the coverage and generate cov.report, and uploads it as workflow artifact.
• cov_mode: send-status: get the cov.report previously generated, and send a status check on the corresponding commit.
• cov_mode: both: Lagacy behavior (not recommended)

uses: PaloAltoNetworks/cov@3.0.0
with:
  cov_mode: coverage

In send-status mode, you must pass workflow_run_id so the job knows where to get the cov.report artifact from, and workflow_head_sha to know on which commit SHA it should send the status.

uses: PaloAltoNetworks/cov@3.0.0
with:
  cov_mode: send-status
  workflow_run_id: ${{github.event.workflow_run.id}}
  workflow_head_sha: ${{github.event.workflow_run.head_sha}}

Repository main branch

The tool needs to know which branch is your main one in order to be able to run coverage on the pull requests patch. (default: main).

uses: PaloAltoNetworks/cov@3.0.0
with:
  main_branch: master

Coverage file

The tool needs to know where your coverage file has been generated. The path is relative to your repository root (default: coverage.go).

uses: PaloAltoNetworks/cov@3.0.0
with:
  cov_file: unit_coverage.out

Coverage threshold

You can configure what is the minimum coverage target a patch must have in order to be considered up to standard. Note that you must give the percentage as a string. (default: 70)

uses: PaloAltoNetworks/cov@3.0.0
with:
  cov_threshold: "80"

Cov version

This is a debugging flag that allows to force the action to use a different version of the cov tool. You should not need to touch this. (default: ${{github.action_ref}})

uses: PaloAltoNetworks/cov@3.0.0
with:
  cov_version: master

Ignore some files

If you have some code you would like cov to ignore (for instance, autogenerated or example code), you can create a file named .covignore at the root of your repository. The syntax uses classic glob syntax.

Note that cov uses the full go package name. So you need to either write the full package, or use a **/prefix.

github.com/me/mypackage/ignored/*
**/pkgs/api/*
**/example/*
**/something/**/something

Local installation

You can install cov locally:

go install github.com/PaloAltoNetworks/cov@latest

Or you can grab a release from the releases page.

Usage

Analyzes coverage

Usage:
  cov cover.out... [flags]

Flags:
  -b, --branch string             The branch to use to check the patch coverage against. Example: master
  -f, --filter strings            The filters to use for coverage lookup
  -h, --help                      help for cov
      --host-url string           The host URL of the provider. (default "https://api.github.com")
  -i, --ignore strings            Define patterns to ignore matching files.
      --pipeline-id string        If set, defines the ID of the pipeline to set the status.
  -p, --provider string           The provider to use for status checks: github, gitlab (default "github")
  -q, --quiet                     Do not print details, just the verdict
      --report-path string        Defines the path for the status report. (default "cov.report")
      --send-repo string          If set, set the status report from --report-path as status check. format: [repo]/[owner]@[sha]
      --send-token string         If set, use this token to send the status. If empty, $GITHUB_TOKEN or $GITLAB_TOKEN will be used based on provider
      --target-url string         If set, associate the target URL with the status.
  -t, --threshold int             The target of coverage in percent that is requested
  -e, --threshold-exit-code int   Set the exit code on coverage threshold miss (default 1)
      --version                   show version
      --write-report              If set, write a status check report into --report-path

When the --branch flag is used, a diff will be done between your current branch and the given branch to identify the files you changed, and only look for the coverage of that diff.

You can pass several coverage files, they all will be merged.

You can filter for a given package or any substring.

When the --threshold flag is set, cov will check if the coverage is greater or equal to that value. It will exit with the code passed as --threshold-exit-code.

You can ignore files matching some patterns using the --ignore option. If you use this parameter, the .covignore file will be ignored.

Examples

Show coverage for all coverage files:

cov *.out

Show coverage for a pull request against master:

cov --branch master coverage.out

Ignore all files in autogen/api and examples:

cov --ignore "**/autogen/api/*" --ignore "**/examples/*" coverage.out

Check for a minimum coverage, but don't exit with code 1:

cov --threshold 80 --threshold-exit-code 0 coverage.out