CLI Manual



Commands

All invocations of dcover take one of the following subcommands create, clean or coverage-diff.

The create command

Usage: dcover create

By 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 create com.a.

This will produce tests for all accessible functions within package com.a (but none for any other classes).


Additional optional arguments for create

active-profiles

Usage: --active-profiles

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

Use this option to specify any Spring profiles to activate while generating 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.


batch

Usage: --batch

Use this option to run dcover non-interactively, e.g. in CI, in order not to clutter the CI logs with progress bar output.


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 generated. 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 generated 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 generate 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 JUnit (and any other dependencies required to run the project's unit tests) are on the classpath in order for the tests to be verified.


clear-index

Usage: --clear-index

Clear any cached index data and recompute the index from scratch. This may help if the class information used by dcover seems to be outdated or corrupted.


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


config

Usage: --config

Example: --config path/to/config.json

Provides a path to a file containing json in the configuration format (see --example-config). All of the options listed in this help file can be specified in the configuration json file, plus some others. The additional options that can be specified in the configuration json are:

  • Style

    • output comments, default: enabled

      If enabled, prints comments in the test to designate sections, e.g. // Act, // Arrange, // Assert.

    • inline constants, default: enabled

      If disabled, these will be represented with intermediate variables. If enabled, constants of immediate values (unboxed and boxed primitives, strings, enums, nulls) are inlined into function calls.

    • inline constructors, default: enabled

      If disabled, objects created by calls to constructors will be represented with intermediate variables. If enabled, calls to constructors will be inlined into method calls if possible.

    • arrange into act assert, default: enabled

      If disabled, the test will be separated into an arrange section which sets up all of the variables for the call to the method under test and/or asserts. If enabled, values that can be inlined into the call to the method under test or asserts will be inlined.

    • act into assert, default: enabled

      If disabled, the result of the call to the method under test will be stored in an intermediate variable. If enabled, the call to the method under test will be inlined into an assert statement if possible.


disable-security-policy

Usage: --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 generation, which may change the file system. Existing files will not be changed or deleted, but new files may be created.


example-config

Usage: --example-config

If specified, an example configuration file will be output to the command line, then the options can be modified to suit the project and saved in a file. If the command is run from a project's root, dcover will attempt to infer some values for the configuration file, e.g., the packages in the project and --classpath.


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 generation. 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 ("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:

https://github.com/powermock/powermock/wiki/Code-coverage-with-JaCoCo


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. This is currently supported by Maven projects.

If dcover cannot validate the tests it generates due to an incompatibility with the stylecheck used in your environment, you will receive an error message. For further information, please see: Maven Troubleshooting or Gradle Troubleshooting.


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

If disabled, any existing .java test file will be overwritten and contain only the newly-generated tests.


method-name-template

Usage: --method-name-template

Default: test\${INNER_CLASS_NAME}$\${METHOD_NAME}

Example: testGenerated\${INNER_CLASS_NAME}\${METHOD_NAME}

Specifies how to name the test methods that are generated. 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 non-static 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.


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

report

Usage: --report

Example: --report=path/to/report.json

Write JSON-formatted test-writing summary report to the file specified.


skip-test-validation

Usage: --skip-test-validation

By default, generated 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.


target-directory

Usage: --target-directory

Default: .diffblue

Example: --target-directory=target/directory

Set the directory for storing dcover's working files and logs.


test-output-dir

Usage: --test-output-dir or -d

Default: src/test/java

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

Location for the generated tests relative to the working directory. Provide the relative path for the directory where generated tests should be placed.

See working-directory below.


testing-framework

By default dcover automatically determines the version of JUnit in use by your project. You can override it with this option.

Usage: --testing-framework

Example: --testing-framework=junit-5.7

The supported values for this option are the versions of JUnit from junit-4.7 to junit-5.7. 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.


verbose

Usage: --verbose

If enabled, prints more detailed log messages about the test generation process.


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:

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

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


working-directory

Usage: --working-directory

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

Sets the working directory for running dcover, enabling the user to run dcover for a particular module, for example, from the root of a project.



The clean command

Example:

dcover clean

The clean command removes test methods written by dcover that no longer compile due changes in the project.

As with create, if the package prefixes following clean are omitted, dcover will infer the packages from the directory structure.

Additional optional arguments for clean

As in the create section above:

batch

class-name-template

classpath

compliance-level

method-name-template

target-directory

test-output-directory

testing-framework

verbose

Optional argument specific to clean:

failing

Usage: --failing

When enabled, instead of deleting non-compiling tests, dcover clean deletes any failing test classes.



The coverage-diff command

Usage: --coverage-diff

Example: dcover coverage-diff target/jacocoOld.exec target/jacocoNew.exec

For visualizing the new coverage gained by writing tests with Diffblue Cover CLI.

Generates an HTML report highlighting the difference between two supplied JaCoCo coverage reports.

Please see "Generating an HTML report highlighting new coverage" for more information.

results matching ""

    No results matching ""