Getting started with Code Coverage in CodeScene

This guide helps you set up code coverage in CodeScene as quickly as possible.

By the end of this guide, you will have:

  1. Generated code coverage data in your CI pipeline.

  2. Uploaded the results to CodeScene with the Coverage CLI.

  3. Run or wait for a new CodeScene analysis.

  4. Verified the results in the Code Coverage dashboard and Explore view.

What CodeScene does

CodeScene does not generate code coverage data itself. Your test tools generate the coverage report, and CodeScene ingests that data so you can visualize and explore it.

The basic workflow is:

Generate coverage in CI -> Upload it to CodeScene -> Run a new analysis -> Verify the results in CodeScene

If you want to check or block pull requests based on coverage, use the separate guide for Code Coverage gates. This guide focuses on uploading coverage data so it can be visualized in CodeScene.

Before you start

Make sure you have the following in place:

  • A CodeScene project that already analyzes your repository.

  • A CI/CD pipeline that runs your tests.

  • A coverage tool that outputs a format supported by CodeScene.

  • A Personal Access Token for the Coverage CLI.

  • Git available in the environment where cs-coverage upload runs.

Supported formats and metrics

CodeScene supports multiple coverage formats and metrics.

Common examples include:

  • lcov: line-coverage, branch-coverage, function-coverage

  • cobertura: line-coverage

  • jacoco: line-coverage, branch-coverage

  • open-cover: line-coverage, sequence-point-coverage, method-coverage, branch-coverage

  • open-clover: line-coverage, method-coverage, condition-coverage, statement-coverage

  • dotcover: line-coverage, statement-coverage

  • ncover: line-coverage, sequence-point-coverage

  • bullseye: line-coverage, method-coverage, condition-decision-coverage, decision-coverage

You can upload multiple metrics for the same repository. Each metric appears as a separate coverage type in CodeScene.

Step 1: Create your access token

The Coverage CLI uses a Personal Access Token.

Create one in your CodeScene instance and then configure the required environment variables.

Linux/macOS:

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

PowerShell:

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

Command Prompt:

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

Step 2: Install the Coverage CLI

Install the CodeScene Coverage CLI in the environment where your CI pipeline runs the coverage upload.

The easiest option is to use the install script. If your environment does not allow install scripts, you can also download and install the binary manually.

Option A: Install with the script

Linux, macOS, and Windows with WSL:

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

PowerShell:

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

To verify the installation:

cs-coverage version

Option B: Manual installation

Use manual installation if you cannot run the install script, for example in restricted on-prem environments or locked-down CI runners.

  1. Download the correct cs-coverage binary for your operating system and architecture.

  2. Extract the archive if needed.

  3. Move the binary to a directory on your PATH.

  4. Verify that the command works.

Linux/macOS example:

chmod +x cs-coverage 
sudo mv cs-coverage /usr/local/bin/ 

cs-coverage version

Windows PowerShell example:

# Place cs-coverage.exe in a folder such as C:\tools\cs-coverage
# Then add that folder to PATH for the current user.
[Environment]::SetEnvironmentVariable(
  "Path",
  $env:Path + ";C:\tools\cs-coverage",
  "User"
)

cs-coverage version

If cs-coverage version is not found, check that the binary location is included in PATH and restart the terminal or CI shell session.

CI-friendly installation without sudo

Some CI environments do not allow sudo or global installation. In that case, install the binary into a local tools directory and add it to PATH for the current job.

Example:

mkdir -p .codescene/bin 

# Download or copy the cs-coverage binary into .codescene/bin 

chmod +x .codescene/bin/cs-coverage 
export PATH="$PWD/.codescene/bin:$PATH" 

cs-coverage version

Use this approach when the CI runner is ephemeral or when you want the installation to be fully contained inside the workspace.

Step 3: Generate coverage in your CI pipeline

CodeScene does not create the coverage report. Your build or test step must generate it first.

Examples:

  • JavaScript/TypeScript projects often produce LCOV.

  • Java projects often produce JaCoCo XML.

  • .NET projects may produce OpenCover or dotCover output.

If your repository contains multiple languages or multiple independently generated reports, you may need multiple uploads.

Step 4: Upload coverage to CodeScene

Upload coverage from the repository root after the coverage report has been generated.

Examples:

# LCOV line coverage 

cd /path/to/your/repository 
cs-coverage upload --format lcov --metric line-coverage coverage/code-coverage.lcov 
# LCOV branch coverage from the same report 

cd /path/to/your/repository 
cs-coverage upload --format lcov --metric branch-coverage coverage/code-coverage.lcov 
# JaCoCo line coverage 

cd /path/to/your/repository 
cs-coverage upload --format jacoco --metric line-coverage target/site/jacoco/jacoco.xml 
# JaCoCo branch coverage 

cd /path/to/your/repository 
cs-coverage upload --format jacoco --metric branch-coverage target/site/jacoco/jacoco.xml 
# Cobertura line coverage 

cd /path/to/your/repository 
cs-coverage upload --format cobertura --metric line-coverage coverage/cobertura-coverage.xml 
# OpenCover branch coverage 

