Module 1: Create your Cover unit test baseline

In this module, we will enable you to perform the first steps of onboarding a new project. These are:

1. make your first projects Cover-ready by validating the build configuration with respect to unit testing, and

2. write a test baseline for your first projects

Prerequisites

To start this module, you need to satisfy the prerequisites, which amount to having Cover installed at least to the level of Reference Deployment 1, i.e.

• Cover Reports is installed on a central server.

• As a champion you have Cover CLI installed in a development environment that satisfies the requirements.

• You have run preflight and sent the log files to Diffblue.

License activation

Activate Cover CLI using the license key that you received from the contact for software and license distribution in your organization:

dcover activate XXXX-XXXX-XXXX-XXXX

View your license details to check that the activation was successful:

dcover license

Telemetry configuration

We will check that telemetry is correctly configured on your system.

Usage information is sent to

• External Diffblue telemetry server (Enterprise Edition users can opt out)

• Cover Reports (if configured)

Telemetry is configured via one of

• ~/.diffblue/telemetry.properties, or

• Environment variables

Check that:

• External telemetry is configured according to your company policies.

• Cover Reports telemetry points to your central Cover Reports server.

Make your project Cover-ready

We will work through the whole flow for creating baseline tests.

You can find a worked example of the entire flow here.

If your project has multiple modules we recommend that you start with a representative module. Once the selected module is working, repeat the steps on the other modules.

Note that you can run a specific module without changing your working directory by adding the following option to the dcover commands: --working-directory your-selected-module

We will start with the validation of your build configuration - and fixing it if necessary. We will also measure and upload your existing unit test coverage.

Step	Command
1. Build the project from its root	E.g. ./mvnw install -DskipTests
2. Check and fix the project environment	dcover create --preflight dcover fix-build If necessary, apply manual fixes to your build configuration
3. Commit fixes	As soon as preflight doesn't report any errors or warnings: git checkout -b diffblue-baseline git commit -a -m "Build configuration fixes for Diffblue"
4. Measure and upload existing coverage	dcover coverage-reports dcover upload http://your-cover-reports:8080 View Cover Reports

Create your unit test baseline

We are now ready to create the baseline tests.

Step	Command
5. Create the baseline tests and measure coverage	dcover create --coverage-reports
6. Commit the baseline tests	git add `find . -name '*DiffblueTest.java'` git commit -m "Diffblue baseline tests"
7. Upload the baseline coverage	dcover upload http://your-cover-reports:8080
8. Review results	View Cover Reports View created tests in IntelliJ
9. Push the changes	git push --set-upstream origin diffblue-baseline Create a pull request and get it merged.

What does Cover CLI do?

When running a Cover command, the execution proceeds in several phases.

Phase	Description	Additional execution information
Detecting environment	Every Cover command starts by performing environment health checks to detect whether the project environment is ready for the Cover command to run.	When using --preflight, Cover stops after this phase and outputs an environment summary.
Creating tests	This phase performs the generation of tests class per class, method per method.	Only executed when using the create command. Ends with a summary with number of tests created and issues encountered.
Validating tests	This phase validates the created tests, i.e. it removes non-compiling and failing tests.	Executed after test generation when using the create command. Test validation can also be run separately using the validate command.
Calculating coverage	This phase calculates the coverage of manually written and Diffblue tests using JaCoCo.	Executed when passing the --coverage-reports option to the create command. Coverage reports can also be generated separately using the coverage-reports command.
Upload to Cover Reports	This phase uploads the coverage reports to Cover Reports.	Executed when running the upload command.

Understanding Cover's log output

Cover produces output with increasing degree of detail:

• Console output

• Console output with --verbose

• User log file

• Support log file

The log files are in the .diffblue/log directory below the directory from where Cover was run.

Overview of CLI options

The following is a short list of the more pertinent options for creating baseline tests. Details of additional options can be found in the Commands & Arguments.

• Select module to run on without changing directory, e.g. --working-directory my-module/my-submodule

