Cover CLI Usage

Scripts

To execute the Cover CLI, the following scripts are available:

  • dcover.bat (Windows)
  • dcover (Linux/macOS)

These should be run in the root of a single-module project or within a module of a multi-module project.

Windows

Example:

./dcover.bat create com.acme.MyClass --test-output-dir=project/src/test/java -cp "project/target/classes"

Linux/macOS

Example:

./dcover create com.acme.MyClass --test-output-dir=project/src/test/java -cp "project/target/classes"

Commands

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

create

Example:

dcover create com.a

Will produce tests for all accessible functions within package com.a (but none for any classes in com.b)

The argument following create can be omitted, e.g. dcover create, and dcover will infer the packages from the directory structure in src/main/java by looking for all directories which contain Java classes. For a project with the structure:

src/main/java/com/packagea/ClassA.java
src/main/java/com/packageb/implementation/ClassB.java

The inferred packages are com.packagea and com.packageb.implementation.

These additional optional arguments can also be provided:

--advanced

Example:

--advanced=true, default: --advanced=false

If true, Cover will perform a more comprehensive analysis in order to cover more lines of the project.

For methods that have conditional branches, this can result in several tests for each method. With this option enabled, Cover's running time is typically an order of magnitude greater and is much more memory-intensive.

--batch

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

--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 or -cp

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

For Maven projects, if no classpath is provided, one will be inferred. Note that this might not work for unsupported Maven versions. For Gradle projects, if no classpath is provided, one will be inferred. Note that this might not work for unsupported Gradle versions. For other projects you must provide a classpath using this argument.

If this argument is used, you must ensure Junit 4 (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

Clears any cached index data for this project and re-computes it. This may help if the class information used by dcover seems to be outdated or corrupted.

--compliance-level

Example:

--compliance-level=[3-13], default: --compliance-level=8

Specifies the Java Compiler Compliance Level (as an integer) that the classes of the generated tests will be written with. Versions 3 to 13 are supported. The default value is 8.

For example, 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. i.e. if your project uses Java 1.6, set the compliance level to 6.

--config

Example:

--config path/to/config.json

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

  • Naming

    • method name template, default: ${METHOD_NAME}Test

      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.

  • 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 enabled, constants of immediate values (unboxed and boxed primitives, strings, enums, nulls) are inlined into function calls. If disabled, these will be represented with intermediate variables.

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

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

--exception-tests

By default, dcover will not generate tests where the only assertion is for an exception thrown by the method under test. If specified, this option will generate these exception tests.

--exclude or -E

Example:

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

Example:

--ignore-stylechecks=true, default: --ignore-stylechecks=false

When set, dcover will suppress known style checking plugins (checkstyle, spring-javaformat) during test verification; style checks may prevent compilation or test execution. Currently only supported by Maven projects.

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

--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 covered by the patch.

In order to create a patch-file for your changes relative to a develop branch, use:

git -C <module> diff develop --relative > patch-file

dcover --patch-only=patch-file can then be run from inside the project module, or from the root of the project using the --working-directory option to specify the relevant module.

--skip-test-verification

By default, generated tests are compiled and executed to make sure they are correct, and only those which succeed will be kept. This process will increase the test creation time, so it may be desirable to skip verification via this option. For test verification to work, JUnit-4 must be on the classpath, either added manually or inferred as a dependency (see the --classpath option). Using --skip-test-verification removes this constraint.

--test-output-dir or -d

Example:

--test-output-dir=src/test/java

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.

--testing-framework

The tests generated by default are compatible with JUnit versions 4.7 to 4.12. Tests may be generated that are compatible with alternative test framework versions by specifying an alternative test framework name and version number.

Example:

--testing-framework=junit-5.6

Supported values:

The supported values for this option are the versions of JUnit from junit-4.7 to junit-5.6 inclusive. If you have a version of junit-4 or junit-jupiter-api-5 in your classpath the appropriate value will be chosen for you. 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

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

--verification-command or -x

Example:

--verification-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. Typical values for this option are "mvn test" or "gradle test".

It is required that all existing tests should pass the verification command before dcover is invoked; there should be no pre-existing compilation or test failures.

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

--verification-command-directory

Example:

--verification-command-directory=path/to/directory

Specifies the directory in which to run the verification command. By default, this is the working directory. See --working-directory.

--verification-timeout

Example:

--verification-timeout=duration, default: --verification-timeout=30m

Specifies how long test verification 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 verification will not timeout.

--working-directory

Example:

--working-directory=path/to/sub-module

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

clean

Example:

dcover clean

Removes existing non-compiling test methods and test classes.

This command will search the output directory using the class name template to match generated test source files. Each test source file will be parsed and any non-compiling test methods will be removed. If after method removal there are remaining non-compiling test source files, those files will be deleted.

Designed for the case where existing generated test source files are now non-compiling due to changes in the main source code.

As with create if the arguments following clean are omitted, e.g. dcover clean, dcover will infer the packages from the directory structure.

These additional optional arguments can also be provided:

--batch

As with create above, use this option to run Cover non-interactively.

--class-name-template

Example:

--class-name-template=\${CLASS_NAME}Test, default: --class-name-template=\${CLASS_NAME}DiffblueTest

The template for locating generated test classes. As with create --class-name-template above, the variable ${CLASS_NAME} will be substituted with the name of the class under test. The $ must be escaped.

--classpath or -cp

Example:

-cp "target/classes:~/.m2/repository/junit/junit/4.12/junit-4.12.jar"

The classpath(s) of the project you want to generate tests for. For Maven projects, if no classpath is provided, one will be inferred. If you provide one you will need to include the Junit framework. See create --classpath above for further information.

--test-output-dir or -d

Example:

--test-output-dir=src/test/java

The output directory for generated tests from which methods and classes will be cleaned. See create --test-output-dir above for further information.

--compliance-level

Example:

--compliance-level=[3-13], default: --compliance-level=8

Specifies the Java Compiler Compliance Level (as an integer) that the generated tests were written with. See create --compliance-level above for further details.

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" in the User guide for more information.

results matching ""

    No results matching ""