LogoLogo
diffblue.comFree trial
  • Discover Diffblue Cover
  • Get Started
    • What is Diffblue Cover?
    • Get started
      • Free trial
      • Get started - Cover Plugin
      • Get started - Cover CLI
      • Get started - Cover Pipeline
      • Get started - Cover Reports
    • Specs & Reqs
    • Reference Deployments
    • Licensing
      • Online license activation
      • Offline license activation
      • Diffblue License Manager
    • Update Cover
    • FAQs
    • Diffblue Learning
      • Get started
        • Just the basics
        • Free trial
        • Cover Plugin (IDE)
        • Cover CLI (Command Line)
      • Developer
        • Unit tests (IDE)
        • Unit tests (CLI)
        • Test coverage
      • DevOps
        • GitHub
        • GitLab
        • Other CI
      • Administrator
        • Admin - IntelliJ
        • Admin - CLI
        • Admin - Reports
      • Test coverage
        • Developer
        • Senior developer
        • Cover Reports Administrator
  • EVALUATION & ONBOARDING
    • Proof of Value
    • Jumpstart
      • Prerequisites for onboarding
      • Phase 1: Up and running
        • Module 1: Create your Cover unit test baseline
        • Module 2: Cover Pipeline CI integration
      • Phase 2: Developer productivity
        • Module 3: Getting started using Cover
        • Module 4: Introduction to Cover Reports
      • Phase 3: Advanced topics
        • Module 5: Speed up your test execution
        • Module 6: Getting more from Cover
  • Features
    • Cover Plugin
      • Writing tests
        • Gutter icons
        • Menu options
        • Run configurations
        • Cover Plugin tool window
        • Test Review
        • Test examples
        • Creating partial tests
        • Creating skeleton tests
        • Covering all enum values
        • Test insertion order
        • Diffblue Sandbox
        • Environment Check Cache
      • Project configuration
        • General dependencies
        • Test framework dependencies
      • Cover Plugin settings
        • Test Naming
        • Test Formatting
        • Spring configuration options
        • Method Annotations
        • Test Directory
        • Reset Cover Plugin settings
      • Cover Plugin admin
        • Core Maintenance
        • Cover Plugin toolbar menu
        • Cover Plugin status bar widget
        • Telemetry
        • Memory management
        • Using SonarQube with Cover Plugin
        • Log files
        • Troubleshooting
    • Cover CLI
      • Writing tests
        • Command summary
        • Test examples
        • Creating partial tests
        • Customizing test inputs
        • Customizing test setup
        • Test naming
        • Test formatting
        • Test insertion order
        • Patch files
        • Diffblue Sandbox
        • Operational behaviors
        • Test validation
      • Project configuration
        • Preflight checks
        • General dependencies
        • Test framework dependencies
        • Compiling your project successfully
          • Building a Maven project
          • Building a Gradle project
        • Configuring Cover to work with your project's build system
          • Quick guide
          • Configuration file in detail
          • Getting Started with Ant Projects
          • Default configuration
        • Mocking using Mockito
        • Spring profiles
        • Runtime environment
      • Commands & Arguments
        • Environment configuration for CI
        • Packages, classes, and methods
        • Quoting command line arguments
        • Argument files
      • Cover CLI admin
        • Core Maintenance
        • Telemetry
        • Memory management
        • Using Cover CLI in Eclipse
        • Using SonarQube with Cover CLI
        • Log files
        • Troubleshooting
      • Environment Configuration
    • Cover Pipeline
      • Cover Pipeline for CI
        • Quick Start - General
        • Quick Start - Jenkins
        • Quick Start - Azure Pipelines
        • Quick Start - AWS Codebuild
        • Integrating Diffblue Cover into CI on pull requests
        • Installation - VMs or CI run
      • Cover Pipeline for GitLab
        • Introduction
        • Installation and initial setup
        • GitLab workflow
        • Configuration
        • Troubleshooting
        • Related topics
      • Cover Pipeline for GitHub
        • Introduction
        • Installation and initial setup
        • GitHub workflow
        • Configuration
        • Troubleshooting
        • Related topics
    • Cover Reports
      • Cover Reports Contributor
        • Java project config (JaCoCo)
        • Generate and upload reports bundles
        • Authenticated uploads
      • Cover Reports User
        • Navigation
        • Dashboards
        • Telemetry data
        • Export API
        • Considerations
      • Cover Reports Administrator
        • Install and update Cover Reports
        • Configuration options
        • Database backup
        • SSO with Cover Reports
        • Uninstall Cover Reports
    • Cover Optimize
      • Get started - Cover Optimize
      • Cover Optimize & Gradle
      • Cover Optimize & Maven
      • Patch files
    • Cover Refactor
      • Get started - Cover Refactor
    • Cover Annotations
      • Mocking Annotations
      • Custom Input Annotations
      • Interesting Value Annotations
    • Output Codes
      • E - Environment Codes
      • L - License Codes
      • R - Reason Codes
      • T - Testability Codes
      • V - Validation Codes
      • Working with output codes
        • Working with code E020
        • Working with codes E057 to E065
        • Working with code E085
        • Working with code R005
        • Working with code R006
        • Working with code R008
        • Working with code R011
        • Working with code R012
        • Working with code R013
        • Working with code R026
        • Working with code R031
        • Working with code V003
    • Tutorials
      • How to measure test quality
      • How to improve code coverage
      • How to test a new feature
      • How to find regressions
      • How to use Diffblue Cover in test driven development (TDD)
      • How to write tests for Kotlin projects
      • Examples of tests created by Diffblue Cover
      • Best practices for testing private methods
  • Updates & Upgrades
    • Update Cover
    • Cover Editions
    • What's new
    • Release archive
      • 2025-05-01
      • 2025-04-02
      • 2025-04-01
      • 2025-03-02
      • 2025-03-01
      • 2025-02-02
      • 2025-02-01
      • 2025-01-02
      • 2025-01-01
      • 2024-12-02
      • 2024-12-01
      • 2024-11-02
      • 2024-11-01
      • 2024-10-02
      • 2024-10-01
      • 2024-09-02
      • 2024-09-01
      • 2024-08-02
      • 2024-08-01
      • 2024-07-04
      • 2024-07-03
      • 2024-07-01
      • 2024-06-02
      • 2024-06-01
      • 2024-05-02
      • 2024-05-01
      • 2024-04-02
      • 2024-04-01
      • 2024-03-02
      • 2024-03-01
      • 2024-02-02
      • 2024-02-01
      • 2024-01-02
      • 2024-01-01
      • 2023-12-02
      • 2023-12-01
      • 2023-11-03
      • 2023-11-02
      • 2023-11-01
      • 2023-10-02
      • 2023-10-01
      • 2023-09-02
      • 2023-09-01
      • 2023-08-02
      • 2023-08-01
      • 2023-07-03
      • 2023-07-02
      • 2023-07-01
      • 2023-06-02
      • 2023-06-01
      • 2023-05-02
      • 2023-05-01
      • 2023-04-02
      • 2023-04-01
      • 2023-03-02
      • 2023-03-01
      • 2023-02-02
      • 2023-02-01
      • 2023-01-02
      • 2023-01-01
      • 2022-12-02
      • 2022-12-01
      • 2022-11-02
      • 2022-11-01
      • 2022-10-03
      • 2022-10-02
      • 2022-10-01
      • 2022-09-02
      • 2022-09-01
      • 2022-08-05
      • 2022-08-03
      • 2022-08-02
      • 2022-08-01
      • 2022-07-02
      • 2022-07-01
      • 2022-06-02
      • 2022-06-01
      • 2022-05-02
      • 2022-05-01
      • 2022-04-02
      • 2022-04-01
      • 2022-03-02
      • 2022-03-01
      • 2022-02-02
      • 2022-02-01
      • 2022-01-02
      • 2022-01-01
      • 2021-06-02
      • 2021-02-01
  • Legal
    • Diffblue Legal
      • Diffblue End User License Agreement (EULA)
      • Cover Third Party Notices and/or Licenses
      • Privacy Notice
