# Commands & Arguments

## Introduction

This topic details the Cover CLI commands and optional arguments.

<table data-view="cards"><thead><tr><th data-card-target data-type="content-ref"></th><th data-hidden></th><th data-hidden></th><th data-hidden></th><th data-hidden data-card-cover data-type="files"></th></tr></thead><tbody><tr><td><a href="#create-tests">#create-tests</a></td><td></td><td></td><td></td><td></td></tr><tr><td><a href="#cover-reports-commands">#cover-reports-commands</a></td><td></td><td></td><td></td><td></td></tr><tr><td><a href="#cover-pipeline-commands">#cover-pipeline-commands</a></td><td></td><td></td><td></td><td></td></tr><tr><td><a href="#cover-issues-commands">#cover-issues-commands</a></td><td></td><td></td><td></td><td></td></tr><tr><td><a href="#cover-refactor-commands">#cover-refactor-commands</a></td><td></td><td></td><td></td><td></td></tr><tr><td><a href="#license-commands">#license-commands</a></td><td></td><td></td><td></td><td></td></tr></tbody></table>

### Command summary

<table><thead><tr><th width="285.49071125607543">Command</th><th>Description</th></tr></thead><tbody><tr><td><code>dcover create</code></td><td><strong>Create Tests</strong> - write tests for a project, package, method or class. See <a data-mention href="#create-tests">#create-tests</a>.</td></tr><tr><td><p><code>dcover coverage-reports</code></p><p><code>dcover upload</code></p></td><td><strong>Cover Reports</strong> - create and upload reports bundles for use with Cover Reports. See <a data-mention href="#cover-reports-commands">#cover-reports-commands</a>.</td></tr><tr><td><code>dcover ci</code></td><td><strong>Cover Pipeline</strong> - run Diffblue Cover in "CI mode" within a CI/CD pipeline. See <a data-mention href="#cover-pipeline-commands">#cover-pipeline-commands</a>.</td></tr><tr><td><code>dcover build</code></td><td><strong>Cover Pipeline</strong> - build a Maven or Gradle project using default build commands. See <a data-mention href="#cover-pipeline-commands">#cover-pipeline-commands</a>.</td></tr><tr><td><p><code>dcover clean</code></p><p><code>dcover validate</code></p><p><code>dcover remove</code></p></td><td><strong>Cover Pipeline</strong> - remove Diffblue tests from your project. See <a data-mention href="#cover-pipeline-commands">#cover-pipeline-commands</a>.</td></tr><tr><td><p><code>dcover refactor</code></p><p><code>dcover fix-build</code></p></td><td><strong>Cover Refactor</strong> - apply refactorings, identified when running <code>dcover create</code>, to your code base. See <a data-mention href="#cover-refactor-commands">#cover-refactor-commands</a>.</td></tr><tr><td><p><code>dcover activate</code></p><p><code>dcover license</code></p></td><td><strong>Licensing</strong> - apply/activate a license and display your current license status. See <a data-mention href="#license-commands">#license-commands</a>.</td></tr><tr><td><code>dcover help</code></td><td><strong>Help</strong> - get, err, help. Use this with the other commands as well to get some details of what options are available (for example, <code>dcover help create</code>).</td></tr><tr><td><code>dcover version</code></td><td><strong>Check Version</strong> - display your Cover CLI version.</td></tr><tr><td><code>dcover list-modules</code></td><td><strong>List Modules</strong> - display all modules in the project.</td></tr><tr><td><code>dcover issues</code> (Beta)</td><td><strong>Cover Issues</strong> - provides a guided self-serve workflow that enables users to improve the coverage provided by Diffblue Cover. Including prioritised issues list and guidance in the form of LLM prompts to resolve project issues. See <a data-mention href="#cover-issues-commands">#cover-issues-commands</a></td></tr></tbody></table>

### Output Codes

