Module 1: Create your Cover unit test baseline
Last updated
Was this helpful?
Last updated
Was this helpful?
In this module, we will enable you to perform the first steps of onboarding a new project. These are:
make your first projects Cover-ready by validating the build configuration with respect to unit testing, and
write a test baseline for your first projects
To start this module, you need to satisfy the , which amount to having Cover installed at least to the level of , i.e.
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.
using the license key that you received from the contact for software and license distribution in your organization:
View your license details to check that the activation was successful:
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)
~/.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.
We will work through the whole flow for creating baseline tests.
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.
1. Build the project from its root
E.g. ./mvnw install -DskipTests
2. Check and fix the project environment
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
View Cover Reports
We are now ready to create the baseline tests.
5. Create the baseline tests and measure coverage
6. Commit the baseline tests
git add `find . -name '*DiffblueTest.java'`
git commit -m "Diffblue baseline tests"
7. Upload the baseline coverage
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.
When running a Cover command, the execution proceeds in several phases.
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.
Creating tests
This phase performs the generation of tests class per class, method per method.
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.
Calculating coverage
This phase calculates the coverage of manually written and Diffblue tests using JaCoCo.
Upload to Cover Reports
This phase uploads the coverage reports to Cover Reports.
Cover produces output with increasing degree of detail:
Console output
The log files are in the .diffblue/log directory below the directory from where Cover was run.
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.
CLI help: dcover help create
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
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)
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).
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.
Before reaching out, check for potential solutions in
Requirements for Diffblue to handle your support case:
Detailed description of what you did and the behavior you observe (compared with what you expect)
A reproducer (most valuable to be able to support): a piece of code that results in the the R code message that you see
The prerequisites for running this example are:
JDK 17 has been installed.
We will work through the whole flow for creating baseline tests.
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
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 created tests in IntelliJ
9. Push the changes
We skip this step for the demo project.
via one of
You can find a worked example of the entire flow .
Note that you can run a specific module without changing your working directory by adding the following option to the dcover commands: your-selected-module
dcover create
dcover
dcover
dcover http://your-cover-reports:8080
dcover
dcover http://your-cover-reports:8080
When using , Cover stops after this phase and outputs an environment summary.
Only executed when using the command.
Executed after test generation when using the command.
Test validation can also be run separately using the command.
Executed when passing the option to the command.
Coverage reports can also be generated separately using the command.
Executed when running the command.
Console output with
Select module to run on without changing directory, e.g. my-module/my-submodule
Exclude modules, e.g. my-module/to-exclude
Verbose console output:
Prefer Maven over Gradle:
Test framework, e.g. junit-4
Active Spring profiles, e.g. test
Ignore style checks:
System properties, e.g. my.property=value
Environment variables, e.g. MYVAR=value
Cover automatically figures out which entry point methods to write tests for. The set of methods can be restricted by . E.g. to write tests only for the OwnerController class you can run dcover create org.springframework.samples.petclinic.owner.OwnerController
Output codes identify the , e.g. E052 - Missing dependency
The output code can be used to quickly look it up in docs: e.g.
and
More complex questions & issues .
Diffblue Cover
Additionally, for -related questions, one of the following:
A code snippet of the relevant code under test (useful, but with lower chances of success) and a (if there is one) with the R code
, and started by running bin/cover-reports
The demo project has been cloned by running git clone
To use the dcover fix-build command in step 2, must be met.