cd /path/to/your/repository 
cs-coverage upload --format open-cover --metric branch-coverage TestResults/coverage.opencover.xml

Important rules for uploads

  • Run the uploader from the repository root.

  • Make sure the local checkout matches the same commit or branch that CodeScene analyzes.

  • Run the upload immediately after the coverage report is generated whenever possible.

  • If multiple uploads contain data for the same file, CodeScene uses the most recent applicable upload for that file.

  • Coverage data is uploaded per Git repository.

Upload command examples by format

Use the format, metric, and file path that match the report your test tooling actually generates. CodeScene supports multiple formats and metrics, and you can upload multiple metrics for the same repository.

Golden path: GitHub Actions

This example shows a complete GitHub Actions workflow for uploading coverage data to CodeScene. Replace the test command and coverage file path with the values used by your project.

name: Upload Code Coverage to CodeScene

on:
  push:
    branches:
      - main
  workflow_dispatch:

jobs:
  coverage:
    runs-on: ubuntu-latest

    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Run tests and generate coverage
        run: |
          # Replace this with your project's actual test command
          # and make sure it generates a supported coverage report.
          echo "Run tests here and generate coverage"

      - name: Install CodeScene Coverage CLI
        run: curl https://downloads.codescene.io/enterprise/cli/install-cs-coverage-tool.sh | bash -s -- -y

      - name: Upload coverage data to CodeScene
        run: cs-coverage upload --format "lcov" --metric "line-coverage" "coverage/code-coverage.lcov"
        env:
          CS_ONPREM_URL: ${{ secrets.CS_ONPREM_URL }}
          CS_ACCESS_TOKEN: ${{ secrets.CS_ACCESS_TOKEN }}

What to update in this workflow:

  • Replace the test command with the one your project actually uses.

  • Make sure the test step produces a supported coverage report.

  • Change --format, --metric, and the file path to match your report.

  • Store CS_ONPREM_URL and CS_ACCESS_TOKEN as repository or organization secrets.

Generic pipeline pattern: GitLab CI, Azure DevOps, Jenkins, and others

The provider does not matter as long as the pipeline does the same four things:

  1. Check out the repository.

  2. Run tests and generate a supported coverage report.

  3. Install cs-coverage.

  4. Run cs-coverage upload from the repository root.

Example shell sequence:

# Run from the checked-out repository 
export CS_ONPREM_URL=https://your.codescene.com 
export CS_ACCESS_TOKEN=<your-pat-token> 

# Run your tests here and generate coverage first 
# Example: produce coverage/code-coverage.lcov 

cs-coverage upload --format lcov --metric line-coverage coverage/code-coverage.lcov

For non-GitHub providers, the most important thing is that the upload runs in the same checked-out repository and on the same commit or branch that CodeScene will analyze.

Step 5: Run or wait for a new analysis

Uploaded coverage data only becomes visible in the Project Dashboard after a new CodeScene analysis runs.

If your project is already analyzed automatically, wait for the next analysis.

To trigger an analysis manually:

curl -X POST -H 'Accept: application/json' -H 'Authorization: Bearer <token>' \ 'https://your.codescene.com/api/v2/projects/{project-id}/run-analysis'

Replace {project-id} with the correct project id.

Step 6: Verify the results in CodeScene

After the next analysis completes, verify the result in these places:

  • Code Coverage dashboard: review overall coverage, hotspot coverage, uncovered files, and trends over time.

  • Explore view: inspect code coverage on the system map and drill down to folders and files.

  • Analysis warnings: if coverage does not line up with the analyzed commit, check warnings in Project Dashboard -> Scope -> Analysis Data -> Analysis Warnings.

Common mistakes and what to check

Coverage is not visible in CodeScene

Check the following:

  • A new analysis has run after the upload.

  • The upload used the correct repository checkout.

  • The upload was performed from the repository root.

  • The format, metric, and file path match the generated report.

Some files show no coverage

This can happen when:

  • Coverage was uploaded for an ancestor commit and those files changed afterwards.

  • Coverage is only generated for part of the codebase.

  • A language or repository in a larger setup is not covered yet.

The results look incomplete or misleading

Remember:

  • CodeScene only uses coverage data that matches the same commit or an ancestor commit.

  • If coverage is from an ancestor commit, files changed since then will not show coverage data.

  • CodeScene does not merge coverage data for the same file across uploads.

Excluding false positives

If some files or folders do not have coverage data yet, CodeScene may treat them as 0% coverage by default.

To avoid misleading results, define code coverage exclusions in the project configuration using glob patterns relative to the repository root.

Excluded files appear as grey circles in the system map and do not affect the code coverage KPIs and averages.

Next step: Code Coverage gates for pull requests

If you want to enforce coverage in pull requests or merge requests, continue with the separate guide for Code Coverage gates.

That setup is different from the upload flow in this guide:

  • coverage uploads are for visualization and analytics in CodeScene

  • coverage gates run in CI and evaluate pull requests or build results