# Generate and upload reports bundles

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:

* [**Cover Pipeline Integration**](#cover-pipeline-integration) - integration with Cover Pipeline reporting on the baseline tests, after-merge or periodically.
* [**Create, Generate, Upload**](#create-generate-upload-reports-bundles) - create tests, generate the reports bundle, and upload the bundle to the Cover Reports server.
* [**Generate Only**](#generate-reports-bundles) - generate the reports bundle only, no tests created, no upload.
* [**Upload Only**](#upload-reports-bundles) - 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.

{% hint style="info" %}
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.
{% endhint %}

#### Command summary (core options only):

```bash
// 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

For information about integrating Cover Reports into Cover Pipeline please see. [Quick Start - General](/features/cover-pipeline/cover-pipeline-for-ci/quick-start-guide-general.md#integrating-with-diffblue-cover-reports)

***

## Create, Generate, Upload <a href="#create-generate-upload-reports-bundles" id="create-generate-upload-reports-bundles"></a>

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 ).
* Ensure that Diffblue generated tests are correctly tagged, using the latest version of [Cover Annotations](/features/cover-annotations.md) (see [Test Tagging](/features/cover-annotations/test-tagging.md)).
* Build your project.

**Command details:**

Run the following `dcover` command:

```bash
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:

```bash
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"
```

<table><thead><tr><th width="325.58935361216726">Argument</th><th>Description</th></tr></thead><tbody><tr><td><code>--coverage-reports</code></td><td>Generates the reports bundle.</td></tr><tr><td><code>--upload=&#x3C;reports-server></code></td><td>Uploads the reports bundle to the specified Cover Reports server. See your Cover Reports Administrator for details, if needed.</td></tr><tr><td><code>--name=&#x3C;name-of-report></code></td><td>Sets the name of the reports bundle. Replace <code>&#x3C;name-of-report></code> with a useful name. If the <code>--name</code> argument is omitted, the name will default to the current timestamp, or the latest commit hash when used within Git.</td></tr><tr><td><code>--project-name=&#x3C;name-of-project></code></td><td>Sets the specific name of the project to which this reports bundle relates. Replace <code>&#x3C;name-of-project></code> with a useful name. If the <code>--project-name</code> argument is omitted, the project name in Cover Reports will default to the project name defined by the build system, which is recommended.</td></tr><tr><td><code>--location=&#x3C;report-location></code></td><td>Sets the path to the project in Cover Reports. Replace <code>&#x3C;report-location></code> with a useful value, with folder names separated by dots. If the provided location does not exist it will be created. If the <code>--location</code> argument is omitted, the project will be placed in the default location. Project locations can be changed from within Cover Reports at any time.</td></tr><tr><td><p><code>--report-username=&#x3C;username></code></p><p><code>--report-password=&#x3C;password></code></p></td><td>Cover Reports username and password. Used for authenticated uploads only - see <a data-mention href="/pages/COBz23V0HQG7l1PXTZzX">/pages/COBz23V0HQG7l1PXTZzX</a>. The username and password must match those configured by your Cover Reports Administrator.</td></tr><tr><td><code>--class-name-template="${CLASS_NAME}&#x3C;string>"</code></td><td>Used to define a custom test class naming convention to identify tests written by Diffblue Cover. If this argument omitted, the default value of <code>*DiffblueTest</code> will be used</td></tr></tbody></table>

{% hint style="info" %}
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.
{% endhint %}

**Optional JaCoCo arguments:**

<table><thead><tr><th width="325.58935361216726">Argument</th><th>Description</th></tr></thead><tbody><tr><td><code>--jacoco-command-diffblue</code><br><code>=&#x3C;command></code></td><td>Custom command to generate the JaCoCo report for tests written by Diffblue Cover.</td></tr><tr><td><code>--jacoco-command-manual</code><br><code>=&#x3C;command></code></td><td>Custom command to generate the JaCoCo report for manually written tests.</td></tr><tr><td><code>--jacoco-xml-test-report</code><br><code>=&#x3C;jacoco-xml-test-report></code></td><td>Filename and path (including the <code>.xml</code> extension) of the JaCoCo report created using custom commands (as defined above).</td></tr></tbody></table>

**Examples (using default values):**

{% tabs %}
{% tab title="Windows" %}

```
// 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
```

{% endtab %}

{% tab title="Linux/macOS" %}

```
// 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
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Please see --class-name-template in [Commands & Arguments](/features/cover-cli/commands-and-arguments.md) 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
{% endhint %}

***

## Generate Only <a href="#generate-reports-bundles" id="generate-reports-bundles"></a>

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)](/features/cover-reports/cover-reports-contributor/java-project-config.md)).

**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-reports-bundles](#upload-reports-bundles "mention") below.

#### Optional arguments (as detailed in [Commands & Arguments](/features/cover-cli/commands-and-arguments.md)):

<table data-header-hidden><thead><tr><th width="230"></th><th width="267"></th><th width="247"></th></tr></thead><tbody><tr><td><a href="#batch">batch</a></td><td><a href="#build-system-configuration">build-system-configuration</a></td><td><a href="#classpath">classpath</a></td></tr><tr><td><a href="#compliance-level">compliance-level</a></td><td><a href="#define">define</a></td><td><a href="#environment">environment</a></td></tr><tr><td><a href="/pages/ZdPmy6CyXPLH7MPm8dEJ#exclude-modules">exclude-modules</a></td><td><a href="#gradle">gradle</a></td><td><a href="#ignore-stylechecks">ignore-stylechecks</a></td></tr><tr><td><a href="/pages/ZdPmy6CyXPLH7MPm8dEJ#include-modules">include-modules</a></td><td><a href="#maven">maven</a></td><td><a href="#preflight">preflight</a></td></tr><tr><td><a href="/pages/ZdPmy6CyXPLH7MPm8dEJ#strict">strict</a></td><td><a href="#test-framework">test-framework</a></td><td><a href="#verbose">verbose</a></td></tr><tr><td><a href="#working-directory">working-directory</a></td><td></td><td></td></tr></tbody></table>

**Additional JaCoCo arguments:**

<table><thead><tr><th width="325.58935361216726">Argument</th><th>Description</th></tr></thead><tbody><tr><td><code>--jacoco-command-diffblue</code><br><code>=&#x3C;command></code></td><td>Custom command to generate the JaCoCo report for tests written by Diffblue Cover.</td></tr><tr><td><code>--jacoco-command-manual</code><br><code>=&#x3C;command></code></td><td>Custom command to generate the JaCoCo report for manually written tests.</td></tr><tr><td><code>--jacoco-xml-test-report</code><br><code>=&#x3C;jacoco-xml-test-report></code></td><td>Filename and path (including the <code>.xml</code> extension) of the JaCoCo report created using custom commands (as defined above).</td></tr></tbody></table>

**Examples (using default values):**

{% tabs %}
{% tab title="Windows" %}

```
// 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
```

{% endtab %}

{% tab title="Linux/macOS" %}

```
// 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"
```

{% endtab %}
{% endtabs %}

***

## Upload Only <a href="#upload-reports-bundles" id="upload-reports-bundles"></a>

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:

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

For example:

```bash
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"
```

<table><thead><tr><th width="245.19691119691117">Component</th><th>Description</th></tr></thead><tbody><tr><td><p><code>dcover upload</code></p><p><code>&#x3C;reports-server></code></p></td><td>Uploads the reports bundle to the Cover Reports server. Replace <code>&#x3C;reports-server></code> with the URL and port number for your server. See your Cover Reports Administrator for help, if needed.</td></tr><tr><td><code>--name</code><br><code>=&#x3C;name-of-report></code></td><td>Sets the name of the reports bundle. Replace <code>&#x3C;name-of-report></code> with a useful name. If the <code>--name</code> argument is omitted, the name will default to the current timestamp, or the latest commit hash when used within Git.</td></tr><tr><td><code>--project-name=&#x3C;name-of-project></code></td><td>Sets the specific name of the project to which this reports bundle relates. Replace <code>&#x3C;name-of-project></code> with a useful name. If the <code>--project-name</code> argument is omitted, the project name in Cover Reports will default to the project name defined by the build system, which is recommended.</td></tr><tr><td><code>--location=&#x3C;report-location></code></td><td>Sets the path to the project in Cover Reports. Replace <code>&#x3C;report-location></code> with a useful value, with folder names separated by dots. If the provided location does not exist it will be created. If the <code>--location</code> argument is omitted, the project will be placed in the default location. Project locations can be changed from within Cover Reports at any time.</td></tr><tr><td><p><code>--report-username=&#x3C;username></code></p><p><code>--report-password=&#x3C;password></code></p></td><td>Cover Reports username and password, used for authenticated uploads only. The username and password must match those configured by your Cover Reports Administrator.</td></tr></tbody></table>

{% hint style="info" %}
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.
{% endhint %}

#### **Additional o**ptional arguments (as detailed in [Commands & Arguments](/features/cover-cli/commands-and-arguments.md)):

<table data-header-hidden><thead><tr><th width="194"></th><th width="291"></th><th width="247"></th></tr></thead><tbody><tr><td><a href="#batch">batch</a></td><td><a href="#build-system-configuration">build-system-configuration</a></td><td><a href="#classpath">classpath</a></td></tr><tr><td><a href="#define">define</a></td><td><a href="#environment">environment</a></td><td><a href="/pages/ZdPmy6CyXPLH7MPm8dEJ#exclude-modules">exclude-modules</a></td></tr><tr><td><a href="#gradle">gradle</a></td><td><a href="/pages/ZdPmy6CyXPLH7MPm8dEJ#include-modules">include-modules</a></td><td><a href="#maven">maven</a></td></tr><tr><td><a href="#preflight">preflight</a></td><td><a href="#report-file">report-file</a></td><td><a href="/pages/ZdPmy6CyXPLH7MPm8dEJ#strict">strict</a></td></tr><tr><td><a href="#verbose">verbose</a></td><td><a href="#working-directory">working-directory</a></td><td></td></tr></tbody></table>

**Additional JaCoCo arguments:**

<table><thead><tr><th width="295.58935361216726">Argument</th><th>Description</th></tr></thead><tbody><tr><td><p><code>--jacoco-report-diffblue</code></p><p><code>=&#x3C;report></code></p></td><td>Filename and path (including the <code>.xml</code> extension) of the JaCoCo report for Diffblue tests (if a non-standard location is used). Optional.</td></tr><tr><td><p><code>--jacoco-report-manual</code></p><p><code>=&#x3C;report></code></p></td><td>Filename and path (including the <code>.xml</code> extension) of the JaCoCo report for manually written tests (if a non-standard location is used). Optional.</td></tr></tbody></table>

***

## 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-reports-bundles](#generate-reports-bundles "mention") and [#upload-reports-bundles](#upload-reports-bundles "mention").
* **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](/features/cover-reports/cover-reports-contributor/authentication.md) for details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cover-docs-preview.diffblue.com/features/cover-reports/cover-reports-contributor/reports-bundles.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.