Cover CLI performs a number of checks before, during, and after creating unit tests. Cover can generate a range of output codes during these checks to provide general information and highlight any issues. Details for all output codes are provided in the main [Output Codes](/features/output-codes.md) topic. Note that as and when these output codes are displayed within Cover CLI, additional specifics may also be provided, if relevant. Also, some common issues can be resolved automatically using `dcover refactor` - see [#cover-refactor-commands](#cover-refactor-commands "mention").

***

## Create tests

**Usage:** `dcover create [@<argumentFile>...] [<entryPoint>...] [--<argument>...]`

**Example:** `dcover create @argfile.txt io.corebanking.Account --maven`

**Inline help:** `dcover help create`

**Description:** The `dcover create` command writes tests for your projects, packages, classes, and methods.

* By default, `dcover create` automatically writes tests for the entire project. If required, you can specify what packages, classes, or methods you want to write tests for, on the command line (using `[<entryPoint>...]`) - see [Packages, classes, and methods](/features/cover-cli/commands-and-arguments/packages-classes-and-methods.md).
* You can use one or more optional arguments on the command line to specify additional Diffblue Cover options such as running preflight checks, excluding methods, or uploading reports bundles (using `[--<argument>...]`) - see the [#optional-arguments-dcover-create](#optional-arguments-dcover-create "mention") topic below.
* Command lines can become very long when multiple options are specified. To keep your command lines short and avoid any potential issues with terminals that don't support very long command lines, you can make use of argument files to define your optional arguments (using `[@<argumentFile>...]`) - see [Argument files](/features/cover-cli/commands-and-arguments/argument-files.md) for details.

### Optional arguments (dcover create)

You can use one or more optional arguments to specify additional Diffblue Cover options such as running preflight checks, excluding methods, or uploading reports bundles. Arguments can be provided on the command line or via argument files (see [Argument files](/features/cover-cli/commands-and-arguments/argument-files.md)).

#### Argument summary:

<table data-header-hidden><thead><tr><th width="240"></th><th width="248"></th><th width="247"></th></tr></thead><tbody><tr><td><a href="#active-profiles">active-profiles</a></td><td><a href="#allow-jni">allow-jni</a></td><td><a href="#annotate-suppress-warnings">annotate-suppress-warnings</a></td></tr><tr><td><a href="#batch">batch</a></td><td><a href="#build-system-configuration">build-system-configuration</a></td><td><a href="#class-name-template">class-name-template</a></td></tr><tr><td><a href="#classpath">classpath</a></td><td><a href="#compliance-level">compliance-level</a></td><td><a href="#cover-all-enums">cover-all-enums</a></td></tr><tr><td><a href="#coverage-reports">coverage-reports</a></td><td><a href="#define">define</a></td><td><a href="#descriptive-test-names">descriptive-test-names</a></td></tr><tr><td><a href="#disable-sandbox">disable-sandbox</a></td><td><a href="#environment">environment</a></td><td><a href="#exclude">exclude</a></td></tr><tr><td><a href="#exclude-method">exclude-method</a></td><td><a href="#exclude-modules">exclude-modules</a></td><td><a href="#exclude-trivial-methods">exclude-trivial-methods</a></td></tr><tr><td><a href="#gradle">gradle</a></td><td><a href="#ignore-existing-coverage">ignore-existing-coverage</a></td><td><a href="#ignore-stylechecks">ignore-stylechecks</a></td></tr><tr><td><a href="#include-modules">include-modules</a></td><td><a href="#keep-partial-tests">keep-partial-tests</a></td><td><a href="#maven">maven</a></td></tr><tr><td><a href="#max-assertions-per-test">max-assertions-per-test</a></td><td><a href="#merge">merge</a></td><td><a href="#method-name-template">method-name-template</a></td></tr><tr><td><a href="#mock">mock</a></td><td><a href="#mock-construction">mock-construction</a></td><td><a href="#mock-method-returns">mock-method-returns</a></td></tr><tr><td><a href="#mock-static">mock-static</a></td><td><a href="#new-jacoco-coverage">new-jacoco-coverage</a></td><td><a href="#no-spring-boot-tests-beta">no-spring-boot-tests</a></td></tr><tr><td><a href="#no-spring-tests">no-spring-tests</a></td><td><a href="#output-comments">output-comments</a></td><td><a href="#patch-only">patch-only</a></td></tr><tr><td><a href="#preflight">preflight</a></td><td><a href="#refactor">refactor</a></td><td><a href="#report-file">report-file</a></td></tr><tr><td><a href="#resume-from-module">resume-from-module</a></td><td><a href="#spring-configuration">spring-configuration</a></td><td><a href="#spring-integration-tests">spring-integration-tests</a></td></tr><tr><td><a href="#strict">strict</a></td><td><a href="#test-framework">test-framework</a></td><td><a href="#test-output-dir">test-output-dir</a></td></tr><tr><td><a href="#use-cache">use-cache</a></td><td><a href="#verbose">verbose</a></td><td><a href="#working-directory">working-directory</a></td></tr></tbody></table>

{% hint style="info" %}
A number of additional arguments are designed to be used with the main arguments listed above. These are detailed in the argument descriptions below where appropriate.
{% endhint %}

**Alternative arguments:**

A few arguments are also provided with short alternatives. These are shown in the main argument descriptions in this topic and are summarized here for reference and ease of navigation.

<table><thead><tr><th width="132">Alternative</th><th width="216">Main Argument</th><th width="48"></th><th width="120">Alternative</th><th>Main Argument</th><th data-hidden></th></tr></thead><tbody><tr><td><a href="#batch">-B</a></td><td><a href="#batch">--batch</a></td><td></td><td><a href="#classpath">-cp</a></td><td><a href="#classpath">--classpath</a></td><td></td></tr><tr><td><a href="#test-output-dir">-d</a></td><td><a href="#test-output-dir">--test-output-dir</a></td><td></td><td><a href="#define">-D</a></td><td><a href="#define">--define</a></td><td></td></tr><tr><td><a href="#exclude">-E</a></td><td><a href="#exclude">--exclude</a></td><td></td><td><a href="#patch-only">-p</a></td><td><a href="#patch-only">--patch-only</a></td><td></td></tr><tr><td><a href="#validation-command">-x</a></td><td><a href="#validation-command">--validation-command</a></td><td></td><td></td><td></td><td></td></tr></tbody></table>

***

#### active-profiles

**Usage:** `--active-profiles=<value>[,<value>...]`

**Example:** `--active-profiles=development,test`

**Description:** Used to specify one or more Spring profiles to activate while writing tests. If this option is not used, Cover will automatically use the `test` profile (if available), otherwise the default Spring profile will be used.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### allow-jni

**Usage:** `--allow-jni=<value>[,<value>...]`

**Example:** `--allow-jni=mycustomjni`

**Description:** Use this option to specify any additional Java Native Interface (JNI) library name prefixes that should be usable within the execution sandbox when creating and evaluating tests. JNI library names are the strings supplied in calls to `System.loadLibrary(String)`. By default only JDK provided libraries are allowed.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### annotate-suppress-warnings

**Usage:** `--annotate-suppress-warnings=<value>[,<value>...]`

**Description:** Used to suppress compiler warnings for test methods written by Diffblue Cover. This is especially useful when using SonarQube - see [Using SonarQube with Cover CLI](/features/cover-cli/cover-cli-admin/using-sonarqube-with-cover-cli.md). The `--annotate-suppress-warnings` argument will add the `@SuppressWarnings` code annotation to all test methods written by Diffblue Cover (as detailed below).

**Example - all:** `--annotate-suppress-warnings=all`

Suppresses all warnings - adds the code annotation `@SuppressWarnings({"all"})`\`

**Example - types:** `--annotate-suppress-warnings=unused,raw-types`

Suppresses one or more "warning types" - this example adds the code annotation `@SuppressWarnings({"unused","raw-types"})`

**Example - specific:** `--annotate-suppress-warnings=java:S1161`

Suppresses one or more specific warnings (using warning codes) - this example, adds the code annotation `@SuppressWarnings({"java:S1161"}`

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### batch

**Usage:** `--batch`

**Alternative:** `-B`

**Description:** Used to run `dcover` commands non-interactively within a CI environment, in order not to clutter the CI logs with progress bar output. Note that if you're using Cover Pipeline for GitLab, this option is automatically integrated into the `dcover ci` command.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### build-system-configuration \[deprecated]

**Usage:** `--build-system-configuration=<value>`

**Example:** `--build-system-configuration=~/.m2/settings.xml`

**Description:** Used to specify a custom build system configuration file for `dcover` to use when reading project settings. A common example is a Maven `settings.xml` file.

**Deprecated**: This option should no longer be used: if you want to customize your build system configuration [follow the guidelines here to configure Diffblue Cover to work with your project's build system](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### class-name-template

{% tabs %}
{% tab title="Windows" %}
**Usage:** `--class-name-template="${CLASS}<string>"`

**Example:** `--class-name-template="${CLASS}CreatedTest"`

**Default:** `${CLASS}DiffblueTest`
{% endtab %}

{% tab title="Linux/macOS" %}
**Usage:** `--class-name-template=\${CLASS}<string>`

**Example:** `--class-name-template=\${CLASS}CreatedTest`

**Default:** `${CLASS}DiffblueTest`
{% endtab %}
{% endtabs %}

**Description:** Used to define the test class naming convention for tests written by Diffblue Cover. The `${CLASS}` variable will be substituted with the name of the class under test. If this argument is omitted, the default value `${CLASS}DiffblueTest` will be used.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### classpath

{% tabs %}
{% tab title="Windows" %}
**Usage:** `--classpath="<value>[;<value>...]"`

**Alternative:** `-cp="<value>[;<value>...]"`

**Example:**\
`--classpath="target/classes;~/.m2/repository/junit/4.12/junit-4.12.jar"`
{% endtab %}

{% tab title="Linux/macOS" %}
**Usage:** `--classpath=<value>[:<value>...]`

**Alternatives:** `-cp=<value>[:<value>...]`

**Example:**\
`--classpath=target/classes:~/.m2/repository/junit/4.12/junit-4.12.jar`
{% endtab %}
{% endtabs %}

**Description:** Used to specify the classpath(s) of the project you want to write tests for (a list of directories and JAR archives). Note that by default `dcover` automatically determines the classpaths for your project from Maven or Gradle - for projects where that isn't possible, you can set the classpaths with this argument.

If this argument is used, you must ensure the testing framework, and any other dependencies required to run the project's unit tests, are on the classpath in order for the tests to be validated.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### compliance-level

**Usage:** `--compliance-level=<value>`

**Example:** `--compliance-level=11`

**Description:** Used to specify the Java Compiler Compliance Level (as an integer). Versions 8 to 21 are supported. The default value is `8`.

Note that, in general, `dcover` automatically determines the Java compliance level ("Java version") being used. However, it may be useful to explicitly set the level with this argument. Use this argument if your project is designed to be compiled against a specific Java version other than your default. For example, class files compiled on a newer version of the Java Compiler may not run on older versions of the JVM - this argument can be set to force the compiler to write class files corresponding to the specified Java version.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### cover-all-enums

**Usage:** `--cover-all-enums`

**Description:** If used, `dcover create` will write tests using all possible values for `Enum` types used as a parameter, or write test cases that cause the method-under-test to return all possible values of `Enum` types, even if this provides no additional measured coverage.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### coverage-reports

**Usage:** `--coverage-reports`

**Description:** Generate the reports bundle for Cover Reports - for details, see [#cover-reports-commands](#cover-reports-commands "mention") and [Generate and upload reports bundles](/features/cover-reports/cover-reports-contributor/reports-bundles.md).

{% hint style="info" %}
This option requires an install of Diffblue Cover Reports and also requires JaCoCo to be configured for the project - see [Install and update Cover Reports](/features/cover-reports/cover-reports-administrator/installation.md) and [Java project config (JaCoCo)](/features/cover-reports/cover-reports-contributor/java-project-config.md) for details.
{% endhint %}

The following `dcover create` arguments are specifically designed for use with `--coverage-reports`. This topic provides an overview of the `--coverage-reports` options - for detailed information see the main [Cover Reports Contributor](/features/cover-reports/cover-reports-contributor.md) topics.

<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. Optional - if this argument is omitted the reports bundle will need to be uploaded separately - see <a data-mention href="#upload-reports-bundles">#upload-reports-bundles</a>.</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. 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 isn't provided, the assumed diffblue class name will default to <code>*DiffblueTest</code></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 %}

**Syntax summary:**

```
dcover create
--coverage-reports
--upload=
--name=
--project-name=
--location=
--report-username=
--report-password=
--class-name-template=${CLASS_NAME}
```

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

**Customizing JaCoCo reports**

If you want to customize the JaCoCo reports execution (for example, to use a custom command) [follow the guidelines here to configure Diffblue Cover to work with your project's build system](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

#### Optional JaCoCo arguments \[deprecated]

The following JaCoCo customization options are deprecated and should no longer be used:

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

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### define

**Usage:** `--define=<key=value>`

**Alternative:** `-D=<key=value>`

**Example:** `--define=BUILD=DEBUG`

**Description:** Used to set system properties (key/value pairs) to be applied when running tests.

* In more complex environments (like Spring) system properties are commonly used for configuration.
* User code under test will be executed with the given system properties. These system properties will also be forwarded to your build tool (`Maven`/`Gradle`) during test validation.
* If you're specifying system properties for `dcover` you will need to add those system properties to the test execution configuration of your build script. Otherwise tests created using those system properties will fail.
* For more details on build tool configuration with system properties, see [Building a Maven project](/features/cover-cli/project-configuration/compiling-your-project/building-a-maven-project.md) and [Building a Gradle project](/features/cover-cli/project-configuration/compiling-your-project/building-a-gradle-project.md).
* As illustrated in the example above, multiple key/value pairs are specified separately on the command line using individual `--define` and/or `-D` arguments.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### descriptive-test-names

**Usage:** `--descriptive-test-names`

**Description:** Use descriptive test names to disambiguate similar tests. Requires [method name template](#method-name-template) to include `${GIVEN}`, `${WHEN}`, and/or `${THEN}` replacement tokens.

Descriptive test names are enabled by default but can be disabled by using the `--descriptive-test-names=false` or `--no-descriptive-test-names` options.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### disable-sandbox

**Usage:** `--disable-sandbox`

**Description:** If used, this argument disables the Diffblue sandbox for the methods under test.

{% hint style="warning" %}
Use this argument with caution - see below.
{% endhint %}

Diffblue Cover writes unit tests by running your code thousands of times as it searches for the best tests that achieve maximum coverage and regression detection. By default, your code is run inside a sandbox which blocks calls with potentially disruptive side-effects such as network, file system, or system changes. However, this can also limit the number of tests that Diffblue Cover can write. Disabling the Diffblue sandbox will allow Cover to run all of your code regardless of side-effects, thereby maximizing coverage. Disabling the sandbox must be done with caution as your code may behave in ways you don't expect (e.g. file system modifications).

{% hint style="info" %}
See [Diffblue Sandbox](/features/cover-cli/writing-tests/diffblue-sandbox.md) for more details.
{% endhint %}

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### environment

**Usage:** `--environment=<key=value>`

**Example:** `--environment=BUILD=DEBUG --environment=SPRING_VERSION=5.1`

**Description:** Used to set environment variables (key/value pairs) to be applied when running tests.

* In more complex environments (like Spring) environment variables are commonly used for configuration.
* User code under test will be executed with the given environment variables. These environment variables will also be forwarded to your build tool (`Maven`/`Gradle`) during test validation.
* If you're specifying environment variables for `dcover` you will need to add those environment variables to the test execution configuration of your build script. Otherwise tests created using those environment variables will fail.
* As illustrated in the example above, multiple key/value pairs are specified separately on the command line using individual `--environment` arguments.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### exclude

**Usage:** `--exclude=<entryPointExclusion>`

**Alternative:** `-E=<entryPointExclusion>`

**Examples:**

`--exclude com.x.y.` `-E com.x.y.Foo` `-E com.x.y.Foo.bar:()V`

**Description:** Used to exclude problematic methods from test creation.

* Any test method with a fully-qualified name starting with an exclusion pattern will be excluded.
* The union of methods matched by the arguments is excluded.
* The exclusion argument can be a package name (use trailing `.`) or a fully-qualified class or method name.
* You can specify a trailing method descriptor if you're differentiating between overloaded methods - see [Packages, classes, and methods](/features/cover-cli/commands-and-arguments/packages-classes-and-methods.md).
* As illustrated in the example above, multiple prefixes are specified separately on the command line using individual `--exclude` and/or `-E` arguments.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### exclude-method

**Usage:** `--exclude-method=<methodExclusion>`

**Examples:**

`--exclude-method=com.example.Foo { *bar;}` `--exclude-method=com.example.Baz`

**Description:** Used to specify methods that Diffblue Cover should exclude when writing tests. The generated tests will not contain any calls to methods that match the exclusion pattern, except when the methods are themselves being tested.

* Calls are avoided for any method with a fully-qualified name starting with an exclusion pattern
* Calls are avoided for the union of methods matched by the arguments
* The exclusion argument can be a package name (use trailing `.`), or a fully-qualified class or method name.
* You can specify a trailing method descriptor if you're differentiating between overloaded methods - see [Packages, classes, and methods](/features/cover-cli/commands-and-arguments/packages-classes-and-methods.md).
* As illustrated in the example above, multiple exclusion patterns are specified separately on the command line using individual `--exclude-method`. Only for patterns with **prefix syntax**, multiple exclusion patterns can be specified in a comma separated list argument, for example\
  `--exclude-method=com.example.Baz,com.example.Qux`

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### exclude-modules

**Usage:** `--exclude-modules=<module>[,<module>...]`

**Maven Example:** `--exclude-modules=com.example:resources,com.example:unit-tests`

**Gradle Example:** `--exclude-modules=resources,unit-tests`

**Description:** Used to exclude modules from the command. Module identifiers must exactly match the module identifiers normally listed when running the command without exclusions.

* For Maven modules use the format `$groupId:$artifactId`
* For Gradle projects use the [project path](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html#sec:project_path) without the leading colon.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### exclude-trivial-methods

**Usage:** `--exclude-trivial-methods`

**Description:** Used to exclude trivial methods from test creation. This excludes methods classified as

* ​[T001 - Trivial getter](https://docs.diffblue.com/features/output-codes/t-testability-codes#t001-trivial-getter)​
* ​[T002 - Trivial setter](https://docs.diffblue.com/features/output-codes/t-testability-codes#t002-trivial-setter)​
* ​[T005 - Trivial constructor](https://docs.diffblue.com/features/output-codes/t-testability-codes#t005-trivial-constructor)​
* ​[T020 - Other trivial method](https://docs.diffblue.com/features/output-codes/t-testability-codes#t020-other-trivial-method)​
* ​[T021 - Empty method body](https://docs.diffblue.com/features/output-codes/t-testability-codes#t021-empty-method-body)​

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> ​[Go to argument summary table.](https://cover-docs.diffblue.com/features/cover-cli/commands-and-arguments#argument-summary)​

***

#### gradle

**Usage:** `--gradle`

**Description:** Used to specify Gradle as the preferred build tool for the project. In general, Diffblue Cover will automatically determine the build tool from the project, but in cases where Maven **and** Gradle are available, use this option to specify Gradle.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### ignore-existing-coverage

**Usage:** `--ignore-existing-coverage`

**Description:** Used to suppress Diffblue Cover coverage optimisation, providing the maximum number of tests, even if the tests duplicate coverage already existing within the target test class.

For more information see [Test Coverage Optimizations](/features/cover-cli/writing-tests/test-coverage-optimizations.md)

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### ignore-stylechecks \[deprecated]

**Usage:** `--ignore-stylechecks=<value>`

**Example:** `--ignore-stylechecks=true`

**Default:** `false`

**Description:** Used to suppress known style checking plugins (`checkstyle`, `spring-javaformat`) during test validation (set to `true`) - style checks may prevent compilation or test execution. Currently only supported by `Maven` projects.

**Deprecated**: This option should no longer be used: if you want to customize your build system configuration [follow the guidelines here to configure Diffblue Cover to work with your project's build system](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### include-modules

**Usage:** `--include-modules=<module>[,<module>...]`

**Maven Example:** `--include-modules=com.example:resources,com.example:unit-tests`

**Gradle Example:** `--include-modules=resources,unit-tests`

**Description:** Used to include only specified modules from the command. Module identifiers must exactly match the module identifiers normally listed when running the command without inclusions.

* For Maven modules use the format `$groupId:$artifactId`
* For Gradle projects use the [project path](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html#sec:project_path) without the leading colon.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### keep-partial-tests

**Usage:** `--keep-partial-tests`

**Description:** Used to retain all tests created by Diffblue Cover, including partial tests, tests without assertions, non-compiling tests, non-deterministic tests, tests that result in exceptions, and tests that violate the security policy (sandbox).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### maven

**Usage:** `--maven`

**Description:** Used to specify Maven as the preferred build tool for the project. In general, Diffblue Cover will automatically determine the build tool from the project, but in cases where Maven **and** Gradle are available, use this option to specify Maven.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### max-assertions-per-test

**Usage:** `--max-assertions-per-test=<value>`

**Example:** `--max-assertions-per-test=10`

**Description:** Used to define the maximum number of assertions that can appear in a single generated test case. The minimum allowed value is **1**.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### merge

**Usage:** `--merge`

**Description:** Enables merge mode, where generated tests are merged into existing test classes (e.g., `MyServiceTest.java`) rather than written to separate files (e.g., `MyServiceDiffblueTest.java`).

When `--merge` is enabled:

* The default class name template automatically changes to `${CLASS_NAME}Test`
* Tests are merged into existing test classes, preserving your manual tests
* Requires `cover-annotations` version 1.4.0 or later

{% hint style="info" %}
IntelliJ plugin users can take advantage of merge mode by changing the class name template to match their existing test naming style (e.g., `${CLASS_NAME}Test`) in plugin settings.
{% endhint %}

See [Merge Mode](/features/cover-cli/writing-tests/merge-mode.md) for full documentation.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### method-name-template

{% tabs %}
{% tab title="Windows" %}
**Usage:** `--method-name-template="<string>\<variable>[\<variable>...]"`

**Example:** `--method-name-template="aitest\${INNER}\${METHOD}"`

**Default:** `test${INNER}${UNIT}${_}${GIVEN}${_}${WHEN}${_}${THEN}`

For example, using the default naming convention for the method `something` in inner class `Foo`, the test method will be named `testFooSomething`.
{% endtab %}

{% tab title="Linux/macOS" %}
**Usage:** `--method-name-template=<string>\<variable>[\<variable>...]`

**Example:** `--method-name-template=testCreated\${INNER_CLASS_NAME}\${METHOD_NAME}`

**Default:** `test${INNER_CLASS_NAME}${UNIT_NAME}${_}${GIVEN}${_}${WHEN}${_}${THEN}`

For example, using the default naming convention for the method `something` in inner class `Foo`, the test method will be named `testFooSomething`.
{% endtab %}
{% endtabs %}

**Description:** Used to define the test method naming convention for tests written by Diffblue Cover.

* The `${INNER}` variable will be substituted with the name of the inner class for the method under test. If there's no inner class this will be an empty string.
* The `${UNIT}` variable will usually be substituted with the name of the method under test. Where the unit under test comprises multiple methods (getters and setters, equals and hash code) the more general unit under test name is used.
* `${METHOD}` - substituted with the name of the first method under test, typically the only method under test. To avoid duplication, do not use `${UNIT}` and `${METHOD}` together.
* `${GIVEN}` - substituted with a summary of the conditions before testing, or blank if no summary is available.
* `${WHEN}` - substituted with a summary of the conditions under test, or blank if no summary is available.
* `${THEN}` - substituted with summary of the test's consequences, or blank if no summary is available.
* `${_}` - substituted with an underscore, or blank if there are no values to separate.

The `${GIVEN}` , `${WHEN}` and `${THEN}` summaries target a maximum test method name length of 80 characters, and will be blanked out if method name would exceed that limit.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### mock

**Usage:** `--mock=<value>[,<value>...]`

**Example:** `--mock=io.diffblue.packagetomock,io.diffblue.otherpackage.ClassToMock`

**Description:** Used to define one or more package/class prefixes to mock, using `Mockito.mock()`.

* The class containing the method under test is never mocked.
* Non-void, non-private instance methods are stubbed with `when().thenReturn()`
* The project configuration must contain a test dependency for Mockito.
* See [Mocking using Mockito](/features/cover-cli/project-configuration/mocking.md) for more information on mocking.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### mock-construction

**Usage:** `--mock-construction=<value>[,<value>...]`

**Example:** `--mock-construction=io.diffblue.package.ClassToMock`

**Description:** Used to define one or more fully qualified class names to mock constructors for, using `Mockito.mockConstruction`.

* This feature is available with Mockito 3.5.0 and above, when using the inline mock maker.
* Constructors of the method under test will not be mocked.
* The project configuration must include the `mockito-inline` artifact.
* See [Mocking using Mockito](/features/cover-cli/project-configuration/mocking.md) for more information on mocking.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### mock-method-returns

**Usage:** `--mock-method-returns`

**Description:** Used to instruct Diffblue Cover to be less reluctant to use mocks as return values for mocked methods (e.g. `when(myObj.myMethod()).thenReturn(mock(MyResult.class))`).

* This may improve coverage when there are chains of class dependencies that are difficult to set up without mocking.
* However, it may degrade coverage when setting up dependencies is simple and it's the business logic that is complex.
* If there is no mocking functionality available this flag will have no effect.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### mock-static

**Usage:** `--mock-static=<value>[,<value>...]`

**Example:** `--mock-static=io.diffblue.package.ClassToMock`

**Description:** Used to define one or more fully qualified class names to mock, using `Mockito.mockStatic`.

* This feature is available with Mockito 3.4.0 and above, when using the inline mock maker.
* If the method under test is static, its class will not be mocked.
* The project configuration must include the `mockito-inline` artifact.
* See [Mocking using Mockito](/features/cover-cli/project-configuration/mocking.md) for more information on mocking.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### new-jacoco-coverage

**Usage:** `--new-jacoco-coverage`

**Description:** Diffblue Cover will only add tests that improve JaCoCo coverage. Existing tests are run to produce a JaCoCo report which is used to determine whether a test created by Diffblue Cover adds coverage. Tests created by Diffblue Cover are added if they increase JaCoCo probe coverage ([details in JaCoCo documentation here](https://www.jacoco.org/jacoco/trunk/doc/flow.html)).

* This feature requires Diffblue Cover to be able to run existing tests.
* If used in conjunction with `--coverage-reports` tests are only run a single time.
* This feature relies on JaCoCo coverage to determine whether a test adds coverage. This will cause many tests to be discarded that may be better quality than existing tests, or test other values or edge cases.
* This option will decrease the overlap of Manual and Diffblue coverage but the overall coverage should remain the same. There will still be some overlap as tests created may cover some of the same lines as another existing test, while adding additional coverage elsewhere.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### no-spring-tests

**Usage:** `--no-spring-tests`

**Description:** If used, `dcover` will not use Spring contexts for dependency injection in tests.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### no-spring-boot-tests (Beta)

**Usage:** `--no-spring-boot-tests`

**Description:** If used, `dcover` will not use Spring Boot Tests for dependency injection(`@MockBean)`, instead falling back to other mechanisms such as Mockito's `@InjectMocks` and `@Mock`. This argument may be useful depending on whether or not a Spring context needs to be loaded for a particular unit test suite.

**Note:** This functionality is in Beta stage, hence there could be cases where some inconsistencies and limitations might still be present.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### output-comments

**Usage:** `--output-comments=<value>`

**Example:** `--output-comments=false`

**Default:** `true`

**Description:** Used to suppress the `// Arrange`, `// Act`, and `// Assert` comments in tests written by Diffblue Cover (set to `false`) - see [Test formatting](/features/cover-cli/writing-tests/test-formatting.md).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### patch-only

**Usage:** `--patch-only=<patch-file>`

**Alternative:** `-p=<patch-file>`

**Example:** `--patch-only=path/to/file.patch`

**Description:** If used, Diffblue Cover will only write tests for the code changes defined in the patch file (any class in the patch and any related/dependent classes).

* Use diff or a similar tool to create a patch file for your changes in your project - for example:\
  `git diff origin/develop > file.patch`.
* For a multi-module project, generate the patch at the root of the project and provide the absolute path to the patch file, using `--working-directory` with the relative path to the module. The same patch file can be used for each module.
* For a project without modules, or a project where tests will only ever be created for a single module, where `--working-directory` is not used, the relative path to the patch file for the project or module only may be used - for example:

```
    cd Module
    git diff origin/develop --relative > file.patch
```

* The `--patch-only` argument only accepts files in UTF-8 encoding. If using PowerShell on Windows, use the following command to get the patch in UTF-8 instead of the default UTF-16:

```
    git diff origin/develop | out-file file.patch -encoding utf8
```

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### preflight

**Usage:** `--preflight`

**Description:** Used to run all the project and environment checks that Diffblue Cover usually runs for this command, without executing the full process. For example, `dcover create --preflight` verifies whether the local environment and the project are in the best condition possible for `dcover` to create tests, without actually creating the tests. Similarly, `dcover create --coverage-reports --preflight` performs all checks necessary for creating tests as well as coverage reports.

As part of the preflight checks for `dcover create`, it will run the existing tests and ensure that they compile and run without any problems. This is effectively running `mvn test` or `./gradlew test`, depending on the build system being used. It's possible to modify the commands being used by customizing your build system configuration for Diffblue Cover [following the guidelines here](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

{% hint style="info" %}
The following arguments are specifically designed for use with `dcover create --preflight`. This topic provides an overview of the `--preflight` options - for detailed information see the main [Preflight checks](/features/cover-cli/project-configuration/preflight.md) topic.
{% endhint %}

<table><thead><tr><th width="313.58935361216726">Argument</th><th>Description</th></tr></thead><tbody><tr><td><code>--preflight-without-tests</code></td><td>Disable running existing tests. Note that in general this is not recommended, however this can improve performance times when you already know that the tests compile and run without any issues, or you're focusing attention in other areas.</td></tr></tbody></table>

The following options are deprecated and should no longer be used: you can customize your build system configuration for Diffblue Cover [following the guidelines here](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

<table><thead><tr><th width="313.58935361216726">Argument</th><th>Description</th></tr></thead><tbody><tr><td><p><code>--preflight-test-command</code></p><p><code>=&#x3C;value></code></p></td><td>Custom Maven or Gradle command that runs the tests during preflight checks. Optional.</td></tr><tr><td><p><code>--preflight-test-timeout</code></p><p><code>=&#x3C;duration>&#x3C;unit></code></p></td><td>Cancel test execution after the specified timeout (default is <code>30m</code>). Optional.</td></tr></tbody></table>

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### refactor

**Usage:** `--refactor`

**Alternative:** `--fix-build`

**Availability:** Enterprise Edition customers only.

**Description:** Used to automatically apply refactorings to your project to resolve issues that would otherwise produce [R002](/features/output-codes/r-reason-codes.md), [E013](/features/output-codes/e-environment-codes.md), [E027](/features/output-codes/e-environment-codes.md), [E052](/features/output-codes/e-environment-codes.md), [E053](/features/output-codes/e-environment-codes.md), [E066](/features/output-codes/e-environment-codes.md), [E086](/features/output-codes/e-environment-codes.md), [E118](/features/output-codes/e-environment-codes.md), [E119](/features/output-codes/e-environment-codes.md), or [E137](/features/output-codes/e-environment-codes.md) output codes - this is the core functionality of Cover Refactor. For example, if you have a missing Mockito dependency, the `--refactor` / `--fix-build` option will add the missing dependency to your project for you. Also, see [#cover-refactor-commands](#cover-refactor-commands "mention") to perform these actions without creating tests.

{% hint style="info" %}
See the main [Cover Refactor](/features/cover-refactor.md) topic for full details and current limitations.
{% endhint %}

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### report-file

**Usage:** `--report-file=<reportFile>`

**Example:** `--report-file=mytestreport.json`

**Default:** `.diffblue/reports/report.json`

**Description:** Used to specify a custom filename and path (including the `.json` extension) of the test-writing summary report created when `dcover create` is run. This file also forms part of the Cover Reports bundle (see [#coverage-reports](#coverage-reports "mention") or [#cover-reports-commands](#cover-reports-commands "mention")).

{% hint style="info" %}
Note that, in general, there should be no need to change the name of the test-writing summary report.
{% endhint %}

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### resume-from-module

**Usage:** `--resume-from-module=<module>`

**Maven Example:** `--resume-from-module=com.example:service`

**Gradle Example:** `--resume-from-module=service`

**Description:** Used to resume iteration from the specified module.

* For Maven modules use the format `$groupId:$artifactId`
* For Gradle projects use the [project path](https://docs.gradle.org/current/userguide/intro_multi_project_builds.html#sec:project_path) without the leading colon.

***

#### spring-configuration

**Usage:** `--spring-configuration=<value>[,<value>...]`

**Example:** `--spring-configuration=com.example.MyConfigBean`

**Description:** Used to specify one or more Spring configuration classes to use in tests written by Diffblue Cover.

***

#### spring-integration-tests

**Usage**: `--spring-integration-tests`

**Description:** Used to limit mocking for Spring projects to Repository dependencies only - Spring handles the rest directly. If this argument is not used then mocking may be implemented for a wider scope of dependencies.

* Spring Repositories are classes implementing `org.springframework.data.repository.Repository` or those annotated with `org.springframework.stereotype.Repository`.
* This argument is not applied when creating tests for `@Controller` classes.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### strict

**Usage:** `--strict`

**Description:** Used to force the strict definition of all project environment options set by you - Diffblue Cover will not attempt to make an automated selection. For example, if multiple testing frameworks are configured for your project then running with this option will lead to an error, unless you define which testing framework Cover should use when writing tests. Without this option, Cover would choose one of the testing frameworks for you, and proceed.

See [Operational behaviors](/features/cover-cli/writing-tests/operational-behaviors.md) for more details.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### test-framework

**Usage:** `--test-framework=<framework-and-version>`

**Example:** `--test-framework=junit-5` or `--test-framework=testng-7.8`

**Description:** Used to specify the test framework and version to use for writing tests.

By default `dcover` automatically determines which test framework (JUnit or TestNG) and version is used by your project. The `--test-framework` argument is used to specify which framework and version to use, especially useful if multiple frameworks or versions are used by your project. The supported values for this option are as follows:

* **JUnit:** Valid versions from `junit-4.11` to `junit-5.10` (including, in particular, `junit-4.13` as a special case for JUnit 4.13 support), and the special values `junit-4` (any JUnit 4), `junit-5` (any JUnit 5 or later).
* **TestNG:** Valid versions from `testng-6.0.1` to `testng-7.8`, or the special value `testng` (any TestNG).

If you use this option, the classpath will be checked to see if that framework is available. If there is a mismatch between versions, `dcover` will produce an error.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### test-output-dir

**Usage:** `--test-output-dir=<relativePath>`

**Alternative:** `-d=<relativePath>`

**Default:** `src/test/java`

**Example:** `--test-output-dir=src/test/diffblue`

**Description:** Used to specify the directory to write Diffblue tests to (relative to the working directory).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### use-cache

**Usage:** `--use-cache`

**Alternative:** `--cache`

**Default:** `false`

**Description:** Used to allow reuse of cached environment checks to increase the speed of subsequent `dcover` executions. Applicable to all commands that have an environment detection phase (e.g. `build`, `clean`, `coverage`, `create`, `issues`, `optimize` , etc.).\
**Note:** The cache will disabled when run using the `ci` command.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### validation-command \[deprecated]

**Usage:** `--validation-command="<value>"`

**Alternative:** `-x="<value>"`

**Default:** `mvn test` (Maven projects), `gradle test` (Gradle projects)

**Example:** `--validation-command="mvn test"`

**Description:** Used to specify a custom Maven or Gradle test command to validate tests written by Diffblue Cover (during this run of `dcover create`). Note that on multi-module projects this custom validation command will be run on each module.

**Deprecated**: This option should no longer be used: if you want to customize your build system configuration [follow the guidelines here to configure Diffblue Cover to work with your project's build system](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

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

* The command must be a standard Maven command to which the `-Dtest` option can be appended. The command should not already contain `-Dtest`.
* If `dcover create` is run from the root of a multi-module project, using `--working-directory`, there is no need to include the `--file` (or `-f`) option to the validation command. The validation command will be run from the directory specified in `--working-directory`.
* If no command is provided, `mvn test` is run if `dcover` detects a `pom.xml` file in the working directory. If the command fails for a certain test method, `dcover` will revert the entire test class containing that method.
* The given command is executed after tests have been written, to make sure they don't break the build. Tests are removed if it returns a non-zero exit value.
* All existing tests should pass the validation command before `dcover` is invoked - there should be no pre-existing compilation or test failures.
  {% endtab %}

{% tab title="Gradle" %}

* The command must be a standard Gradle command invoking a `Test` task, which will produce JUnit XML reports, and to which the `--tests` option can be appended.
* The command must not already contain the `--tests` option.
* The command must have info logging enabled (for test validation to work correctly). This can be done by adding `-i`/`--info` to the command.
* If no command is provided, `gradle test` is run if `dcover` detects a Gradle project in the working directory. If the command fails for a certain test method, `dcover` will revert the entire test class containing that method.
* The given command is executed after tests have been written, to make sure they don't break the build. Tests are removed if it returns a non-zero exit value.
* All existing tests should pass the validation command before `dcover` is invoked - there should be no pre-existing compilation or test failures.
  {% endtab %}
  {% endtabs %}

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### validation-timeout \[deprecated]

**Usage:** `--validation-timeout=<duration>`

**Example:** `--validation-timeout=1h`

**Default:** `30m`

**Description:** Used to specify a timeout for test validation.

By default, when tests are written by Diffblue Cover they're validated to make sure they compile and run successfully. This option can be used to specify how long test validation can take before being cancelled.

Supported values:

* The `<duration>` must be a positive integer followed by a `<unit>` suffix: `h` (hours), `m` (minutes), or `s` (seconds).
* If you use a `<duration>` of zero (`0`), no suffix, the test validation will not time out.

**Deprecated**: This option should no longer be used: if you want to customize your build system configuration [follow the guidelines here to configure Diffblue Cover to work with your project's build system](/features/cover-cli/project-configuration/configuring-cover-to-work-with-your-projects-build-system.md).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### verbose

**Usage:** `--verbose`

**Description:** Used to generate more detailed log messages about the test writing process.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

#### working-directory

**Usage:** `--working-directory=<directory>`

**Example:** `--working-directory=path/to/module`

**Description:** Used to set the working directory for running `dcover`, enabling you to run `dcover` for a particular module, for example, from the root of a project.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#argument-summary)

***

## Cover Reports commands

{% hint style="info" %}
This topic provides an overview of the Cover Reports commands. For detailed information see [Cover Reports Contributor](/features/cover-reports/cover-reports-contributor.md).
{% endhint %}

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

Create tests, generate the reports bundle, and upload the bundle to the Cover Reports server.

**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 (core options only are shown - see the [dcover create --coverage-reports](#coverage-reports) topic above for details):

```bash
dcover create
--coverage-reports
--upload=<reports-server>
```

For example:

```bash
dcover create
--coverage-reports
--upload=http://cover-reports-service:8080
```

### 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.

**Inline help:** `dcover help coverage-reports`

### 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 (core options only are shown):

```bash
dcover upload <reports-server>
```

For example:

```bash
dcover upload http://cover-reports-service:8080
```

**Inline help:** `dcover help upload`

***

## Cover Pipeline commands

This topic provides details of the commands specific to Cover Pipeline - see [Cover Pipeline](/features/cover-pipeline.md) for information on using Diffblue Cover within your CI environment.

### Enable CI

**Usage:** `dcover ci`

**Description:** The `dcover ci` command enables Diffblue Cover to operate within a CI (Continuous Integration) environment. The behavior of `dcover ci` is as follows:

1. Prepares the CI environment.
2. Runs further `dcover` commands in sequence, as specified within your pipeline - for details, see see [Cover Pipeline for GitLab](/features/cover-pipeline/cover-pipeline-for-gitlab.md) or [Cover Pipeline for GitHub](/features/cover-pipeline/cover-pipeline-for-github.md).
3. Pushes any changes made by Diffblue Cover back into the CI environment. In order to ensure that work is not lost, changes are pushed back even if intervening commands fail.

{% hint style="info" %}
Note that `dcover ci` is currently for use with GitLab and GitHub CI environments only - see [Cover Pipeline for GitLab](/features/cover-pipeline/cover-pipeline-for-gitlab.md) and [Cover Pipeline for GitHub](/features/cover-pipeline/cover-pipeline-for-github.md).
{% endhint %}

### Build Project

**Usage:** `dcover build`

**Description:** The `dcover build` command builds a Maven or Gradle project using default build commands. This can be useful in CI environments to ensure that the dependencies have been downloaded and the project compiles, so that further commands can analyze the bytecode. Specifically, the default commands are run, with tests disabled and multi-threading enabled:

* **Maven:** `mvn install -DskipTests --threads=1C`
* **Gradle:** `gradle build -x test`

As detailed in the [#create-tests](#create-tests "mention") topic above, you can use one or more of the following optional arguments to specify additional Diffblue Cover options.

<table data-header-hidden><thead><tr><th width="283"></th><th width="185"></th><th width="172"></th></tr></thead><tbody><tr><td><a href="#build-system-configuration">build-system-configuration</a></td><td><a href="#classpath">classpath</a></td><td><a href="#define">define</a></td></tr><tr><td><a href="#environment">environment</a></td><td><a href="#gradle">gradle</a></td><td><a href="#maven">maven</a></td></tr><tr><td><a href="#working-directory">working-directory</a></td><td></td><td></td></tr></tbody></table>

{% hint style="info" %}
Projects that require a non-standard command line invocation should not use `dcover build` and should instead build the project before invoking `dcover`.
{% endhint %}

### List modules

**Usage:** `dcover list-modules`

**Description:** The `dcover list-modules` command displays all modules in a Maven or Gradle project. This is useful for identifying the structure of a multi-module project.

As detailed in the [#create-tests](#create-tests "mention") topic above, you can use one or more of the following optional arguments to specify additional Diffblue Cover options.

**Inline help:** `dcover help list-modules`

<table data-header-hidden><thead><tr><th width="283"></th><th width="185"></th><th width="172"></th></tr></thead><tbody><tr><td><a href="#classpath">classpath</a></td><td><a href="#define">define</a></td><td><a href="#environment">environment</a></td></tr><tr><td><a href="#gradle">gradle</a></td><td><a href="#maven">maven</a></td><td><a href="#working-directory">working-directory</a></td></tr></tbody></table>

### Test maintenance (validate, clean & remove)

The `validate` , `clean` and `remove` commands can be used within Cover Pipeline or Cover CLI for test maintenance. For clarification of what Diffblue Tests these commands operate on, please see [Test Tagging](/features/cover-annotations/test-tagging.md).

{% hint style="info" %}
Note that `dcover validate` and `dcover clean` can technically be used with Cover CLI, but are most useful when applied within a CI environment.
{% endhint %}

#### The validate command

**Usage:** `dcover validate`

**Description:** The `dcover validate` command validates tests written by Diffblue Cover and removes any non-compiling and failing Diffblue Cover tests (usually due to changes in the project).

* `dcover validate` automatically works across the entire project.
* As detailed in the [#create-tests](#create-tests "mention") topic above, you can use one or more of the following optional arguments to specify additional Diffblue Cover options such as running preflight checks, or specifying the Maven/Gradle validation command to use.

<table data-header-hidden><thead><tr><th width="231"></th><th width="256"></th><th width="208"></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="#class-name-template">class-name-template</a></td><td><a href="#compliance-level">compliance-level</a></td><td><a href="#define">define</a></td></tr><tr><td><a href="#environment">environment</a></td><td><a href="#exclude-modules">exclude-modules</a></td><td><a href="#gradle">gradle</a></td></tr><tr><td><a href="#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="#strict">strict</a></td><td><a href="#test-output-dir">test-output-dir</a></td><td><a href="#validation-command">validation-command</a></td></tr><tr><td><a href="#validation-timeout">validation-timeout</a></td><td><a href="#verbose">verbose</a></td><td><a href="#working-directory">working-directory</a></td></tr></tbody></table>

#### The clean command

**Usage:** `dcover clean`

**Description:** The `dcover clean` command removes test methods written by Diffblue Cover that no longer compile (usually due to changes in the project).

* `dcover clean` automatically works across the entire project.
* As detailed in the [#create-tests](#create-tests "mention") topic above, you can use one or more of the following optional arguments to specify additional Diffblue Cover options such as running preflight checks, or specifying a test output directory.

<table data-header-hidden><thead><tr><th width="227"></th><th width="240"></th><th width="219"></th></tr></thead><tbody><tr><td><a href="#batch">batch</a></td><td><a href="#class-name-template">class-name-template</a></td><td><a href="#classpath">classpath</a></td></tr><tr><td><a href="#compliance-level">compliance-level</a></td><td><a href="#environment">environment</a></td><td><a href="#gradle">gradle</a></td></tr><tr><td><a href="#maven">maven</a></td><td><a href="#method-name-template">method-name-template</a></td><td><a href="#preflight">preflight</a></td></tr><tr><td><a href="#strict">strict</a></td><td><a href="#test-output-dir">test-output-dir</a></td><td><a href="#testing-framework">testing-framework</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>

* Also, you can use the `test-classes-dir` optional argument (specific to `dcover clean`) to define the directory where created tests are compiled. This is necessary if the directory is different than the build system default.
  * **Usage:** `--test-classes-dir="target/different-test-classes-directory"`
  * **Default:** Determined by build system.

#### The remove command

**Usage:** `dcover remove`

**Description:** The `dcover remove` command removes all test methods written by Diffblue Cover. This can be useful if you want to move where Diffblue tests are stored.

* `dcover remove` automatically works across the entire project.
* As detailed in the [#create-tests](#create-tests "mention") topic above, you can use one or more of the following optional arguments to specify additional Diffblue Cover options such as running preflight checks, or specifying a test output directory.

| [class-name-template](#class-name-template) | [classpath](#classpath)             | [environment](#environment)               |
| ------------------------------------------- | ----------------------------------- | ----------------------------------------- |
| [exclude-modules](#exclude-modules)         | [include-modules](#include-modules) | [resume-from-module](#resume-from-module) |
| [test-output-dir](#test-output-dir)         | [verbose](#verbose)                 | [working-directory](#working-directory)   |

**Note:** The `dcover remove` command does not remove the compiled .class files associated with our generated tests. To remove .class files please rebuild the project.

***

## Cover Issues commands (Beta) <a href="#cover-issues-commands" id="cover-issues-commands"></a>

**Usage:** `dcover issues`

**Description:** Diffblue Cover generates [Output Codes](/features/output-codes.md) when running `dcover create`. Each of these output codes identifies a potential issue with your environment or your code base. `dcover issues` provides a prioritised list of issues to be addressed, enabling users to enable Diffblue Cover to increase its test coverage levels. The output of `dcover issues` includes output codes, methods affected and can provide copy-pastable prompts which are designed to be implemented by an LLM coding agent, allowing subsequent runs of `dcover create` to improve coverage.

By default the `dcover issues` output for `--details` and `--prompts` is limited to 10 (prioritised) issues.

### Optional arguments (dcover issues)

You can use one or more optional arguments to specify additional Diffblue Cover options to fine tune the output of `dcover issues`

#### Argument summary:

| [details](#details)           | [limit](#limit) | [prompt](#prompts) |
| ----------------------------- | --------------- | ------------------ |
| [report-file](#report-file-1) |                 |                    |

***

#### details (Beta)

**Usage:** `--details`

**Description:** This option includes the messages associated with each output code, giving the user more information about each problem (such as stack traces).

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#optional-arguments-dcover-issues)

***

#### limit (Beta)

**Usage:** `--limit`

**Example:** `--limit=25`

**Description:** This option limits the number of entries displayed within the `dcover issues` output. When using `--details` or `--prompts` arguments, a limit of 10 is applied by default to help with readability.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#optional-arguments-dcover-issues)

***

#### prompts (Beta)

**Usage:** `--prompts`

**Description:** This option provides copy-pastable prompts which are designed to be implemented by a LLM coding agent, allowing subsequent runs of `dcover create` to improve coverage.

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#optional-arguments-dcover-issues)

***

#### report-file

**Usage:** `--report-file`

**Description:** `dcover issues` uses the report.json file created by the `dcover create` command as a basis of its output. If you require to store a issues list and utilise it later, possibly after running a new `dcover create` in between, or running `dcover coverage-reports`, then please store the report.json file with a specific timestamp. Please use `--report-file` command to specify a non-default report.json file.

For more details see the definition here [#report-file](#report-file "mention")

<img src="/files/fZZAaCa0S4plXPYkYKv6" alt="" data-size="line"> [Go to argument summary table.](#optional-arguments-dcover-issues)

***

## Cover Refactor commands

**Usage:** `dcover refactor`

**Availability:** Enterprise Edition customers only.

**Inline help:** `dcover help refactor`

**Description:** Diffblue Cover generates [Output Codes](/features/output-codes.md) when running `dcover create`. Each of these output codes identifies a potential issue with your environment or your code base, which could potentially be fixed automatically using `dcover refactor` (the core Cover Refactor command). The `dcover refactor` command can be used to automatically resolve [R002](/features/output-codes/r-reason-codes.md), [E027](/features/output-codes/e-environment-codes.md), [E052](/features/output-codes/e-environment-codes.md), [E086](/features/output-codes/e-environment-codes.md), [E118](/features/output-codes/e-environment-codes.md), [E137](/features/output-codes/e-environment-codes.md), [E013](/features/output-codes/e-environment-codes.md), [E053](/features/output-codes/e-environment-codes.md), [E066](/features/output-codes/e-environment-codes.md), and [E119](/features/output-codes/e-environment-codes.md) output codes.

1. When running `dcover create` on a module, a `refactorings.yml` file is stored in the `.diffblue` directory of the module. This file contains a description of the refactorings that Cover Refactor can perform on your code base.
2. Running `dcover refactor` applies these refactorings to your code base. You can view the code changes performed by Cover Refactor using `git diff` or similar, and then commit them to your code base when you're happy.
3. If you run `dcover create` again, after recompiling your project, Diffblue Cover will take the refactorings into account, potentially producing more and better tests for your code base.

**Note:** Steps 1 and 2 can be performed jointly using `dcover create --refactor` - see [#refactor](#refactor "mention") for details.

{% hint style="info" %}
See the main [Cover Refactor](/features/cover-refactor.md) topic for more details and current limitations.
{% endhint %}

***

## License commands

### Activate/apply a license

**Usage:** `dcover activate $LICENSE` or `dcover activate <license-key>`

**Description:** Diffblue Cover requires a remote license check with the Diffblue licensing server each time it's used. For help troubleshooting license keys, network connections, and proxy server settings, as well as details of offline licensing (Enterprise Edition only), see [Licensing](/get-started/licensing.md).

* To activate your license, you can create a `$LICENSE` environment variable using your Diffblue Cover license key as the value, and use the `dcover activate $LICENSE` command. Alternatively, use the `dcover activate <license-key>` command, and replace `<license-key>` on the command line with your Diffblue Cover license key.
* Entering multiple different license keys will overwrite the existing key.
* You can check your license status by running the `dcover license` command ([see below](#view-license-details)).

When you activate a license you'll see a summary of the license details on the console:

```
❯ dcover activate $LICENSE
INFO  Diffblue Cover 2023.07.01-327525f
INFO  Successfully activated key $LICENSE
INFO
INFO  License type: Enterprise Edition
INFO  License key: $LICENSE
INFO  License registered to: John Smith, john.smith@example.com
INFO  Available features:
INFO    Feature Batch Mode is neither time nor consumption limited
INFO    Feature CLI is neither time nor consumption limited
INFO    Feature Test Creation is neither time nor consumption limited
INFO    Feature Patch Mode is neither time nor consumption limited
INFO    Feature Plugin is neither time nor consumption limited
INFO    Feature Replay is neither time nor consumption limited
INFO    Feature JSON Report is neither time nor consumption limited
INFO    Feature Cover Reports is neither time nor consumption limited
INFO
INFO  To start, run "dcover create" in a module of your project, giving it the
INFO  fully-qualified name of a package, class, or method.
INFO
INFO  For example:
INFO    dcover create com.example.
INFO    dcover create com.example.FooClass
INFO    dcover create com.example.FooClass.method
INFO
INFO  For help with running dcover commands, "dcover help" will show you all
INFO  the commands and optional arguments, "dcover help create" will show you
INFO  help specific to the "create" command.
INFO
INFO  For Getting Started information, see:
INFO  https://docs.diffblue.com/get-started/
```

### View license details

**Usage:** `dcover license`

**Description:** To view your license details (type, key, owner, limitations, etc - as illustrated above), run the `dcover license` command.

***


---

# 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-cli/commands-and-arguments.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.