Get started - Cover Reports
Get started with Diffblue Cover Reports - in short, check the prerequisites, download and install Cover Reports, create and upload a reports bundle, and finally, visualize your coverage data.
Cover Reports is a server-side tool accessed via a web browser - Chrome, Edge, Safari, or Firefox. Cover CLI and/or Cover Pipeline are used to create and upload coverage data - Cover Reports is used to visualize that data. This getting started topic focuses on Cover CLI - for information on using Cover Reports with Cover Pipeline see Cover Pipeline.
Prefer video? No problem. Check out our getting started video.
Client workstation:
- Diffblue Cover CLI
- JaCoCo 0.8.3+
- The latest version of Chrome, Edge, Safari, or Firefox with a screen resolution of 1920 x 1080 or higher.
- Network connectivity between the user's workstation and the Cover Reports server.
Server hosting Cover Reports:
- Docker Engine 20.10.17
- Docker Compose v2.10.2
- Network connectivity between the server and client workstations.
- Internet connection if using Docker Hub for install.
Archive file
Docker Hub
- 1.Using the link provided by Diffblue, download the Cover Reports
.tar.gzfile (e.g.diffblue-cover-reports-2023.07.02.tar.gz) to the server you plan to use to host Cover Reports. Contact Diffblue Support if you don't have the download link. - 2.From the directory containing the Cover Reports
.tar.gzfile, load the Docker bundle:
docker load -i /path/diffblue-cover-reports-<version>.tar.gz
- 3.In your shell, navigate to your preferred install directory (we'll now refer to this as
$COVER_REPORTS_HOME). Using the link provided by Diffblue, download the Cover Reports Docker Compose filedocker-compose.ymlto$COVER_REPORTS_HOME. Contact Diffblue Support if you don't have the download link. - 4.From the
$COVER_REPORTS_HOMEdirectory, start Cover Reports:
docker compose up -d
- 5.Finally, open a browser on a client PC that has access to the Cover Reports server and navigate to the Cover Reports Home Page (
<HOSTURL>:8080).
- 1.To access the repository please sign up to Docker Hub and provide Diffblue Support with your username. Diffblue Support will grant access according to your subscription terms.
- 2.In your shell (from the server you plan to use to host Cover Reports), log in to Docker Hub using the
docker logincommand with either your username and password or username and Docker Hub Access Token, for example:
docker login -u <username> <password_or_token>
- 3.In your shell, navigate to your preferred install directory (we'll now refer to this as
$COVER_REPORTS_HOME). Using the link provided by Diffblue, download the Cover Reports Docker Compose filedocker-compose.ymlto$COVER_REPORTS_HOME. Contact Diffblue Support if you don't have the download link. - 4.From the
$COVER_REPORTS_HOMEdirectory, start Cover Reports:
docker compose up -d
- 5.Finally, open your browser and navigate to the Cover Reports Home Page (
<HOSTURL>:8080).
Use Cover CLI to create a coverage data file for your project - this is referred to as a "reports bundle". You can do this on your own project, or you can use the example PetClinic Spring project that's used as part of the Get started - Cover CLI topic.
Note that, to save you a little time, there's a demo project provided as part of Cover Reports so you can click
Open Demo Project from the Reports splash screen and skip this Cover CLI step. If you or your organization have already used Cover Reports, this option won't be available.cd demo-spring-petclinic
dcover create --coverage-reports
--report http://my-cover-reports-service
--project "PetClinic"
--name "PC-2023-08-14/feature-F12345"
The optional arguments used with
dcover create perform the following:--coverage-reportsis used create the coverage data files using Cover and JaCoCo.--reportis used to define the URL to upload the reports bundle to - i.e. the URL for Cover Reports server install. Note that HTTPS direct is currently not supported.--projectis used to define a project name to upload to. This is essential as otherwise the project is simply named as "Anonymous Project".--nameis used to define a name for the specific upload. We suggest a useful and consistent naming convention making your coverage data uploads more useful over time.
Now the fun bit - taking a look at your coverage data. We won't cover the whole UI here, but here are a few basics to get you started:
Projects & Dashboards
Overview Tab
Map Tab
Coverage Tab
- Home - list view: Click the Cover Reports logo (or the Home icon in the project path) to view your project list. Click a line item (project, sub-project, package, etc) to view the coverage data.
- Menu - structure view: As you'd expect, your projects are organised and displayed in a standard tree structure and you can navigate through your projects, sub-projects, packages, classes, and methods as needed. The coverage data visible from the dashboards reflects the current selected component..
- Dashboards - data view: Three main dashboards/tabs are available for data visualization (for more detailed info click the tabs above):
- Overview: An overview/summary of coverage data for your project/project component.
- Map: A coverage heat map for your project/project component. Click an item to drill down further through your project structure.
- Coverage Detail: A detailed coverage breakdown.
- Runs - versions: As you create and upload coverage data over time, use the
Latest Rundrop-down to select what data to view.
Overview Tab - an overview/summary of coverage data for your project/project component. Here's a quick breakdown of the panels and the terminology used for the data.
- Project Overview - the four key data stats.
- Diffblue Coverage - coverage (percentage) provided by all Diffblue Cover Tests.
- Total Coverage - total coverage (percentage) provided by Diffblue Cover Tests and/or Manual Tests (existing developer written tests).
- Lines of Code - total lines of code for the selected project component.
- Diffblue Tests - total number of tests created by Diffblue Cover.
- Coverage Sources & Run Coverage Summary - a more detailed breakdown.
- By manual tests only - percentage or LOC (Lines of Code) covered exclusively by Manual Tests only (existing developer written tests).
- By Diffblue tests only - percentage or LOC (Lines of Code) covered by exclusively by Diffblue Cover Tests only.
- By Diffblue and manual tests - percentage or LOC (Lines of Code) covered by Diffblue Cover Tests and Manual Tests (existing developer written tests) - i.e. this is the overlap of the two types of test.
- Not tested, Untestable, Trivial - percentage or LOC (Lines of Code) that Diffblue Cover was unable to write tests for. In many cases this is due to issues such as private methods, empty methods, trivial setters and getters, etc. You can use the
Coverage Detailtab to get more detailed information (output codes) but that's a topic for later - see Output Codes.
Map Tab - a coverage heat map for your project/project component. Click an item to drill down further through your project structure.
Coverage Detail Tab - a detailed coverage breakdown. Here's a quick breakdown of the panels and the terminology used for the data.
- Project Coverage Detail - output codes (see note below) generated by this run of Diffblue Cover (and total lines of code associated with each).
- Run Coverage Detail - a full breakdown of your project components.
- Lines of Code - total lines of source code associated with the project component.
- Manual Coverage - percentage coverage provided by all Manual Tests (existing developer written tests).
- Diffblue Coverage - percentage coverage provided by all Diffblue Cover Tests.
- Total Coverage - total coverage (percentage) provided by Diffblue Cover Tests and/or Manual Tests (existing developer written tests).
Note - Output Codes: Diffblue Cover performs a number of checks before, during, and after creating unit tests. Cover can generate a range of output codes during these checks to provide general information and highlight any issues. See Output Codes for more details.
Now you're up and running with Cover Reports, use Cover CLI to create reports bundles for your own projects and start to build your data sets over time. In general, Cover Reports is pretty straightforward to use, especially from a UI perspective, but check out the Cover Reports topic for more details on using Cover Reports.
Last modified 23d ago