Getting started with Diffblue Cover
Initial use, signup & login
Once Diffblue is running within your network you should be able to access the main user interface on the installed IP/Hostname e.g.
http://[your hostname]/ through your web browser (we recommend Chrome for the best experience). This is the hostname that you have setup to access the product. You will be presented with a login as follows:
On a clean installation no users will be present, so create one by clicking the
Sign up button at the bottom of the screen:
Then fill in the details for your initial user. Usernames cannot contain spaces or special characters except
_. Passwords must be at least ten characters in length and can be made up of any characters.
Note: All users have the same level of access and will be able to monitor projects from all other users on the installation.
Once you have created your user you will automatically be logged in to the
Dashboard for that user:
Dashboard & adding a project for analysis
The dashboard shows you all of your projects and their status, as well as giving you the tools to add new projects and trigger analyses.
The first step to using Diffblue Cover is to connect your project by clicking
Add project. From here, you can either choose to have a walkthrough using our java-demo project as an example, (this is provided with your shipped version of the product, it is a zip file called
java-demo.zip) or move straight on to analysing your own repository archive.
Add a new Project prompt will ask for a project name and whether the required project is from a
Git repository, publicly accessible repository URL (for private repositories see Adding Credentials), or an
Archive upload which can be any archive of code from your machine.
Adding an archive upload
If you choose the
Archive upload button, you will be presented with a file browser where you can add your source code or the
java-demo.zip shipped with Diffblue Cover. Your code archive should be in zip or tar format. Once the name and archive are selected you can then click
Add project at the bottom of the dialog to add the project.
Adding a repository
If you choose the
Git repository option, you will need a link to your project from your version control system.
Using the example of
Java Demo, input the
Git repository URL to
https://github.com/diffblue/java-demo, name it in a relevant way, like in this instance
java-demo, and then click
This will then fetch and display the branch information for the repository, allowing you to select the branch you wish to analyse. In the case of
java-demo we recommend
master. On selecting
Add project button at the bottom of the screen will be enabled, allowing you to add the repository as a project. You have the option of specifying build and test commands.
Note: Before running an analysis you will need to define how you compile and test your Java project. You can do this by specifying the required command using the included boxes Build Command and Test Command. See section Configuring Diffblue Cover for more information and different methods of how to successfully configure your project. If you run an analysis and nothing happens it is probably because you have not specified the build and test commands.
Running an analysis
Once the project is created it will begin cloning the repo or processing the archive selected when the project was created. Once this is complete the project will show the read icon (the Diffblue owl) and the
Start analysis button will be enabled.
Start a new analysis will trigger the application to run a full analysis. The UI will show
Analysis running along with the percentage of the analysis that has completed:
This screen shows the analyses that have been started, including any currently running. Each analysis can be expanded to provide more information about the specific run and allow the analysis to be stopped:
Once the analysis starts the
View results button becomes available. If the analysis is still running a progress bar will be displayed at the top of the results pages until it completes.
View results you will be presented with the coverage view:
The examples in this section assume an archive upload analysis of
Java Demo. The results are shown as coverage increase over your project, which is broken down into the directory structure of your project. Green shows coverage provided by the tests within the project, blue shows the coverage Diffblue can provide with the tests generated, and red shows where no coverage from either existing test coverage or Diffblue analysis exists. Directories can be expanded and collapsed, and clicking an entry in the list gives a more detailed code view which shows the individual line coverage. The first file in your project will be opened by default.
At this stage all of the tests produced can be downloaded using the
Donwload All Tests button which will provide you with an archive of all of the tests. See section Executing Diffblue Tests for more information about integrating the tests back into your test suite. Clicking the
Tests tab will take you to the following test list view:
This shows all of the tests Diffblue Cover has produced, along with the class they test against and the number of lines of additional coverage these tests provide. Clicking on any test will expand the line to show a breakdown of the input, output and relevant state variables for that test. To see the contents of the test itself click
Note: Each test shows the blocks of code that it covers in a comment at the top. This can be omitted if you wish to use the test in your own test-suite
Here you can
Copy test into your system clipboard or select
Download java file. If you wish to use this unit test in your test suite, please ensure you have appropriately set up
Diffblue Cover™ utilities; see section Executing Diffblue tests for more information. If you are working in an offline environment you can use the link in the product to directly download
deeptestutils.x-y-z.tar and incorporate the files into your environment. For more details see section Offline Diffblue Cover.
At this point you can also click
View Trace to see how the test was calculated. This can help guide your decision on whether the test should be included in your suite:
You can then run through the steps that were analysed to produce the test by using the debug buttons at the top, seeing the
Variables at the relevant steps and jump to further steps by selecting a particular entry in the
Differential analysis (or 'quick analysis')
When a project has been fully analysed by Diffblue Cover, subsequent analyses can be run as
Differential (or 'quick'). This option only analyses the functions that have been changed or added since the previous analysis. In order to calculate the changes since the last analysis Diffblue first needs to be provided with a new source. For projects that use Git repositories Diffblue will pull the latest changes from the repository which happens automatically when the analysis is run so no action is required. For projects that use archives of source you must first upload a new archive before running the analysis; see section Updating Archive Project. Once source code has been updated an analysis will automatically be run as
Differential by default. Please note that when looking at the coverage viewer only the files that have changes will be displayed:
On running a
Differential analysis you will notice that the
Full label is not shown against that analysis on the 'Projects' page. On completion the numbers shown for the analysis reference only the newly created tests as well as the extra increase in coverage for those tests:
Updating Archive Project
To provide a new archive containing updated source code for your project select the project in the project list. Then click the
Settings drop down, and select
Upload new code:
This will bring up the
Upload new code dialogue where you can choose an archive containing the new source code:
Upload new code to accept and once complete the dialogue will display
Success and disappear. Your project is then ready to run a
Differential Analysis against the new source.
Force Full Analysis
If you require a full analysis for a project to be run select the project in the project list. Then click the
Settings drop down, and select
Run full analysis:
Code coverage tools
The Diffblue Cover platform calculates its own coverage for the newly added project and making any existing coverage tools redundant. It is recommended that if your project includes code coverage as part of your
testCmd, that you move this to a different command or use the following tweaks to your build command:
Maven projects using Cobertura
-Dcobertura.skip to the project's
testCmd will skip Cobertura coverage instrumentation.
Maven projects using JaCoCo
-Djacoco.skip to the project's
testCmd will skip JaCoCo coverage instrumentation.
gradle test command is accompanied by a coverage reporting task (in the project's
build.gradle file), this can be skipped by adding the
-x coverageTask argument to the testCmd, e.g.
gradle test -x coverageTask