Powered by GitBook
On this page
  • Non-Docker options
  • Setting properties in the config file (local)
  • Setting properties with environment variables (global)
  • Using an external database server
  • Changing the default port (Docker)
  • Using telemetry in Cover Reports
  • Telemetry configuration
  • Manage configurations
  • Cover Reports - telemetry home page
  • Upload authentication
  • Enable upload authentication
  • Upload with authentication
  • Export API authentication
  • Enable API Authentication
  • Authenticating with the API

Was this helpful?

Export as PDF
  1. Features
  2. Cover Reports
  3. Cover Reports Administrator

Configuration options

Cover Reports provides for a range of configuration options.

Non-Docker options

There are several config options available when Cover Reports is run as a Windows Service, Linux Service, Windows .bat, or macOS/Linux .sh. These can be configured locally via the application.properties config file in the folder where the cover-reports instance is running, or globally via environment variables.

Setting properties in the config file (local)

  1. If needed, copy the "template" application.properties file from [install]/bin/ to the folder where the cover-reports instance is running. Edit the application.properties file and edit/add the following, as required - if you don't need to change the default values you can leave the line(s) commented out.

# Cover Reports configuration
#server.port=<COVER-REPORTS-PORT>
#logging.file.name=<LOG-PATH>/cover-reports.log

