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
  • Cover Pipeline Integration
  • Create, Generate, Upload
  • Generate Only
  • Upload Only
  • Considerations

Was this helpful?

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

Generate and upload reports bundles

PreviousJava project config (JaCoCo)NextAuthenticated uploads

Last updated 2 months ago

Was this helpful?

Cover Reports data, referred to as "reports bundles", are generated as part of your code development process and uploaded to Cover Reports. This can be done from Cover CLI and/or Cover Pipeline, using the appropriate dcover commands detailed in this topic. Reports bundles are comprised of the following files:

  • report.json - Diffblue's coverage report.

  • diffblue-tests-jacoco-report.xml - a JaCoCo coverage report providing data for Diffblue tests (created by Diffblue Cover).

  • manual-tests-jacoco-report.xml – a JaCoCo coverage report providing data for manual tests (created by a developer).

Reports bundles can be generated and uploaded as follows:

  • - integration with Cover Pipeline reporting on the baseline tests, after-merge or periodically.

  • - create tests, generate the reports bundle, and upload the bundle to the Cover Reports server.

  • - generate the reports bundle only, no tests created, no upload.

  • - upload an existing reports bundle only.

The associated dcover commands can be run from Cover CLI or integrated into your CI/CD workflow/pipeline as needed.

Before generating any reports bundles, run dcover coverage-reports --preflight to check if all preconditions necessary for generating the reports are met, without creating the reports themselves.

Command summary (core options only):

// Create, Generate, and Upload
dcover create
--coverage-reports
--upload=<reports-server>

// Generate Only
dcover coverage-reports

// Upload Only
dcover upload <reports-server>

// Cover Pipeline Integration (not recommended)
dcover ci create coverage-reports upload <reports-server>

You can also omit the <reports-server> parameter if you prefer to specify the upload url via environment variable instead. For example:

export DIFFBLUE_COVER_REPORTS_UPLOAD_URL=<reports-server>

// Create, Generate, and Upload
dcover create --coverage-reports --upload

// Upload Only
dcover upload

Cover Pipeline Integration


Create, Generate, Upload

This topic details the dcover command to create tests, generate the reports bundle, and upload the bundle to the Cover Reports server. Note that Cover Reports is primarily focused on reporting the full test suite and so this approach is not recommend in combination with the create --patch-only option.

Prerequisites:

  • Configure your project to generate JaCoCo files (see Java project config (JaCoCo)).

  • Build your project.

Command details:

Run the following dcover command:

dcover create
--coverage-reports
--upload=<reports-server>
--name=<name-of-report>
--project-name=<name-of-project>
--location=<report-location>
--report-username=<username>
--report-password=<password>
--class-name-template=${CLASS_NAME}<string>

For example:

dcover create
--coverage-reports
--upload=http://cover-reports-service:8080
--name="Branch: 1234/feature-TG12345"
--project-name="hello-world"
--location="customer-markets.trading.name"
--report-username="myusername"
--report-password="mypassword"
--class-name-template="${CLASS_NAME}CreatedTests"
Argument
Description

--coverage-reports

Generates the reports bundle.

--upload=<reports-server>

Uploads the reports bundle to the specified Cover Reports server. See your Cover Reports Administrator for details, if needed.

--name=<name-of-report>

Sets the name of the reports bundle. Replace <name-of-report> with a useful name. If the --name argument is omitted, the name will default to the current timestamp, or the latest commit hash when used within Git.

--project-name=<name-of-project>

Sets the specific name of the project to which this reports bundle relates. Replace <name-of-project> with a useful name. If the --project-name argument is omitted, the project name in Cover Reports will default to the project name defined by the build system, which is recommended.

--location=<report-location>

Sets the path to the project in Cover Reports. Replace <report-location> with a useful value, with folder names separated by dots. If the provided location does not exist it will be created. If the --location argument is omitted, the project will be placed in the default location. Project locations can be changed from within Cover Reports at any time.

