# Quick Start - General ## Overview This guide explains how to use Diffblue Cover to write tests for your project as part of a CI pipeline. It outlines the basic commands that you will need to add to your CI scripts. We also have dedicated quick start guides for the most common CI tools, such as GitHub Actions or Jenkins. This guide assumes that you have: * A Maven or Gradle project that: * Compiles * Does not have non-compiling or failing tests * Is stored in a git repository with any CI tool enabled * A basic understanding of your chosen CI tool * The ability to configure environment variables for your CI tool. * Diffblue Cover stored in the cloud for download along with the license key. See [Installation](/features/cover-pipeline/cover-pipeline-for-ci/installing-diffblue-cover-in-your-ci-environment.md). {% hint style="info" %} The rest of this guide assumes that you already have your project set to build (and test) in a CI environment. Typically, this would be a script that downloads your project from the repository, builds the project, and performs testing/checking. The steps below are to incorporate Diffblue Cover into this CI pipeline. If you are starting from scratch, you should do the above first to save trying to understand and configure your project and Diffblue Cover concurrently. {% endhint %} To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a CI script that adds the following to change request push events: 1. Downloads Diffblue Cover CLI 2. Configures the Diffblue Cover environment 3. Runs Diffblue Cover to: * build the project * create tests * commit the created tests * push the tests back to the repository Additionally this guide describes how to configure Diffblue Pipeline to integrate with Diffblue Cover Reports to upload coverage information. Report generation and upload should be performed on merge events, or on a regular basis (e.g. nightly). The following sections provide more details for each of the above steps. ## 1. Downloading Diffblue Cover CLI Note that this section should be added into any step where you required Diffblue Cover CLI; this includes both writing tests and generating reports. You need to give the CI runner access to the Diffblue Cover files in order to write tests. This guide assumes that you have a URL with the Diffblue Cover CLI release zip referred to as `DIFFBLUE_COVER_URL`. For example, the latest release of Diffblue Cover CLI can be found at . ```bash mkdir -p "~/dcover" cd "~/dcover" curl --silent --show-error --location --output "diffblue-cover-cli.zip" "$DIFFBLUE_COVER_URL" unzip -q "diffblue-cover-cli.zip" rm -f "diffblue-cover-cli.zip" PATH=$PATH:~/dcover/ ``` {% hint style="info" %} Diffblue Cover CLI docker images are also available for various JDK versions. These are available on [Docker Hub](https://hub.docker.com/r/diffblue/cover-cli). {% endhint %} ## 2. Configuring the Diffblue Cover Environment Note that this section should be added into change request push events in your CI work flows. This section[^1] describes the main configuration information required to enable Diffblue Cover CLI to perform in a CI environment. This guide uses environment variables in the configuration as these are most suited for CI environments, however many environment variables can also be configured (or even overridden) with command line options. In addition to the common options here, many other options can be specified for CI, or for tuning Diffblue Cover in general. Further details of these can be found in [Commands & Arguments](/features/cover-cli/commands-and-arguments.md). Note that Diffblue Cover Pipeline is designed to write tests in either a patch mode or a baseline mode. * Patch mode generates tests for code changes on the branch compared to the specified base (branch or commit). * Baseline mode will write tests for all the code. Patch mode is best suited for being run on incremental changes such as change requests or merges into a repository with existing Diffblue Cover generated tests. Baseline mode is used for writing initial Diffblue Cover generated tests, or refreshing tests after a major change or version upgrade (e.g. of Diffblue Cover). ### License Configuration The `DIFFBLUE_LICENSE_KEY` environment variable should contain the Diffblue Cover license key. For further license options including offline licensing see [Licensing](https://docs.diffblue.com/get-started/licensing). ### Git Configuration Diffblue Cover Pipeline integrates with git to write appropriate tests and to add these to your repository. This requires credentials to access git history, make commits, and push. The following environment variables are those that grant access to Diffblue Cover, however if these are not specified Diffblue Cover CLI will attempt to invoke git commands and assume git credentials already exist in the environment.
Environment variableNotes
DIFFBLUE_ACCESS_TOKENThe git credentials access token. This should give the user permissions to pull and push to the git repository.
DIFFBLUE_ACCESS_TOKEN_NAMEThe name of the access token.
DIFFBLUE_COMMIT_AUTHORThe author name that Diffblue Cover Pipeline will use in the git repository.
DIFFBLUE_COMMIT_EMAILThe email that Diffblue Cover Pipeline will use in the git repository.
### Branch Configuration Diffblue Cover Pipeline runs on a branch and commit/push the tests before merging into the main branch of the repository. The branch configuration determines what code tests are written for and where the tests are committed. The following environment variables are most commonly used to configure the git branch. Please note the following. * If `DIFFBLUE_HEAD_BRANCH` is not specified then the current branch will be used. * If neither `DIFFBLUE_BASE_BRANCH` nor `DIFFBLUE_BASE_SHA` are specified then Diffblue Cover will run in Baseline mode (see [#mode-configuration](#mode-configuration "mention")).
Environment variableNotes
DIFFBLUE_HEAD_BRANCHThe git name of the branch that the tests will be written for and committed to.
DIFFBLUE_BASE_BRANCHThe name of the branch the change request (or DIFFBLUE_HEAD_BRANCH) was forked from.
DIFFBLUE_BASE_SHAThe SHA of the latest commit before this branch was forked.
DIFFBLUE_REPOSITORY_URLThe full path to the git remote repository (if not specified, this will be read from the local git configuration).
### Mode Configuration The default behavior for Diffblue Cover Pipeline is Patch mode, where code changes between the base and the head are detected and tests written for these code changes. The following environment variables can be set to `true` to change the behavior of Diffblue Cover Pipeline.
Environment variableNotes
DIFFBLUE_BASELINE_MODEWhen set to true this will configure Diffblue Cover to write tests for the whole project, not just changes local to this branch. This is best used when setting up a new project, or with major changes in the code or version of Diffblue Cover.
DIFFBLUE_SKIP_CIWhen set to true this will configure Diffblue Cover to exit with a success return code while performing no further actions.
DIFFBLUE_SKIP_PUSHWhen set to true this will configure Diffblue Cover to not push changes back to the repository; they will still be committed locally.
## 3. Running Diffblue Cover Pipeline Note that this section should be added into change request push events in your CI work flows. The command to invoke Diffblue Cover is as follows ``` dcover ci activate build validate create ``` This will: * `dcover` : Start Diffblue Cover. * `ci` : Enable CI behavior and git integration using environment configuration described above. * `activate` : Activate your Diffblue Cover license locally for use in CI. * `build`: Build the project using standard maven or gradle commands.\ Note that the `build` argument can be omitted and the project built before running Diffblue Cover. This is advisable if the project has non-trivial build configuration or specification. * `validate` : Validate existing Diffblue Cover tests and ensure they are updated. * `create` : Create tests as per the mode configuration. For more details on these commands and their tuning with various arguments see [Commands & Arguments](/features/cover-cli/commands-and-arguments.md). ## Integrating with Diffblue Cover Reports Note that this section should be added into change merge events in your CI workflows, or alternatively on a regular job such as a nightly or weekly build. The prerequisites for this are the [#id-1.-downloading-diffblue-cover-cli](#id-1.-downloading-diffblue-cover-cli "mention") , [#ci-environment-configuration](#ci-environment-configuration "mention") and [#license-configuration](#license-configuration "mention")sections above. Diffblue Cover CLI can generate coverage reports for your project and upload them to your instance of Cover Reports. This is done with the following command ``` dcover coverage-reports upload ``` This will: * `dcover` : Start Diffblue Cover. * `coverage-reports` : Create the coverage reports bundle to send to Reports * `upload` : Upload the created reports bundle to the Reports server where`` is the URL of Cover Reports where the bundle will be uploaded. Note that generating coverage reports should be performed as a separate step/action after test creation. Diffblue created tests should be committed before the upload, ensuring that the data in Cover Reports is associated with the commit which adds these tests. {% hint style="info" %} It is possible to chain `coverage-reports upload` to the `dcover ci` command above, but this is not recommended except on the merge-pipeline that runs on the main branch (as opposed to the pipeline that runs on a feature branch). Cover Pipeline is primarily used to create tests focused on recently changed source files, but can also be used with a **Diffblue Cover: Baseline** label in order to create / refresh the full baseline tests suite. Cover Reports is primarily used to report on the full baseline test suite and so this recommended integration automatically skips generating and uploading reports unless running with the **Diffblue Cover: Baseline** label {% endhint %} {% hint style="info" %} Cover Reports must be installed on a server that is accessible from the CI runner. {% endhint %} For more details on these commands and their tuning with various arguments see [Cover Reports Contributor](/features/cover-reports/cover-reports-contributor.md) [^1]: section? --- # 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.diffblue.com/features/cover-pipeline/cover-pipeline-for-ci/quick-start-guide-general.md?ask= ``` 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.