# Quick Start - AWS Codebuild ## Overview This guide explains how to use Diffblue Cover to write tests in AWS Codebuild. 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 that can be accessed by AWS * A basic understanding of AWS Codebuild CI * Permissions to add Codebuild jobs and secret variables. * 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). To integrate Diffblue Cover into your CI pipeline, we will guide you through creating a workflow file that: 1. Builds your project 2. Downloads and activates Diffblue Cover CLI 3. Runs Diffblue Cover to create tests 4. Commits the created tests to a branch The following sections provide more details for each of the above steps. ## 1. Building the project Create a new build project and select the source to be your Git repository (in this example we'll be using GitHub). Add a new phase to build your project. Make sure to check, and if necessary modify, the command to build your project. Running the project’s tests is not required, and you will save time by skipping them, but they do need to compile and pass. ```yaml version: 0.2 phases: install: commands: - mvn --batch-mode --no-transfer-progress clean install -DskipTests ``` ## 2. Downloading and activating Diffblue Cover CLI You need to give the CI run access to the Diffblue Cover files and activate the `dcover` license in order to write tests. This guide assumes that you have a URL with the Diffblue Cover CLI release zip and the license key for online activation during the CI run - see [Installation](/features/cover-pipeline/cover-pipeline-for-ci/installing-diffblue-cover-in-your-ci-environment.md). If your license allows it you may wish to install Diffblue Cover with offline activation - see [Licensing](/get-started/licensing.md). Create a new secret in the secret manager called `DIFFBLUE_COVER_URL` and set the value to the URL of the Diffblue Cover CLI release zip file. Add a second secret with the name `DIFFBLUE_COVER_LICENSE_KEY` and set the value to your Diffblue Cover license key. Make sure that the service role you assigned to this project has access to these secrets. To do this create a new IAM policy and assign it to your service role. Append the code for getting, unzipping, and activating `dcover` to your workflow file, replacing the strings with the ARNs for the corresponding secrets you created. ```yaml env: secrets-manager: DIFFBLUE_COVER_URL: "COVER_URL_ARN_HERE" DIFFBLUE_COVER_LICENSE_KEY: "COVER_LICENSE_KEY_ARN_HERE" ``` ```yaml build: commands: - 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:$PWD - cd .. - dcover activate "$DIFFBLUE_COVER_LICENSE_KEY" ``` This will put the Diffblue Cover files into the `dcover` directory in the root of the workspace. The Diffblue Cover files contain a script to invoke `dcover` which has the relative path `dcover/dcover`. Add this to your path so that you can call Diffblue Cover as `dcover` (or `dcover.bat`). Push the changes so this workflow runs - ensure that you can see the successful activation of `dcover` before moving on. If your Diffblue Cover did not successfully activate, please see [Licensing](/get-started/licensing.md) or contact [Diffblue Support](https://www.diffblue.com/support). ## 3. Running Diffblue Cover CLI to create tests Now that Diffblue Cover is running in AWS Codebuild, you can use it to write tests. Append the following to your workflow file. Note that the `--batch` option makes the output more suitable for CI, as it ensures the CI logs are not cluttered with progress bar output. ```yaml - dcover create --batch ``` Push the changes so this workflow runs. Once successfully complete, you should expect to see output that looks like this: ```sh INFO Found 7 callable methods in 2 classes INFO INFO Creating tests: INFO --------------- ... INFO All 5 created tests were successfully validated. ``` If you don't see this output, the call may need small modification for your project or dependencies adding until it works. The output gives you warnings along the way to guide you. See CLI Commands for more information. Depending on the size of your module/project, creating tests could take a while. You may wish to restrict test creation to a single class by specifying its fully qualified name: ```bash dcover create com.somepackage.SomeClass --batch ``` ## 4. Committing the created tests to a branch To see these new tests in the project repository you'll need to commit them and push back to the repository. You'll need to configure Git credentials to commit. We recommend creating a service account for this. ```yaml - git config --global user.email "db-ci-bot@yourorg.com" - git config --global user.name "db-ci-bot" - git remote set-url origin https://db-ci-bot:$GH_TOKEN@github.com/yourorg/yourproject.git - git add **/*DiffblueTest.java - git commit --message "Update Unit Tests for $(git rev-parse --short HEAD)" - git push origin ``` As this project was cloned using https we must add our credentials to the origin URL - to do this you must add a third secret in the secret manager for the GitHub token. ```yaml env: secrets-manager: GH_TOKEN: "GH_TOKEN_ARN_HERE" ``` Please note - be careful not to create an infinite CI loop here. This is because pushing a commit with updated tests will re-trigger the pipeline. To avoid this becoming a loop we recommend checking the author of each commit to ensure you are not creating tests for a commit authored by your Diffblue service account. This can be done by appending the following line to the start of all three jobs making sure to replace "db-ci-bot" with the name of your service account. ```yaml - | if [ "$(git rev-list -1 --author='^(?!db-ci-bot).*$' --perl-regexp HEAD --no-merges)" = "$(git rev-list HEAD -1 --no-merges)" ]; then ... git push origin ... fi ``` --- # 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/features/cover-pipeline/cover-pipeline-for-ci/quick-start-guide-aws.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.