Commands & Arguments

Introduction

This topic details the Cover CLI commands and optional arguments.

Create tests

Cover Reports commands

Cover Pipeline commands

Cover Refactor commands

License commands

Command summary

Command	Description
dcover create	Create Tests - write tests for a project, package, method or class. See Create tests.
dcover coverage-reports dcover upload	Cover Reports - create and upload reports bundles for use with Cover Reports. See Cover Reports commands.
dcover ci	Cover Pipeline - run Diffblue Cover in "CI mode" within a CI/CD pipeline. See Cover Pipeline commands.
dcover build	Cover Pipeline - build a Maven or Gradle project using default build commands. See Cover Pipeline commands.
dcover clean dcover validate	Cover Pipeline - remove non-compiling and failing Diffblue tests from your project. See Cover Pipeline commands.
dcover refactor dcover fix-build	Cover Refactor - apply refactorings, identified when running dcover create, to your code base. See Cover Refactor commands.
dcover activate dcover license	Licensing - apply/activate a license and display your current license status. See License commands.
dcover help	Help - get, err, help. Use this with the other commands as well to get some details of what options are available (for example, dcover help create).
dcover version	Check Version - display your Cover CLI version.

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

---

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.

• 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) 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 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).

Argument summary:

active-profiles	allow-jni	annotate-suppress-warnings
batch	build-system-configuration	class-name-template
classpath	compliance-level	cover-all-enums
coverage-reports	define	descriptive-test-names
disable-sandbox	environment	exclude
exclude-modules	gradle	ignore-stylechecks
include-modules	keep-partial-tests	maven
method-name-template	mock	mock-construction
mock-static	no-spring-tests	no-spring-boot-tests
output-comments	patch-only	preflight
refactor	report-file	spring-configuration
spring-integration-tests	strict	test-framework
test-output-dir	validation-command	validation-timeout
verbose	working-directory

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.

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.

Alternative	Main Argument		Alternative	Main Argument
-B	--batch		-cp	--classpath
-d	--test-output-dir		-D	--define
-E	--exclude		-p	--patch-only
-x	--validation-command

---

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.

Go to argument summary table.

---

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.

Go to argument summary table.

---

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. 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"}

Go to argument summary table.

---

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.

Go to argument summary table.

---

build-system-configuration

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.

Go to argument summary table.

---

class-name-template

Windows

Usage: --class-name-template="${CLASS}<string>"

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

Default: ${CLASS}DiffblueTest

Linux/macOS

Usage: --class-name-template=\${CLASS}<string>

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

Default: ${CLASS}DiffblueTest

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.

Go to argument summary table.

---

classpath

Windows

Usage: --classpath="<value>[;<value>...]"

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

Example: --classpath="target/classes;~/.m2/repository/junit/4.12/junit-4.12.jar"

Linux/macOS

Usage: --classpath=<value>[:<value>...]

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

Example: --classpath=target/classes:~/.m2/repository/junit/4.12/junit-4.12.jar

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.

Go to argument summary table.

---

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.

Go to argument summary table.

---

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.

Go to argument summary table.

---

coverage-reports

Usage: --coverage-reports

Description: Generate the reports bundle for Cover Reports - for details, see Cover Reports commands and Generate and upload reports bundles.

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 and Java project config (JaCoCo) for details.

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

Argument	Description
--coverage-reports	Generates the reports bundle.
--upload=<reports-server>	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 Upload Only.
--name=<name-of-report>	Sets the name of the reports bundle. Replace <name-of-report> with a useful name. If the --name argument is omitted, the name will default to the current timestamp, or the latest commit hash when used within Git.
--project-name=<name-of-project>	Sets the specific name of the project to which this reports bundle relates. Replace <name-of-project> with a useful name. If the --project-name argument is omitted, the project name in Cover Reports will default to the project name defined by the build system, which is recommended.
--location=<report-location>	Sets the path to the project in Cover Reports. Replace <report-location> with a useful value, with folder names separated by dots. If the provided location does not exist it will be created. If the --location argument is omitted, the project will be placed in the default location. Project locations can be changed from within Cover Reports at any time.
--report-username=<username> --report-password=<password>	Cover Reports username and password, used for authenticated uploads only. The username and password must match those configured by your Cover Reports Administrator.
--class-name-template="${CLASS_NAME}<string>"	Used to define a custom test class naming convention to identify tests written by Diffblue Cover. If this argument isn't provided, the assumed diffblue class name will default to *DiffblueTest

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.

Syntax summary:

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>

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"

Optional JaCoCo arguments:

Argument	Description
--jacoco-command-diffblue =<command>	Custom command to generate the JaCoCo report for tests written by Diffblue Cover.
--jacoco-command-manual =<command>	Custom command to generate the JaCoCo report for manually written tests.
--jacoco-xml-test-report =<jacoco-xml-test-report>	Filename and path (including the .xml extension) of the JaCoCo report created using custom commands (as defined above).