--report-username=<username>

--report-password=<password>

--class-name-template="${CLASS_NAME}<string>"

Used to define a custom test class naming convention to identify tests written by Diffblue Cover. If this argument omitted, the default value of *DiffblueTest will be used

Semicolon (;), forward slash (/), backslash (\), and percent sign (%) are not allowed in the --project-name and --location arguments due to security reasons. These characters will be automatically removed to prevent potential security risks, and the upload process will continue.

The previous --report argument has been replaced with --upload (Diffblue Cover release 2023.11.01 and later). Use of --report should be avoided as this option will be fully removed in future releases.

Optional JaCoCo arguments:

Argument
Description

--jacoco-command-diffblue =<command>

Custom command to generate the JaCoCo report for tests written by Diffblue Cover.

--jacoco-command-manual =<command>

Custom command to generate the JaCoCo report for manually written tests.

--jacoco-xml-test-report =<jacoco-xml-test-report>

Filename and path (including the .xml extension) of the JaCoCo report created using custom commands (as defined above).

Examples (using default values):

// jacoco-command-diffblue for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='*DiffblueTest.java'"

// jacoco-command-manual for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='!*DiffblueTest.java'"

// jacoco-command-diffblue for Gradle
--jacoco-command-diffblue=./gradlew test --tests=*DiffblueTest.java

// jacoco-command-manual for Gradle
// There is currently no simple way to provide an exlusion pattern to Gradle
// via the command line, we suggest using --class-name-template instead
// jacoco-command-diffblue for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='*DiffblueTest.java'"

// jacoco-command-manual for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='!*DiffblueTest.java'"

// jacoco-command-diffblue for Gradle
--jacoco-command-diffblue="./gradlew test --tests=*DiffblueTest.java"

// jacoco-command-manual for Gradle
// There is currently no simple way to provide an exlusion pattern to Gradle
// via the command line, we suggest using --class-name-template instead

Please see --class-name-template in Commands & Arguments as a standardised way to define a template for what is and is not counted as a diffblue test that works with Gradle and Maven


Generate Only

Generate the reports bundle only - no tests created, no upload to the server. This can be useful if tests have already been created for the project using dcover create, but the --coverage-reports option wasn't included.

Prerequisites:

  • Configure your project to generate JaCoCo files (see Java project config (JaCoCo)).

Command details:

Run the following dcover command:

dcover coverage-reports

Once the reports bundle has been generated, you can upload the bundle to your Cover Reports server using dcover upload - see Upload Only below.

Optional arguments (as detailed in Commands & Arguments):

Additional JaCoCo arguments:

Argument
Description

--jacoco-command-diffblue =<command>

Custom command to generate the JaCoCo report for tests written by Diffblue Cover.

--jacoco-command-manual =<command>

Custom command to generate the JaCoCo report for manually written tests.

--jacoco-xml-test-report =<jacoco-xml-test-report>

Filename and path (including the .xml extension) of the JaCoCo report created using custom commands (as defined above).

Examples (using default values):

// jacoco-command-diffblue for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='*DiffblueTest.java'"

// jacoco-command-diffblue for Gradle
--jacoco-command-diffblue=./gradlew test --tests=*DiffblueTest.java

// jacoco-command-manual for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='!*DiffblueTest.java'"

// jacoco-command-manual for Gradle
--jacoco-command-diffblue=./gradlew clean test --tests=!*DiffblueTest.java
// jacoco-command-diffblue for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='*DiffblueTest.java'"

// jacoco-command-diffblue for Gradle
--jacoco-command-diffblue="./gradlew test --tests=*DiffblueTest.java"

// jacoco-command-manual for Maven
--jacoco-command-diffblue="mvn clean test jacoco:report -Dtest='!*DiffblueTest.java'"

