Comment on page
Commands & Arguments
Scripts, commands and subcommands for running Diffblue Cover CLI.
This topic covers Diffblue Cover CLI commands and options. Please see the Getting Started information if you need help with installation and initial setup.
Invocations of
dcover take a subcommand, e.g. create, clean or help.Command lines can become very long when many options are passed. Some terminals, such as those in Windows, do not support such long command lines, so Diffblue Cover CLI allows options to be imported from a plain text file with an arbitrary name, e.g.
config.txt. This file can then be passed to the tool by adding the option @config.txt.For example:
dcover create @config.txtOptions passed in this way can be added to the file one per line or separated by a space on the same line. Comments can also be added to the file.
Example configuration file:
--verbose --batch
--patch-only 'C:\Users\My User Name\myproject\patch.diff'
# We don't want to create tests for this class (this is a comment).
--exclude a.class.i.want.ToIgnore.
If you're using this feature under PowerShell, typically on Windows, you might hit the error:
The splatting operator '@' cannot be used to reference variables in an expression.
In this case make sure that you quote the configuration file to stop PowerShell from trying to interpret the
@ symbol:dcover create '@config.txt'If you have a certain set of arguments that you frequently use with a command, you can add them to plain text files in the following locations instead of using the
@ notation on the command line:.diffblue/create.args.diffblue/upload.args
This will allow you to run a command with common arguments, without having to repeatedly specify them on the command line
These files are command-specific, so any arguments added to
.diffblue/create.args will only affect the dcover create command and likewise any arguments added to .diffblue/upload.args will only affect the dcover upload command. Without these files in the particular location, all desired arguments will have to be specified when running the relevant command.Arguments added to these default configuration files can be overriden by specifying them, either on the command line or in a separate config file denoted by
@config.txt. For example, assuming you had the following arguments in your .diffblue/create.args file:--class-name-template "\${CLASS_NAME}Test"
--coverage-reports
You would be able to override these values by specifying them like so:
dcover create --class-name-template="\${CLASS_NAME}DiffblueTest" --coverage-reports=false.It should be noted that mutually exclusive parameters cannot be overriden. As a result, if you add these parameters to your default argument file, you will need to temporarily move or rename the file to be able to specify a different value. Currently, the following parameters are mutually exclusive:
--mavenand--gradle
Class files should be compiled with debug information included for Diffblue Cover to write the best tests possible. For specific build system recommendations see the Building a Maven project and Building a Gradle project topics.
The underlying
javac Java compiler can use a -g option to generate all debugging information, if you're using custom compiler arguments then please ensure the -g option and not -g:none are present.Usage:
dcover activate $LICENSEUsing
dcover requires a license to be activated before you are able to write tests. For pricing information, please see our pricing page. When you activate a license you'll see a summary of the license details printed to the console:❯ dcover activate $LICENSE
INFO Diffblue Cover 2021.08.03-SNAPSHOT-0bce711
INFO Successfully activated key $LICENSE
INFO
INFO License type: Enterprise Edition
INFO License key: $LICENSE
INFO License registered to: John Smith, john.smith@example.com
INFO Available features:
INFO Feature Batch Mode is neither time nor consumption limited
INFO Feature CLI is neither time nor consumption limited
INFO Feature Test Creation is limited to 2147483647 tests daily; you have used 0 of your current budget so far
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 Analytics is neither time nor consumption limited
INFO Feature Cover Reports Basic 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 commands "dcover help" will show you all the
INFO sub-commands, "dcover create --help" will show you help specific to the
INFO sub-command "create".
INFO
INFO See the Getting Started guide
INFO https://docs.diffblue.com/getting-started/cli/basic-concepts
If you ever need to see the information about your license (e.g. the type of license, the number of tests remaining, which features are available to you), you can get this same summary by running
dcover license.This topic provides an overview of the Cover Reports commands. For detailed information see Cover Reports Contributor.
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 is being 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 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 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"
Usage:
dcover createBy default,
dcover automatically discovers all the packages and writes tests for all of them. You can tell dcover to only write tests for specific packages, classes or methods by specifying one or more prefixes. dcover matches prefixes against the fully qualified method names with descriptor.dcover create com.a.. This will produce tests for all accessible methods within package com.a. and subpackages. For example, tests will be written for class com.a.B andcom.a.b.C but not for com.x.Y. Note that com.a (not com.a.) will allow tests to be written for class com.apple, com.apricot etc.Given two classes
io.diffblue.corebanking.account.Account and io.diffblue.corebanking.account.AccountException:dcover create io.diffblue.corebanking.account.Accountwill create tests for both classes but:
dcover create io.diffblue.corebanking.account.Account. (note trailing .)will create tests for the
Account class only.dcover create io.diffblue.corebanking.account.Account.addToBalance: (note trailing :)will create tests for all methods named
addToBalance, e.g. addToBalance(int value) and addToBalance(double value), but not addToBalanceDeferred(int value). In order to write tests for addToBalance(double value) only, but not for addToBalance(int value), you also have to specify the method descriptor:dcover create 'io.diffblue.corebanking.account.Account.addToBalance:(D)V'.The method descriptor is a list of type descriptors in a single string, that describe the parameter types and the return type of a method. As in the example above, the type descriptor (D for double) is enclosed within parentheses, followed by the type descriptor of the return type OR a V if the method returns void. For more information on type descriptors and method descriptors, please see sections 2.1.3 and 2.1.4 of the ASM 4.0 A Java bytecode engineering library.
- The descriptor is separated from the method name by
:. - You can also specify a list of prefixes to ignore, using the
--excludeoption (see below).
This is a list of the most common options, to see the full list of available options run
dcover help create. | ||||
| ||||
| ||||
| ||||
| ||||
| ||||
| ||||
| ||||
| ||||
| ||||
| | | |
Usage:
--act-into-assertUse this formatting option file to move execution of the MUT (method under test) from the act section into the assert section. This means there will not be an act section in the test(s) produced, and the MUT (normally within the act section) will now be run within the assertion statement in the assert section.
Usage:
--active-profilesExample:
--active-profiles=development, --active-profiles=development,testUse 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 this separate page for further details.
Usage:
--allow-jniExample:
--allow-jni=mycustomjni, --active-profiles=jnaUse 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-warningsA 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.For example:
--annotate-suppress-warnings=allsuppresses 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:S1161Usage:
--arrange-into-act-assertUse this formatting option to move all the information from the arrange section into either the act or assert sections, depending on the specific case. This means that there will not be an arrange section in the test(s) produced. The arrange section normally sets all of the variables and objects needed to run the MUT (method under test) and these will be inlined in the act section (when the MUT is run) or will become part of the assertion (in the assert section).
Usage:
--batchUse this option to run
dcover non-interactively, e.g. in CI, in order not to clutter the CI logs with progress bar output.Usage:
--build-system-configurationExample:
--build-system-configuration=~/.m2/settings.xmlUse this option if you want
dcover to use a custom configuration file when interacting with the Maven build tool.Usage:
--class-name-templateExample:
--class-name-template=\${CLASS_NAME}Test, default: --class-name-template=\${CLASS_NAME}DiffblueTestSpecifies 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.Usage:
--classpath or -cpBy 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.
By default,
dcover automatically determines the Java compliance level ("Java version") being used. You can set it explicitly with this option.Usage:
--compliance-levelExample:
--compliance-level=[3-13], default: --compliance-level=8Specifies 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.
Usage:
--cover-all-enumsIf 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.)Usage:
--coverage-reportsGenerate 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.
Usage:
--define or -DExamples:
--Dkey1=value1 --Dkey2=value2 -Dkey3=value3Define 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 are 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.Usage:
--disable-mock-inputsIf 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.Usage:
--disable-security-policyUses 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.
Usage:
--environmentExamples:
--environment KEY=VALUEDefine additional environment variable 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 are 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.Usage:
--exclude or -EExamples:
--exclude com.x.y. --exclude com.x.y.Foo --exclude com.x.y.Foo.bar:()VFor 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.Usage:
--existing-coverage or -eExample:
--existing-coverage=target/jacoco.execTakes a path to a JaCoCo coverage report ("target/jacoco.exec" here) as an argument, so that
dcover will write tests only for those lines of code which are not already covered by existing tests.Note 1: if using the JaCoCo coverage,
--merge must be used (otherwise the tests that produce the coverage, would be replaced!).Note 2: there are known issues with PowerMock and JaCoCo that can interfere with the usage of this feature:
Usage:
--fix-buildIf 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
fix-build option will add the missing dependency to your project for you.Usage:
--gradleFor cases where you prefer which tool is used, this option tells Cover to use Gradle.
Usage:
--ignore-stylechecksExample:
--ignore-stylechecks=true, default: --ignore-stylechecks=falseWhen 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.Usage:
--jacoco-command-diffblueExamples:
--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.javaWhen 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.Usage:
--jacoco-command-manualExamples:
--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.Usage:
--mavenFor cases where you prefer which tool is used, this option tells Cover to use Maven.
Usage:
--max-class-lengthExample:
--max-class-length=10000Allows 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.
Usage:
--mergeExample:
--merge=true, default: --merge=falseIf 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.Usage:
--method-name-templateDefault:
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.Usage:
--mockExample:
--mock io.diffblue.packagetomock io.diffblue.otherpackage.ClassToMockdcover 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.Usage:
--output-commentsExample:
--output-comments=falseBy default, this option is set to
true. Setting it to false prevents the inclusion of "Arrange", Act" and "Assert" comments for these three sections of the tests.Usage:
--patch-only or -pExample:
--patch-only=path/to/patch-fileBy 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
Usage:
--preflightRun all the project and environment checks that
dcover 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 creating the tests yet. Similarly, dcover create --coverage-reports --preflight performs all checks necessary for creating tests as well as coverage reports. For further information, please see: Preflight checks.Usage:
--skip-if-service-out-of-resourcesIf 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).
Usage:
--skip-test-validationBy 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 are using a manual classpath don't forget to add it.Usage:
--spring-integration-testsTests 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.Usage:
--strictForces 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.
Usage:
--test-output-dir or -dDefault:
src/test/javaExample:
--test-output-dir=src/test/diffblueLocation for the created tests relative to the working directory. Provide the relative path for the directory where created tests should be placed.
By default
dcover automatically determines the version of JUnit in use by your project. If there are multiple versions available, dcover will ask you which one you want to use. The --testing-framework command is used to specify which version to use.Usage:
--testing-framework <testing framework and version>Example:
--testing-framework=junit-4.7The supported values for this option are 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), valid versions from testng-6.0.1 to testng-7.8, and the special values junit-4 (any JUnit 4), junit-5 (any JUnit 5 or later), or testng (any TestNG).If you choose to supply 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.The default is:
junit-4.8.2Usage
--validation-command or -xBy 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
-Dtestoption can be appended. The command should not already contain-Dtest. - If
dcover createis 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
dcoverdetects a pom file in the working directory. When the command fails for a certain test method,dcoverwill revert the entire test class containing that method.
- Gradle:
- The command must be a standard Gradle command invoking a
Testtask, which will produce JUnit XML reports, and to which the--testsoption can be appended. - The command must not already contain the
--testsoption. - The command must have info logging enabled (for test validation to work correctly). This can be done by adding
-i/--infoto the command. - If no command is provided, "gradle test" is run if
dcoverdetects a Gradle project in the working directory. When the command fails for a certain test method,dcoverwill 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.Usage:
--validation-timeoutExample:
--validation-timeout=duration, default: --validation-timeout=30mSpecifies how long test validation may take before being cancelled.
Supported values:
A positive integer value with one of the following suffixes:
h for hours, m for minutes, or s for seconds.If
0 (zero) is specified, the test validation will not timeout.Usage:
--verboseIf enabled, prints more detailed log messages about the test writing process.
Usage:
--working-directoryExample:
--working-directory=path/to/moduleSets the working directory for running
dcover, enabling the user to run dcover for a particular module, for example, from the root of a project.Example:
dcover cleanThe
clean command removes test methods written by dcover that no longer compile due to changes in the project.As with
create, if the package prefixes following clean are omitted, dcover will infer the packages from the directory structure.As detailed in the
create section above:Further optional arguments specific to
clean:Deprecated, use
dcover validate instead.Usage:
--test-classes-dir="target/different-test-classes-directory", default: Determined by build system.Directory to where created tests are compiled. This is necessary if the directory is different than the build system default.
The
validate command removes both non-compiling and failing tests by running a Maven or Gradle command. Running dcover validate removes failing and non-compiling unit test classes if they end in DiffblueTest.Examples:
dcover validateAlternatively, the command can be used with extra options, for example:
dcover validate --validation-command="mvn test -Dtest='*DiffblueTest.java'"
This call to dcover validate runs the specified validation command mvn test -Dtest=*DiffblueTest.java and deletes any non-compiling or failing tests resulting from this command.As detailed in the
create section above:Last modified 20d ago

