# Module 1: Create your Cover unit test baseline

In this module, we will enable you to perform the first steps of onboarding a new project. These are:

1. make your first projects Cover-ready by validating the build configuration with respect to unit testing, and
2. write a test baseline for your first projects

### Prerequisites

To start this module, you need to satisfy the [prerequisites](/evaluation-and-onboarding/jumpstart/prerequisites-for-onboarding.md), which amount to having Cover installed at least to the level of [Reference Deployment 1](/get-started/reference-deployments.md#reference-deployment-1-no-ci-cd-system-available), i.e.

* [Cover Reports is installed](/get-started/diffblue-learning/test-coverage/cover-reports-administrator.md) 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.

### License activation

[Activate Cover CLI ](https://cover-docs-preview.diffblue.com/evaluation-and-onboarding/jumpstart/phase-1-up-and-running/pages/iwOfddKGyABv89Iog4UY#id-2.-apply-a-license)using the license key that you received from the contact for software and license distribution in your organization:

```
dcover activate XXXX-XXXX-XXXX-XXXX
```

View your license details to check that the activation was successful:

```
dcover license
```

### Telemetry configuration

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)

[Telemetry is configured](/features/cover-plugin/cover-plugin-admin/telemetry.md) 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.

### Make your project Cover-ready

We will work through the whole flow for creating baseline tests.

{% hint style="info" %}
You can find a worked example of the entire flow [here](#worked-example-baseline-creation-process-using-the-petclinic-demo-project).
{% endhint %}

{% hint style="info" %}
If your project has multiple modules we recommend that you start with a representative module. Once the selected module is working, repeat the steps on the other modules.

Note that you can run a specific module without changing your working directory by adding the following option to the `dcover` commands: [`--working-directory`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#working-directory) `your-selected-module`
{% endhint %}

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.

<table><thead><tr><th width="242">Step</th><th>Command</th></tr></thead><tbody><tr><td><strong>1. Build the project from its root</strong></td><td>E.g. <code>./mvnw install -DskipTests</code></td></tr><tr><td><strong>2. Check and fix the project environment</strong></td><td><p><code>dcover create</code> <a href="/pages/0A3dPGLMragBjW8cL0xL"><code>--preflight</code></a></p><p><code>dcover</code> <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#refactor"><code>fix-build</code></a></p><p>If necessary, apply manual fixes to your build configuration</p></td></tr><tr><td><strong>3. Commit fixes</strong></td><td><p>As soon as preflight doesn't report any errors or warnings:</p><p><code>git checkout -b diffblue-baseline</code></p><p><code>git commit -a -m "Build configuration fixes for Diffblue"</code></p></td></tr><tr><td><strong>4. Measure and upload existing coverage</strong></td><td><p><code>dcover</code> <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#generate-reports-bundles"><code>coverage-reports</code></a></p><p><code>dcover</code> <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#upload-reports-bundles"><code>upload</code></a> <code>http://your-cover-reports:8080</code></p><p>View Cover Reports</p></td></tr></tbody></table>

### Create your unit test baseline

We are now ready to create the baseline tests.

<table><thead><tr><th width="242">Step</th><th>Command</th></tr></thead><tbody><tr><td><strong>5. Create the baseline tests and measure coverage</strong></td><td><code>dcover</code> <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#create-tests"><code>create</code></a> <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#coverage-reports"><code>--coverage-reports</code></a></td></tr><tr><td><strong>6. Commit the baseline tests</strong></td><td><p><code>git add `find . -name '*DiffblueTest.java'`</code></p><p><code>git commit -m "Diffblue baseline tests"</code></p></td></tr><tr><td><strong>7. Upload the baseline coverage</strong></td><td><code>dcover</code> <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#upload-reports-bundles"><code>upload</code></a> <code>http://your-cover-reports:8080</code></td></tr><tr><td><strong>8. Review results</strong></td><td><p>View Cover Reports</p><p>View created tests in IntelliJ</p></td></tr><tr><td><strong>9. Push the changes</strong></td><td><p><code>git push --set-upstream origin diffblue-baseline</code></p><p>Create a pull request and get it merged.</p></td></tr></tbody></table>

### What does Cover CLI do?

When running a Cover command, the execution proceeds in several phases.

<table><thead><tr><th width="170">Phase</th><th width="299">Description</th><th>Additional execution information</th></tr></thead><tbody><tr><td><strong>Detecting environment</strong></td><td>Every Cover command starts by performing environment health checks to detect whether the project environment is ready for the Cover command to run.</td><td>When using <a href="/pages/0A3dPGLMragBjW8cL0xL"><code>--preflight</code></a>, Cover stops after this phase and outputs an <em>environment summary.</em></td></tr><tr><td><strong>Creating tests</strong></td><td>This phase performs the generation of tests class per class, method per method.</td><td><p>Only executed when using the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#create-tests"><code>create</code></a> command.</p><p>Ends with a <em>summary</em> with number of tests created and issues encountered.</p></td></tr><tr><td><strong>Validating tests</strong></td><td>This phase validates the created tests, i.e. it removes non-compiling and failing tests.</td><td><p>Executed after test generation when using the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#create-tests"><code>create</code></a> command.</p><p>Test validation can also be run separately using the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#the-validate-command"><code>validate</code></a> command.</p></td></tr><tr><td><strong>Calculating coverage</strong></td><td>This phase calculates the coverage of manually written and Diffblue tests using JaCoCo.</td><td><p>Executed when passing the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#coverage-reports"><code>--coverage-reports</code></a> option to the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#create-tests"><code>create</code></a> command.</p><p>Coverage reports can also be generated separately using the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#generate-reports-bundles"><code>coverage-reports</code></a> command.</p></td></tr><tr><td><strong>Upload to Cover Reports</strong></td><td>This phase uploads the coverage reports to Cover Reports.</td><td>Executed when running the <a href="https://docs.diffblue.com/features/cover-cli/commands-and-arguments#upload-reports-bundles"><code>upload</code></a> command.</td></tr></tbody></table>

### Understanding Cover's log output

Cover produces output with increasing degree of detail:

* Console output
* Console output with [`--verbose`](/features/cover-cli/commands-and-arguments.md#verbose)
* [User log file](/features/cover-cli/cover-cli-admin/log-files.md#user-logs)
* [Support log file](/features/cover-cli/cover-cli-admin/log-files.md#support-logs)

The log files are in the `.diffblue/log` directory below the directory from where Cover was run.

### Overview of CLI options

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](/features/cover-cli/commands-and-arguments.md).

* Select module to run on without changing directory, e.g. [`--working-directory`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#working-directory) `my-module/my-submodule`
* Exclude modules, e.g. [`--exclude-modules`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#exclude-modules) `my-module/to-exclude`
* Verbose console output: [`--verbose`](/features/cover-cli/commands-and-arguments.md#verbose)
* Prefer Maven over Gradle: [`--maven`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#maven)
* Test framework, e.g. [`--test-framework`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#test-framework) `junit-4`
* Active Spring profiles, e.g. [`--active-profiles`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#active-profiles) `test`
* Ignore style checks: [`--ignore-stylechecks`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#ignore-stylechecks)
* System properties, e.g. [`-D`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#define)`my.property=value`
* Environment variables, e.g. [`--environment`](https://docs.diffblue.com/features/cover-cli/commands-and-arguments#environment) `MYVAR=value`
* CLI help: `dcover help create`

Cover automatically figures out which entry point methods to write tests for. The set of methods can be restricted by [specifying inclusions and exclusions](https://docs.diffblue.com/features/cover-cli/commands-and-arguments/packages-classes-and-methods). E.g. to write tests only for the `OwnerController` class you can run `dcover create org.springframework.samples.petclinic.owner.OwnerController`

### What does Cover do during test generation?

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

### Understanding Cover's output codes

Output codes identify the [messages that Cover outputs](/features/output-codes.md), e.g. E052 - Missing dependency

The output code can be used to quickly look it up in docs: e.g. <https://diff.blue/E052>

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)

### What does test validation do?

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

### Coverage measurement

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.

### How to ask for support

Before reaching out, check for potential solutions in

* [the documentation](https://docs.diffblue.com)
* and [the forum](https://forum.diffblue.com)

More complex questions & issues [contact support depending on your support plan](https://www.diffblue.com/support/).

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 [*support log file*](/features/cover-cli/cover-cli-admin/log-files.md#support-logs)
  * Additionally, for [R code](/features/output-codes/r-reason-codes.md)-related questions, one of the following:
    * A *reproducer* (most valuable to be able to support): a piece of code that results in the the R code message that you see
    * A *code snippet* of the relevant code under test (useful, but with lower chances of success) and a [*partial test*](/features/cover-cli/writing-tests/partial-tests.md) (if there is one) with the R code

### Worked example: Baseline creation process using the Petclinic demo project

The prerequisites for running this example are:

* JDK 17 has been installed.
* [Cover Reports has been downloaded, unpacked locally](/get-started/diffblue-learning/test-coverage/cover-reports-administrator.md), and started by running `bin/cover-reports`
* The demo project has been cloned by running `git clone` [`https://github.com/diffblue/demo-spring-petclinic`](https://github.com/diffblue/demo-spring-petclinic)
* To use the `dcover fix-build` command in step 2, [these prerequisites](/get-started/specs-and-reqs.md#cover-refactor) must be met.

We will work through the whole flow for creating baseline tests.

<table><thead><tr><th width="242">Step</th><th>Command</th></tr></thead><tbody><tr><td><strong>1. Build the project from its root</strong></td><td><code>./mvnw install -DskipTests</code></td></tr><tr><td><strong>2. Check and fix the project environment</strong></td><td><p><code>dcover create --preflight</code></p><p><code>dcover fix-build</code></p></td></tr><tr><td><strong>3. Commit fixes</strong></td><td><p><code>git checkout -b diffblue-baseline</code></p><p><code>git commit -a -m "Build configuration fixes for Diffblue"</code></p></td></tr><tr><td><strong>4. Measure and upload existing coverage</strong></td><td><p><code>dcover coverage-reports</code></p><p><code>dcover upload http://localhost:8080</code></p><p><a href="http://localhost:8080">View Cover Reports</a></p></td></tr><tr><td><strong>5. Create the baseline tests and measure coverage</strong></td><td><code>dcover create --coverage-reports</code></td></tr><tr><td><strong>6. Commit the baseline tests</strong></td><td><p><code>git add `find . -name '*DiffblueTest.java'`</code></p><p><code>git commit -m "Diffblue baseline tests"</code></p></td></tr><tr><td><strong>7. Upload the baseline coverage</strong></td><td><code>dcover upload http://localhost:8080</code></td></tr><tr><td><strong>8. Review results</strong></td><td><p><a href="http://localhost:8080">View Cover Reports</a></p><p>View created tests in IntelliJ</p></td></tr><tr><td><strong>9. Push the changes</strong></td><td>We skip this step for the demo project.</td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://cover-docs-preview.diffblue.com/evaluation-and-onboarding/jumpstart/phase-1-up-and-running/module-1-create-your-cover-unit-test-baseline.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.