Commands & Arguments
Last updated
Last updated
This topic details the Cover CLI commands and optional arguments.
dcover create
dcover coverage-reports
dcover upload
dcover ci
dcover build
dcover clean
dcover validate
dcover refactor
dcover fix-build
dcover activate
dcover license
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.
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.
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.
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).
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.
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.
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.
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"}
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.
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.
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.
Usage: --classpath="<value>[;<value>...]"
Alternative: -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.
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.
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.
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.
--coverage-reports
Generates the reports bundle.
--upload=<reports-server>
--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:
Example:
Optional JaCoCo arguments:
--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).
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
Usage: --no-spring-tests
Description: If used, dcover will not use Spring contexts for dependency injection in tests.
Usage: --no-spring-boot-tests