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:

login.png

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 - and _. 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.

The 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

git_repository_analysis.png

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 Continue.

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 master the 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.

Clicking 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.

Analysis results

On clicking View results you will be presented with the coverage view:

coverage.png

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 View Test:

test.png

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:

trace.png

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 Execution trace.

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:

differential_update.png

Click 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:

Troubleshooting

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

Adding -Dcobertura.skip to the project's testCmd will skip Cobertura coverage instrumentation.

Maven projects using JaCoCo

Adding -Djacoco.skip to the project's testCmd will skip JaCoCo coverage instrumentation.

Gradle projects

If the 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