# H2 configuration
#reports.h2.path=<H2-PATH>

# External PostgreSQL DB config
#spring.profiles.active=postgres
#spring.datasource.url=jdbc:postgresql://<DB-SERVER-HOSTNAME>:<DB-SERVER-PORT>/reports
#spring.datasource.username=reports
#spring.datasource.password=<REPORTS-DB-PASSWORD>

# Upload Authentication
#reports.users.upload.username=username
#reports.users.upload.password=password

# Export API Authentication
#reports.users.api.username=username
#reports.users.api.password=password
Field
Description

server.port

Cover Reports listens on port 8080 by default. If this port is already in use, you can change it here. Note that if you change the port, this needs to be replicated when accessing the Cover Reports UI (via a browser) and when uploading reports bundles from Cover CLI and Cover Pipeline.

logging.file.name

Cover Reports logs are saved to cover-reports.log by default, in the root directory of your Reports install. You can change the default path if needed.

reports.h2.path

Cover Reports uses a local H2 database for coverage details and general data. Data files are stored in the root directory of your Reports install - you can change the default path if needed.

External PostgreSQL

DB config

Upload Authentication

Export API Authentication

Setting properties with environment variables (global)

Edit the cover-reports.xml file in your Cover Reports installation. Edit/add the following environment variables in the <service> section, as needed.

<env name="SERVER_PORT" value="8080"/>
<env name="LOGGING_FILE_NAME" value="%BASE%\cover-reports.log"/>
<env name="REPORTS_H2_PATH" value="%BASE%"/>
  
<env name="JAVA_HOME" value="<JAVA-PATH>"/>

<env name="SPRING_PROFILES_ACTIVE" value="postgres"/>
<env name="SPRING_DATASOURCE_URL value="jdbc:postgresql://<DB-SERVER-HOSTNAME>:<DB-SERVER-PORT>/reports"/>
<env name="SPRING_DATASOURCE_USERNAME value="reports"/>
<env name="SPRING_DATASOURCE_PASSWORD value="<REPORTS-DB-PASSWORD>"/>

<env name="REPORTS_USERS_UPLOAD_USERNAME value="username"/>
<env name="REPORTS_USERS_UPLOAD_PASSWORD value="password"/>

<env name="REPORTS_USERS_API_USERNAME value="api-username"/>
<env name="REPORTS_USERS_API_PASSWORD value="api-password"/>

Edit the cover-reports.service file in your Cover Reports installation. Edit/add the following environment variables in the [Service] section, as needed.

[Service]
User=cover-reports
Environment="SERVER_PORT=8080"
Environment="LOGGING_FILE_NAME=<LOG-PATH>/cover-reports.log"
Environment="REPORTS_H2_PATH=<H2-PATH>"
Environment="JAVA_HOME=<JAVA-PATH>"

ExecStart=<COVER-REPORTS-PATH>/cover-reports/bin/cover-reports

Environment="SPRING_PROFILES_ACTIVE=postgres"
Environment="SPRING_DATASOURCE_URL=jdbc:postgresql://<DB-SERVER-HOSTNAME>:<DB-SERVER-PORT>/reports"
Environment="SPRING_DATASOURCE_USERNAME=reports"
Environment="SPRING_DATASOURCE_PASSWORD=<REPORTS-DB-PASSWORD>"

Environment="REPORTS_USERS_UPLOAD_USERNAME=username"
Environment="REPORTS_USERS_UPLOAD_PASSWORD=password"

Environment="REPORTS_USERS_API_USERNAME=api-username"
Environment="REPORTS_USERS_API_PASSWORD=api-password"
Field
Description

SERVER_PORT

Cover Reports listens on port 8080 by default. If this port is already in use, you can change it here. Note that if you change the port, this needs to be replicated when accessing the Cover Reports UI (via a browser) and when uploading reports bundles from Cover CLI and Cover Pipeline.

LOGGING_FILE_NAME

Cover Reports logs are saved to cover-reports.log by default, in the root directory of your Reports install. You can change the default path if needed.

REPORTS_H2_PATH

Cover Reports uses a local H2 database for coverage details and general data. Data files are stored in the root directory of your Reports install - you can change the default path if needed.

JAVA_HOME

Java JDK PATH.

COVER-REPORTS-PATH

