CodeScene Coverage CLI tool

The CodeScene Coverage CLI tool is a command-line tool which helps upload code coverage data to your CodeScene instance.

Installation

Linux, macOS and Windows (if WSL)

The installation script will download the binary, move it to ~/.local/bin and make it executable. If ~/.local/bin is not in the user’s PATH, it will be added.

It works if your shell is one of: bash, zsh or fish

curl https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | sh

The command can be run in your terminal from any directory on your system.

Windows (Powershell)

The powershell script downloads the windows binary, moves it to $env:USERPROFILE\AppData\Local\Programs\CodeScene and makes it executable.

Invoke-WebRequest -Uri 'https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.ps1' -OutFile install-cs-coverage-tool.ps1
.\install-cs-coverage-tool.ps1

The command should be run in a Powershell terminal, from any folder on your system. In some cases, this may require administrator privileges.

Note, on non-server editions of Windows, the script execution policy is set to Restricted by default, and script execution is disabled. It can be enabled with:

Set-ExecutionPolicy RemoteSigned

This allows for the execution of trusted scripts downloaded from the internet, and all local scripts. For the CodeScene Coverage CLI tool, the script is considered a local file.

Manual installation

The binaries are also available for manual installation. Just download the binary for you platform and make it executable.

Updating

To update the tool, just run the install script again or re-do the manual installation.

You can check the version of the installed tool via cs-coverage version, which will print out the build date and SHA for the installed version.

Client setup

The CLI Coverage tool requires a Personal Access Token which can be created at https://your.codescene.com/configuration/user/token.

Then set your environment variables as follows, the pat token chars might require escaping, see escaping for: linux shell , windows comand prompt and windows power shell 

export CS_ONPREM_URL=<https://your.codescene.com>
export CS_ACCESS_TOKEN=<your-pat-token>

Or in windows(powershell):

$env:CS_ONPREM_URL = '<https://your.codescene.com>'
$env:CS_ACCESS_TOKEN = '<your-pat-token>'

Or in windows(comand prompt):

set "CS_ONPREM_URL = <https://your.codescene.com>"
set "CS_ACCESS_TOKEN = <your-pat-token>"

Note that the CLI upload tool requires that Git.

Uploading Code Coverage data using the CLI

After the CodeScene Coverage CLI tool is installed via script or manually as described above and your environment variables are set, the tool is ready to use.

cd /home/test/my-project-with-code-coverage
cs-coverage upload --format lcov --metric line-coverage /tmp/my-project-with-code-coverage.lcov

Running the uploader

Code coverage uploads are per Git repository. A single repository may require multiple uploads if there are, for example, different programming languages in the repository, and coverage data has been generated separately.

At each upload, CodeScene records the Git hash of the currently checked-out branch. This is done so that we can match coverage data as closely as possible with the Git data in the main analysis. Therefore, the following must be true:

  • The upload CLI must be executed from the root folder of your project. In this example the project is located at /home/test/my-project-with-code-coverage

  • During the upload, the local clone of your repository must be checked out to same commit/branch as the project being analysed by the CodeScene instance.

Ideally, the upload tool would be run immediately after the third-party coverage tools are run, which will ensure perfect alignment between the uploaded data and the currently checked out branch.

Arugments

The following arguments are required:

--format

The upload CLI tool can be used to upload the follwoing formats: open-clover, lcov, dotcover, jacoco, cobertura, ncover, bullseye, open-cover

--metric

The upload CLI tool supports the following metrics: condition-decision-coverage, sequence-point-coverage, statement-coverage, line-coverage, method-coverage, decision-coverage, condition-coverage, branch-coverage, function-coverage

<file>

The last argument is the path to file to upload. In the example above, we assume the code coverage data from project my-project-with-code-coverage was generated and saved at /tmp/my-project-with-code-coverage.lcov