Links

Commands & Arguments

Introduction

This topic details the Cover CLI commands and optional arguments.

Command summary

Command
Description
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 activate
dcover license
Licensing - apply/activate a license and display your current license status. See License commands.
dcover version
Check Version - display your Cover CLI version.
dcover create
Create Tests - write tests for a project, package, method or class. See the-create-command.
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 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.

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
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 (for example, dcover create io.corebanking.Account - see Packages, classes, and methods.
  • 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 - see Optional arguments below.

Optional arguments (dcover create)

This is a list of the most common options - to see the full list of available options run dcover help create.
Command lines can become very long when multiple options are specified on the command line. 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 - see Argument files for details.

active-profiles

Usage: --active-profiles
Example: --active-profiles=development, --active-profiles=development,test
Use this option to specify any Spring profiles to activate while writing tests. You can specify multiple profiles by giving a comma separated list of profiles. By default, or if you do not specify this option, the default Spring profile will be used. Please see Spring profiles for further details.

allow-jni

Usage: --allow-jni
Example: --allow-jni=mycustomjni, --allow-jni=jna
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.

annotate-suppress-warnings

Usage: --annotate-suppress-warnings
A simple way to turn off the warnings given by SonarQube is to use the --annotate-suppress-warnings option to add the @SuppressWarnings code annotation to all test methods written by Diffblue Cover.
Example: --annotate-suppress-warnings=all suppresses all SonarQube warnings by producing the code annotation: @SuppressWarnings({"all"})`
If you want to turn off a specific warning, you can use the warning code to do this. For example, to suppress warning java:S1161, enter the following:
--annotate-suppress-warnings=java:S1161

batch

Usage: --batch
Use this option to run dcover 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.

build-system-configuration

Usage: --build-system-configuration
Example: --build-system-configuration=~/.m2/settings.xml
Use this option if you want dcover to use a custom configuration file when interacting with the Maven build tool.

class-name-template

Usage: --class-name-template
Example: --class-name-template=\${CLASS_NAME}Test
Default: --class-name-template=\${CLASS_NAME}DiffblueTest
Specifies how to name the test class files that are created. The variable ${CLASS_NAME} will be substituted with the name of the class under test. The $ must be escaped.
For example, with the argument given above, and a class name Foo, the name of the class file created will be FooTest.java. If this argument is specified without the variable ${CLASS_NAME}, all of the tests will be put into one file named by the string in the argument.

classpath

Usage: --classpath or -cp
By default dcover automatically determines the classpath for your project from Maven or Gradle. For projects where that isn't possible, you can set the classpath with this option. For example:
-cp "target/classes:~/.m2/repository/junit/junit/4.12/junit-4.12.jar"
Provide the classpath(s) of the project you want to write tests for. Multiple paths can be specified using : as separators for Linux/macOS and ; for Windows. jar files can also be added to the classpath as shown above.
Please note that on Windows the classpath argument -cp must be wrapped in double quotes.
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.

compliance-level

By default, dcover automatically determines the Java compliance level ("Java version") being used. You can set it explicitly with this option.
Usage: --compliance-level
Example: --compliance-level=[3-13], default: --compliance-level=8
Specifies the Java Compiler Compliance Level (as an integer). Versions 3 to 13 are supported. The default value is 8.
Class files compiled on a newer version of the Java Compiler may not run on older versions of the JVM. This flag can be set to force the compiler to write class files corresponding to the specified Java version.
Use this argument if your project is designed to be compiled against a specific Java version other than your default.

cover-all-enums

Usage: --cover-all-enums
If specified, dcover will attempt to write tests using all possible values for Enum types used as a parameter, or to write test cases that cause the method-under-test to return all possible values of Enums (this will happen even if this provides no additional measured coverage).

coverage-reports

Usage: --coverage-reports
Generate the reports bundle for Cover Reports - for details, see Cover Reports commands and Generate and upload reports bundles.
Note that this option requires having JaCoCo set up in the project.
The JaCoCo command that is run by dcover can be configured using the --jacoco-command-manual and --jacoco-command-diffblue options which should run the non-Diffblue tests and the Diffblue tests, respectively.
Both Maven and Gradle are supported.

define

Usage: --define or -D
Examples: --Dkey1=value1 --Dkey2=value2 -Dkey3=value3
Define system properties for this dcover execution.
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.
Note: 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.

disable-mock-inputs

Usage: --disable-mock-inputs
If specified, dcover will not attempt to create mock objects for use as input parameters. Specifying this option does not affect the creation of mock objects as specified by the mock option.

disable-sandbox

Usage: --disable-sandbox or --disable-security-policy
Uses a more permissive security manager policy for the methods under test. Use with caution! This option allows execution of potentially unsafe code during test creation, which may change the file system. Existing files will not be changed or deleted, but new files may be created. See Diffblue Sandbox for more details.

environment

Usage: --environment
Example: --environment KEY=VALUE
Define additional environment variables for this dcover execution.
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.
Note: 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.

exclude

Usage: --exclude or -E
Examples:
--exclude com.x.y. --exclude com.x.y.Foo --exclude com.x.y.Foo.bar:()V
For excluding 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 from the set of included methods.
The exclusion argument may be a package name (use trailing .) or a fully-qualified class or method name. You may specify a trailing method signature if differentiating between overloaded methods.

existing-coverage

Usage: --existing-coverage or -e
Example: --existing-coverage=target/jacoco.exec
Takes a path to a JaCoCo coverage report as an argument (target/jacoco.exec in this example), so that dcover will write tests only for those lines of code which are not already covered by existing tests.
Note:

gradle

Usage: --gradle
For cases where you prefer which tool is used, this option tells Cover to use Gradle.

ignore-stylechecks

Usage: --ignore-stylechecks
Example: --ignore-stylechecks=true, default: --ignore-stylechecks=false
When set, dcover will suppress known style checking plugins (checkstyle, spring-javaformat) during test validation - style checks may prevent compilation or test execution. Currently only supported by Maven projects.

jacoco-command-diffblue

Usage: --jacoco-command-diffblue
Examples:
--jacoco-command-diffblue "mvn clean test jacoco:report -Dtest='*DiffblueTest.java'"
--jacoco-command-diffblue "./gradlew test --tests=*DiffblueTest.java"
Default for Maven:
mvn clean test jacoco:report -Dtest='*DiffblueTest.java'
Default for Gradle:
./gradlew test --tests=*DiffblueTest.java
When run with --coverage-reports, sets the JaCoCo command to run to produce the JaCoCo report for the Diffblue tests.
Care must be taken when supplying the arguments on Windows for the Gradle command. Gradle interprets the value after --tests literally, if you include quotes, for example, it'll include the quotes too. If you find that the Gradle execution fails, you can add --info and --debug to the command to help. You will see the Gradle output in the Cover log file.

jacoco-command-manual

Usage: --jacoco-command-manual
Examples:
--jacoco-command-manual "mvn clean test jacoco:report -Dtest='!*DiffblueTest.java'"
--jacoco-command-manual "./gradlew clean test --tests=!*DiffblueTest.java"
Default for Maven:
mvn clean test jacoco:report -Dtest='!*DiffblueTest.java'
When run with --coverage-reports, sets the JaCoCo command to run to produce the JaCoCo report for the manual (non-Diffblue) tests.
Default for Gradle:
"./gradlew clean test --tests=!*DiffblueTest.java"
Care must be taken when supplying the arguments on Windows for the Gradle command. Gradle interprets the value after --tests literally, if you include quotes, for example, it'll include the quotes too. If you find that the Gradle execution fails, you can add --info and --debug to the command to help. You will see the Gradle output in the Cover log file.

maven

Usage: --maven
For cases where you prefer which tool is used, this option tells Cover to use Maven.

max-class-length

Usage: --max-class-length
Example: --max-class-length=10000
Allows you to exclude overly long and slow methods from automatic test creation by specifying a maximum java file size (total lines of code). Java files larger than this will not have any tests written for any methods inside them, or any inner classes. The number of lines of code is considered to be the line number of the last functional line in the file (i.e. method lines, ignoring things like whitespace or a closing “}”).
This option is especially useful where third party code conversion tools have generated large class files which are not idiomatic of developer written code.

merge

Usage: --merge
Example: --merge=true
Default: --merge=false
If enabled and the .java test file already exists, the created tests are inserted into the appropriate file. If the file already contains tests for the same method, then the existing tests will be kept and therefore the file will contain both the existing and newly-created tests.
If disabled, any existing .java test file will be overwritten and contain only the newly-created tests.

method-name-template

Usage: --method-name-template
Default: test\${INNER_CLASS_NAME}$\${METHOD_NAME}
Example: testCreated\${INNER_CLASS_NAME}\${METHOD_NAME}
Specifies how to name the test methods that are created. The variable ${METHOD_NAME} will be substituted with the name of the method under test. Similar to --class-name-template.

mock

Usage: --mock
Example: --mock io.diffblue.packagetomock io.diffblue.otherpackage.ClassToMock
dcover will mock classes that match the given prefixes using Mockito. Non-void, non-private instance methods are stubbed with when().thenReturn(). The class containing the method for which the tests are being created will not be mocked. The project configuration must contain a test dependency for Mockito.

no-spring-tests

Usage: --no-spring-tests
If used, dcover will not use Spring contexts for dependency injection in tests.

patch-only

Usage: --patch-only or -p
Example: --patch-only=path/to/patch-file
By specifying a patch file, it is possible to create tests only for the code changes affected by the patch, i.e. classes in the patch or classes that call a class in the patch.
Use diff or a similar tool to create a patch file for your changes in your project, e.g. 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, e.g.
cd Module
git diff origin/develop --relative > file.patch
--patch-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

preflight

Usage: --preflight
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. For further information, see Preflight checks.

refactor

Usage: --refactor or --fix-build
If test creation fails due to build issues (currently limited to R002, E027, E052, E086, E118, or E137 output codes), including this option will instruct Diffblue Cover to attempt to fix those issues. For example, if you have a missing Mockito dependency, the refactor and fix-build options will add the missing dependency to your project for you. Also, see Cover Refactor commands to perform these actions without creating tests.

skip-if-service-out-of-resources

Usage: --skip-if-service-out-of-resources
If the analysis of a method fails due to the analysis service running out of resources, skip the remaining methods in the class with a status of R025 (Skipped due to previous failure).

skip-test-validation

Usage: --skip-test-validation
By default, created tests are compiled and executed to make sure they are correct, and only those which succeed will be kept. Sometimes this results in all the tests being deleted due to style checks failing (see ignore-stylechecks above) and it increases test creation time, so it may be desirable to skip validation via this option. For test validation to work, JUnit must be on the classpath. Normally dcover automatically takes care of this, but if you're using a manual classpath, don't forget to add it.

spring-integration-tests

Usage: --spring-integration-tests
Tests created for Spring components will use mocking only for Repository dependencies. All other dependencies will be resolved by Spring directly. Not applied when creating tests for @Controller classes.
Spring Repositories are classes implementing org.springframework.data.repository.Repository or those annotated with org.springframework.stereotype.Repository.

strict

Usage: --strict
Forces 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.

test-output-dir

Usage: --test-output-dir or -d
Default: src/test/java
Example: --test-output-dir=src/test/diffblue
Location for the created tests relative to the working directory. Provide the relative path for the directory where created tests should be placed.

testing-framework

By default dcover automatically determines which test framework (JUnit or TestNG) and version is used by your project. The --testing-framework argument is used to specify which framework and version to use, especially useful if multiple frameworks or versions are used by your project.
Usage: --testing-framework=<framework-and-version>
Example: --testing-framework=junit-5 or --testing-framework=testng-7.8
Default: junit-4.8.2
The supported values for this option are as follows:
  • JUnit: Valid versions from junit-4.7 to junit-5.9 (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.

validation-command

Usage: --validation-command or -x
By default, dcover uses the standard Maven or Gradle test command to validate tests. You can override that with this option.
  • 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 file in the working directory. When the command fails for a certain test method, dcover will revert the entire test class containing that method.
  • 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. When the command fails for a certain test method, dcover will revert the entire test class containing that method.
Example:
--validation-command "mvn test"
The given command is executed after tests have been written, to make sure they do not 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.

validation-timeout

Usage: --validation-timeout
Example: --validation-timeout=duration
Default: --validation-timeout=30m
Specifies how long test validation may take before being cancelled.
Supported values:
  • A positive integer with one of the following suffixes: h (hours), m (minutes), or s (seconds).
  • Zero (0) - the test validation will not time out.

verbose

Usage: --verbose
If enabled, dcover provides more detailed log messages about the test writing process.

working-directory

Usage: --working-directory
Example: --working-directory=path/to/module
Sets the working directory for running dcover, enabling you to run dcover for a particular module, for example, from the root of a project.

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:
Command details:
Run the following dcover command:
dcover create
--coverage-reports
--upload <reports-server>
--project <name-of-project>
--name <name-of-report>
For example:
dcover create
--coverage-reports
--upload http://cover-reports-service
--project "customer-markets.trading.name.name"
--name "Branch: 1234/feature-TG12345"
Note: The previous --report argument has been replaced with --upload (Diffblue Cover release 2023.11.01 and later). Use of --report should be avoided as this option will be fully removed in future releases.

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

Upload Only

Upload an existing reports bundle only. This can be useful when the reports bundle has been generated separately, but not uploaded.
Command details:
Run the following dcover command:
dcover upload <reports-server>
--project <name-of-project>
--name <name-of-report>
For example:
dcover upload http://cover-reports-service
--project "customer-markets.trading.name.name"
--name "Branch: 1234/feature-TG12345"

Cover Pipeline commands

This topic provides details of the Cover Pipeline commands - see Cover Pipeline for information on using Diffblue Cover within your CI environment.

Enable CI

Usage: dcover ci
The dcover ci command enables Diffblue Cover to operate within a CI (Continuous Integration) environment. The behavior of dcover ci is as follows:
  1. 1.
    Prepares the CI environment.
  2. 2.
    Runs further dcover commands in sequence, as specified within your pipeline - for details, see Pipeline config.
  3. 3.
    Pushes any changes made by Diffblue Cover into the CI environment.
Note that dcover ci is currently for use with GitLab CI environments only - see Cover Pipeline for GitLab.

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
The dcover validate command removes both 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.

The clean command

Usage: dcover clean
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.
  • 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 or dcover fix-build
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 or dcover fix-build (the core Cover Refactor commands).
  1. 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. 2.
    Running dcover refactor or dcover fix-build 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. 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 or dcover create --fix-build - 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>
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, [email protected]
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
To view your license details (type, key, owner, limitations, etc - as illustrated above), run the dcover license command.