macOS/Linux executable path for Cover Reports.

SPRING...

REPORTS_USERS_UPLOAD...

REPORTS_USERS_API...

Using an external database server

When using Cover Reports in a production grade environment you also need to provide an external PostgreSQL database in place of the default H2 database:

  1. Create a new database and user on the PostgreSQL server.

  2. Grant all privileges on the new database to the new user.

  3. Define the PostgreSQL settings as detailed above (local config or global environment variables).

Field
Description

spring.profiles.active SPRING_PROFILES_ACTIVE

Profile type - set this value to postgres

spring.datasource.url SPRING_DATASOURCE_URL

URL for the PostgreSQL database created for Cover Reports data, including the name of the database.

spring.datasource.username SPRING_DATASOURCE_USERNAME

Username used to access the database.

spring.datasource.password SPRING_DATASOURCE_PASSWORD

Password used to access the database.

Changing the default port (Docker)

Cover Reports listens on port 8080 by default. If this port is already in use, you can change it in the docker-compose.yml file. Note that if you change the port, this needs to be replicated when accessing the Cover Reports UI (via a browser) and when uploading reports bundles from Cover CLI and Cover Pipeline. To change the port:

  1. In your shell, navigate to $COVER_REPORTS_HOME and stop Cover Reports using:

docker compose down
  1. Edit the docker-compose.yml file and update the ports value. Note that the value specified is in the format <external-port>:<internal-port> - update the <external-port> value only.

```shell
	ports:
	  - "9090:8080"
```
  1. From the $COVER_REPORTS_HOME directory, start Cover Reports using:

docker compose up -d

Using telemetry in Cover Reports

Cover Reports can collect usage telemetry from Cover CLI and Cover Plugin installations to give you vital information on usage across your organization.

Telemetry configuration

Telemetry can be configured (if required) using environment variables, and/or a properties file, on the host machine (where Diffblue Cover is being used). Note that these configuration settings apply to Cover CLI and Cover Plugin.

  • Environment variables (listed below) always take priority and is the recommended method for configuring telemetry.

  • If you use a properties file, create a telemetry.properties file in the home directory under the .diffblue folder (for example, /users/joeblogs/.diffblue/telemetry.properties) and define one or more of the properties listed below.

  • If an individual environment variable or property is not found, the default value will be used.

Environment variable
Property
Description
Default

DIFFBLUE_TELEMETRY_ EXTERNAL_ENABLED

telemetry.

external.

enabled

Enable (true) or disable (false) telemetry data for Diffblue. *

true

DIFFBLUE_TELEMETRY_ REPORTS_ENABLED

telemetry.

reports.

enabled

Enable (true) or disable (false) telemetry data for Cover Reports.

false

DIFFBLUE_TELEMETRY_ REPORTS_HOSTNAME

telemetry.

reports.

hostname

Hostname of your Cover Reports server.

localhost

DIFFBLUE_TELEMETRY_ REPORTS_PORT

telemetry.

reports.

port

Port number of your Cover Reports instance

8080

DIFFBLUE_TELEMETRY_ REPORTS_SCHEME

telemetry.

reports.

scheme

Protocol used to communicate with Cover Reports - http or https

http

* Disabling the Diffblue endpoint for telemetry data is only available to Diffblue Cover Enterprise Edition customers.

Example telemetry.properties file:

# Copyright 2021-2024 Diffblue Limited. All Rights Reserved.
# Example telemetry.properties file
telemetry.external.enabled=true
telemetry.reports.enabled=true
telemetry.reports.hostname=localhost
telemetry.reports.port=8080
telemetry.reports.scheme=http

Manage configurations

If you need to manage telemetry configuration across your organization, you can set the environment variables defined above (as needed) and apply these settings across your organization (for example, using a group policy).

Cover Reports - telemetry home page

To view telemetry data for your organization in Cover Reports, navigate to your Cover Reports telemetry home page, e.g. http://cover-reports.mycompany.com:8080/ui/telemetry. From this view, you can select either the CLI tab for CLI events, or the Plugin tab for plugin events:

Upload authentication

By default, any Diffblue Cover user can upload reports bundles to Cover Reports. However, you may want to restrict and/or secure access using upload authentication. For example, you may want to restrict upload to your CI processes only, so that the data and upload timings are consistent.

Enable upload authentication

  1. Stop Cover Reports by running: docker compose down

  2. In your docker-compose.yml file, add two new environment variables (REPORTS_USERS_UPLOAD_USERNAME and REPORTS_USERS_UPLOAD_PASSWORD), and replace <username> and <password> with the username and password to use for uploading reports bundles:

  report-web:
    depends_on:
      postgres:
        condition: service_started
    environment:
      REPORTS_USERS_UPLOAD_USERNAME: <username>
      REPORTS_USERS_UPLOAD_PASSWORD: <password>

