Preflight checks

Diffblue Cover's preflight option checks the suitability of your environment without running a full process.

Diffblue Cover's preflight option checks the suitability of your environment without running a full process. This allows you to rectify any environmental challenges before writing any tests.

Running preflight checks

The preflight check can be run with a single dcover command from the root of the project or module and carries out the relevant checks. This is done by adding the option --preflight to the desired command.

The preflight check requires that all of the environmental conditions are met for running dcover:

• Prerequisites for Cover CLI.

• The project is built with the artifacts available.

• Any existing tests compile and pass (for create only).

Then the command can be run, for example:

$ dcover create --preflight

The --preflight option can be added to any dcover command, for example added to the coverage-reports option as dcover coverage-reports --preflight which will carry out checks relevant to creating coverage reports (such as checking the JaCoCo plugin version) but not other checks related to test creation (such as Spring dependencies).

If needed, the --preflight option can be used without a Diffblue Cover license.

Understanding the environment summary

After the checks have been carried out a summary table is displayed. Several key checks, along with any warnings and errors are shown with a result of SUCCESS, WARNING or ERROR. An overall Environment check status is also given.

INFO  Environment summary:
INFO  --------------------
INFO  Java version                  11.0.14             SUCCESS
INFO  Build system                  Gradle              SUCCESS
INFO  Testing framework             JUnit Jupiter 5     SUCCESS
INFO  Launcher                      JUnit Jupiter       SUCCESS
INFO  Test validation               Enabled             SUCCESS
INFO  Spring Core                   5.3.14              SUCCESS
WARN  Spring Web                    5.3.6               WARNING
INFO  Spring Test                   5.3.14              SUCCESS
INFO  Spring Boot                   2.6.2               SUCCESS
INFO  Spring Boot Test              2.6.2               SUCCESS
INFO  Hamcrest                      Hamcrest 2 2.2      SUCCESS
INFO  Mocking Framework             Mockito 4.0.0       SUCCESS
ERROR JVM matches compilation JDK   17                  ERROR
INFO
INFO  Environment check status: ERROR

Errors indicate a problem with the environment that must be corrected before the full command can be run (e.g. the current JVM does not match the compilation JDK). Warnings indicate the setup is not optimal, but they will not prevent the full command from being run (e.g. Spring dependencies are mismatched).

Detailed recommendations on how to fix the warnings and errors can be found above the summary table.

The summary table is displayed in the user log file even when a command is run without the --preflight option.

A cache of some of these values is produced every time the environment checks are performed, however, this cache is only used when --use-cache is specified on the command line. Using the cache will improve the performance of these environment checks. The cache will not be available when run with the ci command. If the cache needs to be reset, re-run the same command but without the --use-cache option. Should the cache need to be removed, manually delete the .diffblue/cache folder and its contents in all modules of your project.

Automatic fixing of environment issues

Environment issues resulting in an R002, E027, E052, E086, E118, E137, E013, E053, E066, or E119 output code can be automatically fixed by running dcover refactor or dcover create --refactor. Note that an automatic fix is not always possible, especially when the project is very simple (no imports, no methods calling other methods, only primitive types, etc). See Commands & Arguments.

Running existing tests

As part of the preflight checks for dcover create, Cover CLI will run the existing tests and ensure that they compile and run without any problems. This is effectively running mvn test or ./gradlew test (depending on the build system being used). It is possible to customize the commands being used along with the timeout (by default this is 30 minutes) with the --preflight-test-command and --preflight-test-timeout options respectively. It is possible to skip running the existing tests by specifying --preflight-without-tests, however doing so will result in a poor experience with dcover.

As part of the preflight checks for dcover create, it will run the existing tests and ensure that they compile and run without any problems. This is effectively running mvn test or ./gradlew test, depending on the build system being used. It's possible to modify the commands being used by customizing your build system configuration for Diffblue Cover following the guidelines here. It's also possible to skip running the existing tests by specifying --preflight-without-tests, although this is not recommended.

Argument	Description
--preflight-without-tests	Disable running existing tests. Note that in general this is not recommended, however this can improve performance times when you already know that the tests compile and run without any issues, or you're focusing attention in other areas.

The following options are deprecated and should no longer be used: you can customize your build system configuration for Diffblue Cover following the guidelines here.

Argument	Description
--preflight-test-command =<value>	Custom Maven or Gradle command that runs the tests during preflight checks. Optional.
--preflight-test-timeout =<duration><unit>	Cancel test execution after the specified timeout (default is 30m). Optional.