• Exclude modules, e.g. --exclude-modules my-module/to-exclude

• Verbose console output: --verbose

• Prefer Maven over Gradle: --maven

• Test framework, e.g. --test-framework junit-4

• Active Spring profiles, e.g. --active-profiles test

• Ignore style checks: --ignore-stylechecks

• System properties, e.g. -Dmy.property=value

• Environment variables, e.g. --environment MYVAR=value

• CLI help: dcover help create

Cover automatically figures out which entry point methods to write tests for. The set of methods can be restricted by specifying inclusions and exclusions. E.g. to write tests only for the OwnerController class you can run dcover create org.springframework.samples.petclinic.owner.OwnerController

What does Cover do during test generation?

To generate tests, Cover analyzes your project's bytecode. It runs your code, and thus operates in a sandbox. The sandbox runs in a separate service process which prohibits system calls (file system, network, etc) to protect your system from potentially detrimental functionality within your codebase (e.g. wiping your filesystem, spamming third party services).

Cover partitions your code into groups of methods under test that it is going to test. For each group of methods under test, Cover

• either produces tests

• or an output code that explains why it didn’t produce complete tests

Understanding Cover's output codes

Output codes identify the messages that Cover outputs, e.g. E052 - Missing dependency

The output code can be used to quickly look it up in docs: e.g. https://diff.blue/E052

There are different types of messages distinguished by the first letter in the output code:

• Informational messages:

  • Testability (T), reason for not writing tests (R)

• Warnings/errors:

  • Project environment (E) including coverage measurement and reports upload

  • Licensing (L)

What does test validation do?

Validation ensures that generated tests compile and pass. This is essential for Cover's autonomous operation in your CI Pipeline.

You may see two output codes related to test validation:

• First, tests are compiled and run individually (W output code).

• Finally, tests are run via your build system (V output code).

Coverage measurement

Cover uses JaCoCo for coverage measurement.

Cover distinguishes two types of tests:

• Diffblue-controlled tests (“Diffblue”)

  • Unchanged tests written by Cover

  • Automatically maintained by CI pipeline

• User-controlled tests (“manual”)

  • Manually written or modified Diffblue tests

  • Maintained by user

  • These include the existing tests that you have manually written before starting to use Cover.

How to ask for support

Before reaching out, check for potential solutions in

• the documentation

• and the forum

More complex questions & issues contact support depending on your support plan.

Requirements for Diffblue to handle your support case:

• Detailed description of what you did and the behavior you observe (compared with what you expect)

  • Diffblue Cover support log file

  • Additionally, for R code-related questions, one of the following:

    • A reproducer (most valuable to be able to support): a piece of code that results in the the R code message that you see

    • A code snippet of the relevant code under test (useful, but with lower chances of success) and a partial test (if there is one) with the R code

Worked example: Baseline creation process using the Petclinic demo project

The prerequisites for running this example are:

• JDK 17 has been installed.

• Cover Reports has been downloaded, unpacked locally, and started by running bin/cover-reports

• The demo project has been cloned by running git clone https://github.com/diffblue/demo-spring-petclinic

• To use the dcover fix-build command in step 2, these prerequisites must be met.

We will work through the whole flow for creating baseline tests.

Step	Command
1. Build the project from its root	./mvnw install -DskipTests
2. Check and fix the project environment	dcover create --preflight dcover fix-build
3. Commit fixes	git checkout -b diffblue-baseline git commit -a -m "Build configuration fixes for Diffblue"
4. Measure and upload existing coverage	dcover coverage-reports dcover upload http://localhost:8080 View Cover Reports
5. Create the baseline tests and measure coverage	dcover create --coverage-reports
6. Commit the baseline tests	git add `find . -name '*DiffblueTest.java'` git commit -m "Diffblue baseline tests"
7. Upload the baseline coverage	dcover upload http://localhost:8080
8. Review results	View Cover Reports View created tests in IntelliJ
9. Push the changes	We skip this step for the demo project.