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)
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.
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.
We are now ready to create the baseline tests.
When running a Cover command, the execution proceeds in several phases.
Cover produces output with increasing degree of detail:
Console output
Console output with
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 .
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:
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
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
Output codes identify the , e.g. E052 - Missing dependency
The output code can be used to quickly look it up in docs: e.g.
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
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”)
Before reaching out, check for potential solutions in
and
More complex questions & issues .
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
Additionally, for -related questions, one of the following:
A
The prerequisites for running this example are:
JDK 17 has been installed.
, and started by running bin/cover-reports
The demo project has been cloned by running git clone
We will work through the whole flow for creating baseline tests.
Upload to Cover Reports
This phase uploads the coverage reports to Cover Reports.
Executed when running the command.
--mavenTest 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
Licensing (L)
Manually written or modified Diffblue tests
Maintained by user
These include the existing tests that you have manually written before starting to use Cover.
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
dcover fix-builddcover upload http://localhost:8080
8. Review results
View created tests in IntelliJ
9. Push the changes
We skip this step for the demo project.
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
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.
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.
Calculating coverage
This phase calculates the coverage of manually written and Diffblue tests using JaCoCo.
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
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"
Executed when passing the option to the command.
Coverage reports can also be generated separately using the command.
7. Upload the baseline coverage
dcover activate XXXX-XXXX-XXXX-XXXXdcover license