Note: Use ASCII characters only in your username and password. Also, do not use an empty string as this may cause unexpected behaviour.

  1. Save your changes to docker-compose.yml and start your Cover Reports instance by running: docker compose up

  1. Stop Cover Reports (if currently running).

  2. In your application.properties file, add two new variables (reports.users.upload.username=username and reports.users.upload.password=password), replacing <username> and <password> with the username and password to use for uploading reports bundles:

reports.users.upload.username=<username>
reports.users.upload.password=<password>

Note: Use ASCII characters only in your username and password. Also, do not use an empty string as this may cause unexpected behaviour.

  1. Save your changes and start your Cover Reports instance.


Alternatively you can add these two variables to your environment variables:

REPORTS_USERS_UPLOAD_USERNAME: <username>
REPORTS_USERS_UPLOAD_PASSWORD: <password>

For Cover Reports Release 2025.03.01 or earlier, use reports.requiredusername, reports.requiredpassword, REPORTS_REQUIREDUSERNAME, and REPORTS_REQUIREDPASSWORD. For Cover Reports Release 2025.03.02 and later, use reports.users.upload.username, reports.users.upload.password, REPORTS_USERS_UPLOAD_USERNAME, and REPORTS_USERS_UPLOAD_PASSWORD. The older property names are deprecated and will be removed in a future release.

Upload with authentication

Once upload authentication has been enabled, reports bundles can be uploaded from Cover CLI and Cover Pipeline using the username and password defined above. See Authenticated uploads for details.

Export API authentication

By default, any Diffblue Cover user can access the Cover Reports export API. However, you may want to restrict and/or secure access using API authentication. For example, you may want to restrict access to specific systems only.

Enable API Authentication

  1. Stop Cover Reports by running: docker compose down

  2. In your docker-compose.yml file, add two new environment variables (REPORTS_USERS_API_USERNAME and REPORTS_USERS_API_PASSWORD), and replace <username> and <password> with the username and password to use for accessing the API:

  report-web:
    depends_on:
      postgres:
        condition: service_started
    environment:
      REPORTS_USERS_API_USERNAME: <username>
      REPORTS_USERS_API_PASSWORD: <password>

Note: Use ASCII characters only in your username and password. Also, do not use an empty string as this may cause unexpected behaviour.

  1. Save your changes to docker-compose.yml and start your Cover Reports instance by running: docker compose up

  • Stop Cover Reports (if currently running).

  • In your application.properties file, add two new variables (reports.users.api.username=username and reports.users.api.password=password), replacing <username> and <password> with the username and password to use for accessing the API:

reports.users.api.username=<username>
reports.users.api.password.password=<password

Note: Use ASCII characters only in your username and password. Also, do not use an empty string as this may cause unexpected behaviour.

  • Save your changes and start your Cover Reports instance.


Alternatively you can add these two variables to your environment variables:

REPORTS_USERS_API_USERNAME: <username>
REPORTS_USERS_API_PASSWORD: <password>

Authenticating with the API

Once authentication has been enabled, it is up to the client to authenticate with Cover Reports using the configured username and password.

This is done by sending a POST request to /report/authenticate, where the username and password are provided in the request parameters:

  • username

  • password

PreviousInstall and update Cover ReportsNextDatabase backup

Last updated 1 month ago

Was this helpful?

If you wish to use an external PostgreSQL data in place of the default H2 database, define the settings in this section. See for details.

If you wish to add authentication to uploads, define the settings in this section. See for details.

If you wish to add authentication to the export API, define the settings in this section. See for details.

If you wish to use an external PostgreSQL data in place of the default H2 database, define the settings using these environment variables. See for details.

If you wish to add authentication to uploads, define the settings using these environment variables. See for details.

If you wish to add authentication to the export API, define the settings using there environment variables. See for details.

For general Telemetry config detail, refer to the telemetry topics for and .

The authentication mechanism allows only a single user to be defined. This mechanism is the same as for , although the API user is separate from the upload user.

If the username and password match the required username and password, a will be returned. This token must then be attached as the in all subsequent requests to the API endpoints.

Cover CLI
Cover Plugin
upload authentication
JSON Web Token
Bearer token in the Authorization HTTP header
Using an external database server
Upload authentication
Export API authentication
Using an external database server
Upload authentication
Export API authentication