Go to argument summary table.

---

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 and Building a Gradle project.

• As illustrated in the example above, multiple key/value pairs are specified separately on the command line using individual --define and/or -D arguments.

Go to argument summary table.

---

descriptive-test-names

Usage: --descriptive-test-names

Description: Use descriptive test names to disambiguate similar tests. Requires 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.

Go to argument summary table.

---

disable-sandbox

Usage: --disable-sandbox

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

Use this argument with caution - see below.

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

See Diffblue Sandbox for more details.

Go to argument summary table.

---

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.

Go to argument summary table.

---

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.

• As illustrated in the example above, multiple prefixes are specified separately on the command line using individual --exclude and/or -E arguments.

Go to argument summary table.

---

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 without the leading colon.

Go to argument summary table.

---

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.

Go to argument summary table.

---

ignore-stylechecks

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.

Go to argument summary table.

---

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 without the leading colon.

Go to argument summary table.

---

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

Go to argument summary table.

---

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.

Go to argument summary table.

---

method-name-template

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.

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.

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.

Go to argument summary table.

---

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 for more information on mocking.

Go to argument summary table.

---

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 for more information on mocking.

Go to argument summary table.

---

mock-static

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

Example: --mock=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 for more information on mocking.

Go to argument summary table.

---

no-spring-tests

Usage: --no-spring-tests

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

Go to argument summary table.

---

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.

Go to argument summary table.

---

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.

Go to argument summary table.

---

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

Go to argument summary table.

---

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 customize the commands being used, along with the timeout, by using the --preflight-test-command and --preflight-test-timeout options respectively.

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

Argument	Description
--preflight-test-command =<value>	Custom Maven or Gradle command that runs the tests during preflight checks. Optional.
--preflight-test-timeout =<duration><unit>	Cancel test execution after the specified timeout (default is 30m). Optional.
--preflight-without-tests	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.

Go to argument summary table.

---

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, E013, E027, E052, E053, E066, E086, E118, E119, or E137 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 to perform these actions without creating tests.

See the main Cover Refactor topic for full details and current limitations.

Go to argument summary table.

---

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 or Cover Reports commands).

Note that, in general, there should be no need to change the name of the test-writing summary report.

Go to argument summary table.

---

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.

Go to argument summary table.

---

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 for more details.

Go to argument summary table.

---

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.

Go to argument summary table.

---

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

Go to argument summary table.

---

validation-command

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.

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.

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.

Go to argument summary table.

---

validation-timeout

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.

Go to argument summary table.

---

verbose

Usage: --verbose

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

Go to argument summary table.

---

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.

Go to argument summary table.

---

Cover Reports commands

This topic provides an overview of the Cover Reports commands. For detailed information see Cover Reports Contributor.

Create, Generate, Upload

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

Command details:

Run the following dcover command (core options only are shown - see the dcover create --coverage-reports topic above for details):

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

For example:

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

Generate Only

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

Prerequisites:

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

Command details:

Run the following dcover command:

dcover coverage-reports

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

Inline help: dcover help coverage-reports

Upload Only

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

Command details:

Run the following dcover command (core options only are shown):

dcover upload <reports-server>

For example:

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 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 or Cover Pipeline for GitHub.

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.

Note that dcover ci is currently for use with GitLab and GitHub CI environments only - see Cover Pipeline for GitLab and Cover Pipeline for GitHub.

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 topic above, you can use one or more of the following optional arguments to specify additional Diffblue Cover options.

build-system-configuration	classpath	define
environment	gradle	maven
working-directory

Projects that require a non-standard command line invocation should not use dcover build and should instead build the project before invoking dcover.

Test maintenance (validate & clean)

The validate and clean commands can be used within Cover Pipeline for test maintenance, removing non-compiling and failing Diffblue tests from your project.

Note that dcover validate and dcover clean can technically be used with Cover CLI, but are most useful when applied within a CI environment.

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

batch	build-system-configuration	classpath
class-name-template	compliance-level	define
environment	exclude-modules	gradle
include-modules	maven	preflight
strict	test-output-dir	validation-command
validation-timeout	verbose	working-directory

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

batch	class-name-template	classpath
compliance-level	environment	gradle
maven	method-name-template	preflight
strict	test-output-dir	testing-framework
verbose	working-directory

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

---

Cover Refactor commands

Usage: dcover refactor

Availability: Enterprise Edition customers only.

Inline help: dcover help refactor

Description: Diffblue Cover generates Output Codes 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, E027, E052, E086, E118, E137, E013, E053, E066, and E119 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 for details.

See the main Cover Refactor topic for more details and current limitations.

---

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.

• 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).

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, [e-mail]
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.

---