// jacoco-command-manual for Gradle
--jacoco-command-diffblue="./gradlew clean test --tests=!*DiffblueTest.java"

Upload Only

Upload an existing reports bundle only. This can be useful when the reports bundle has been generated separately, but not uploaded.

Command details:

Run the following dcover command:

dcover upload <reports-server>
--name=<name-of-report>
--project-name=<name-of-project>
--location=<report-location>
--report-username=<username>
--report-password=<password>

For example:

dcover upload http://cover-reports-service:8080
--name="Branch: 1234/feature-TG12345"
--project-name="hello-world"
--location="customer-markets.trading.name"
--report-username="myusername"
--report-password="mypassword"
Component
Description

dcover upload

<reports-server>

Uploads the reports bundle to the Cover Reports server. Replace <reports-server> with the URL and port number for your server. See your Cover Reports Administrator for help, if needed.

--name =<name-of-report>

Sets the name of the reports bundle. Replace <name-of-report> with a useful name. If the --name argument is omitted, the name will default to the current timestamp, or the latest commit hash when used within Git.

--project-name=<name-of-project>

Sets the specific name of the project to which this reports bundle relates. Replace <name-of-project> with a useful name. If the --project-name argument is omitted, the project name in Cover Reports will default to the project name defined by the build system, which is recommended.

--location=<report-location>

Sets the path to the project in Cover Reports. Replace <report-location> with a useful value, with folder names separated by dots. If the provided location does not exist it will be created. If the --location argument is omitted, the project will be placed in the default location. Project locations can be changed from within Cover Reports at any time.

--report-username=<username>

--report-password=<password>

Cover Reports username and password, used for authenticated uploads only. The username and password must match those configured by your Cover Reports Administrator.

Semicolon (;), forward slash (/), backslash (\), and percent sign (%) are not allowed in the --project-name and --location arguments due to security reasons. These characters will be automatically removed to prevent potential security risks, and the upload process will continue.

Additional optional arguments (as detailed in Commands & Arguments):

Additional JaCoCo arguments:

Argument
Description

--jacoco-report-diffblue

=<report>

Filename and path (including the .xml extension) of the JaCoCo report for Diffblue tests (if a non-standard location is used). Optional.

--jacoco-report-manual

=<report>

Filename and path (including the .xml extension) of the JaCoCo report for manually written tests (if a non-standard location is used). Optional.


Considerations

When generating, naming, and uploading reports bundles, consider the following. You may also wish to discuss these with your Cover Reports Users and Cover Reports Administrators as appropriate.

  • Generate & Upload - Timing: You can generate and upload reports bundles before, during, and after code development. For consistency, you may wish to define specific schedules and you may also find it useful to generate and upload reports for your project before you run dcover create on the project for the first time (useful for setting a coverage baseline) - see Generate Only and Upload Only.

  • Naming Conventions: The --name, --project-name and --location arguments are used to structure the uploaded data within Cover Reports. Diffblue recommends that you select an appropriate and consistent naming convention to help with data visualization in the Cover Reports UI. Alternatively, don't use these options and allow the data to be auto-generated.

  • Authentication: If upload authentication has been enabled by your Cover Reports Administrator, you'll need to use the defined username and password when uploading your reports bundles. See Authenticated uploads for details.

For information about integrating Cover Reports into Cover Pipeline please see.

Cover Reports username and password. Used for authenticated uploads only - see . The username and password must match those configured by your Cover Reports Administrator.

Cover Pipeline Integration
Create, Generate, Upload
Generate Only
Upload Only
Authenticated uploads
batch
build-system-configuration
classpath
compliance-level
define
environment
gradle
ignore-stylechecks
maven
preflight
test-framework
verbose
working-directory
batch
build-system-configuration
classpath
define
environment
gradle
maven
preflight
report-file
verbose
working-directory
Integrating with Diffblue Cover Reports
exclude-modules
include-modules
strict
exclude-modules
include-modules
strict