CI/CD Integration Plugin
Overview#
The CI/CD integration plugin offers a wide range of capabilities and is available for both Gradle and Maven.
All these functions are provided under a single tool because they are related to tasks executed within Maven or Gradle.
Features#
CI/CD Integration Plugin functions include:
Downloading and configuring agents:
- Application agent - to capture unit tests coverage
- Test agent - to capture metadata for tests launches (such as runner, test name and result)
Generating change testing reports:
- With a command - useful to call on branch push event.
- On GitHub Pull Request
- On GitLab Merge Request
Sending Git metadata to Drill4J API - to supply Drill4J with commit information (date, hash, author) from which a particular application version is built.
How to use#
The general gist of using the CI/CD integration plugin is:
- Add the plugin to your Maven or Gradle configuration.
- Configure the agents (for application, for tests)
- Use commands provided by CI/CD Integration Plugin and integrate it with your CI/CD scripts
The exact configuration files and commands you should use depend on the task at hand. This page provides general reference. For step-by-step guides refer to Integration Guides section (see documentation sidebar at the top of the page).
Adding plugin#
This section describes how to add CI/CD integration plugin to your project.
Gradle#
- Add the following to Gradle build file
pluginssection:
plugins {id("com.epam.drill.integration.cicd") version "0.1.11"}
- Set Drill4J API address and API key
- Option 1 (recommended): using environment variables.
- Option 2 (not recommended): using Gradle build file.
- Option 1 (recommended): using environment variables.
Maven#
- Add the Drill4J CI/CD integration plugin to
<build>section of pom.xml file:
<build><plugins><plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration></configuration></plugin></plugins></build>
- Set Drill4J API address and API key
- Option 1 (recommended): using environment variables.
- Option 2 (not recommended): using Maven configuration file.
- Option 1 (recommended): using environment variables.
<build><plugins><plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Set API url and API key --><apiUrl>http://localhost:8090/api</apiUrl><apiKey>your_api_key_here</apiKey></configuration></plugin></plugins></build>
Test Agent#
Enables Drill4J to map tests to coverage and vice versa. For more details on this feature and its purpose, see the Test Agent reference page.
Set up#
Prerequisite - CI/CD integration plugin added to project
Gradle#
To enable the Drill4J Test Agent to Gradle project add the following:
drill {// groupId is a required parameter to run test agentgroupId = "my-group"enableTestAgent {version = 0.23.10}}
Note, that Test Agent will automatically launch for every Gradle test task. If you need to disable Test Agent for specific tasks, refer to this section
Maven#
To enable the Drill4J Test Agent to Maven project add the following to pom.xml:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- groupId is a required parameter to run test agent --><groupId>my-group</groupId><testAgent><version>0.23.10</version></testAgent></configuration><!-- adds enableTestAgent goal --><executions><execution><goals><goal>enableTestAgent</goal></goals></execution></executions></plugin>
Note, that Test Agent will automatically launch for every Maven test goal. If you need to disable Test Agent for specific goals, refer to this section
Disable for specific task#
By default, the Test Agent will launch for every Gradle task and Maven goal. To disable the Test Agent for specific tasks/goals, follow the steps below:
Gradle#
Add the following to configuration of test task:
Maven#
There is no way to disable Test Agent for specific Maven goal while keeping it for all others.
Instead you can create dedicated Maven profile for both CI/CD Integration Plugin and Test Agent configuration:
<profiles><profile><!-- profile name, it is totally arbitrary --><id>profileWithTestAgent</id><activation><activeByDefault>false</activeByDefault></activation><build><plugins><plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><executions><execution><goals><goal>enableTestAgent</goal></goals></execution></executions></plugin></plugins></build></profile></profiles>
This way Test Agent will only launch when the respective profile is launched.
Agent files download source#
There are 3 ways to specify where CI/CD plugin should load agent from:
- Automatic download by version tag - the default option.
- Custom URL download - arbitrary URL to ZIP release.
- Local path to ZIP release - local path to ZIP release.
Automatic download#
To enable automatic download specify version parameter with concrete version. See list of available versions on Test Agent GitHub repository releases page.
NOTE: GitHub API has rate limits for unauthenticated downloads. To increase these limits, set the
GH_USER_TOKENenvironment variable.
Gradle#
enableTestAgent {version = "0.1.11"}
Maven#
<testAgent><version>0.1.11</version></testAgent>
Custom URL download#
To download the Test Agent from a custom URL, set the downloadUrl parameter to the desired link:
Gradle#
Maven#
Local path to ZIP release#
To use a locally available Test Agent, set the zipPath parameter to the path of the local zip archive:
Gradle#
Maven#
Disable test tracing#
By default, the Test Agent will trace all tests executed in Gradle or Maven. This lets you measure the coverage of each individual test, but it also generates a large amount of data. If you only need the overall coverage for an entire test session rather than for each test - you can disable test tracing.
To disable test tracing, set the testTracingEnabled parameter to false in the Test Agent configuration:
Gradle#
Maven#
Disable sending test metadata#
By default, the Test Agent sends test launch metadata (test names, test results, test duration, etc.) to the Drill4J backend. This metadata is used to provide detailed test reports and recommendations.
If you want to disable this feature, set the testLaunchMetadataSendingEnabled parameter to false in the Test Agent configuration:
Gradle#
Maven#
Application Agent#
Enables Drill4J to collect coverage for application classes. See the Application Agent reference page for more details.
Set up#
Prerequisite - CI/CD integration plugin added to project
Gradle#
To enable the Drill4J Application Agent to Gradle project add the following:
drill {// Enter appropriate parameter valuesgroupId = "my-group"appId = "my-application"// Specifies the java packages for Drill4J to monitor// Use "/" separator for package name partspackagePrefixes = "my/awesome/application"// Optional, identifies app version built from checked out commitbuildVersion = "1.0.0"enableAppAgent {version = "0.9.12"}}
Note, that Application Agent will automatically launch for every Gradle exec task. If you need to disable Application Agent for specific tasks, refer to this section
Maven#
To enable the Drill4J Application Agent to Maven project add the following to pom.xml:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Enter appropriate parameter values --><groupId>my-group</groupId><appId>my-application</appId><!-- Specifies the java packages for Drill4J to monitor --><!-- Use "/" separator for package name parts --><packagePrefixes>my/awesome/application</packagePrefixes><!-- Optional, identifies app version built from checked out commit --><buildVersion>1.0.0</buildVersion><appAgent><version>0.9.12</version></appAgent></configuration><!-- adds enableAppAgent goal --><executions><execution><goals><goal>enableAppAgent</goal></goals></execution></executions></plugin>
Note, that Application Agent will automatically launch for every Maven test goal. If you need to disable Application Agent for specific goals, refer to this section
Disable for specific task#
By default, the Application Agent will launch for every Gradle task and Maven goal. To disable the Application Agent for specific tasks/goals, follow the steps below:
Gradle#
Add the following to configuration of test task:
Maven#
There is no way to disable Application Agent for specific Maven goal while keeping it for all others.
Instead you can create dedicated Maven profile for both CI/CD Integration Plugin and Application Agent configuration:
<profiles><profile><!-- profile name, it is totally arbitrary --><id>profileWithAppAgent</id><activation><activeByDefault>false</activeByDefault></activation><build><plugins><plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><executions><execution><goals><goal>enableAppAgent</goal></goals></execution></executions></plugin></plugins></build></profile></profiles>
This way Application Agent will only launch when the respective profile is launched.
Agent files download source#
There are 3 ways to specify where CI/CD plugin should load agent from:
- Automatic download by version tag - the default option.
- Custom URL download - arbitrary URL to ZIP release.
- Local path to ZIP release - local path to ZIP release.
Automatic download#
To enable automatic download specify version parameter with concrete version. See list of available versions on Application Agent GitHub repository releases page.
NOTE: GitHub API has rate limits for unauthenticated downloads. To increase these limits, set the
GH_USER_TOKENenvironment variable.
Gradle#
enableAppAgent {version = "0.9.12"}
Maven#
<appAgent><version>0.9.12</version></appAgent>
Custom URL download#
To download the Application Agent from a custom URL, set the downloadUrl parameter to the desired link:
Gradle#
Maven#
Local path to ZIP release#
To use a locally available Application Agent, set the zipPath parameter to the path of the local zip archive:
Gradle#
Maven#
Test Recommendations#
Drill4J helps to significantly reduce test execution time by providing recommendations on which tests can be skipped because the code they cover has already been tested before.
Set up#
Prerequisites:
- Test agent is enabled.
- Before running the tests, make sure that the application under test is already deployed with the Application Agent enabled.
Gradle#
To enable test recommendations add the following properties to your Gradle build file:
drill {// Group IDgroupId = "my-group"// ID of the application under testappId = "my-application"// Identifies the version of the application under test that is based on the checked out commitbuildVersion = "1.0.0"// Enables Test RecommendationsenableTestRecommendations {coveragePeriodDays = 30 // Optional, sets the period of days for which coverage data is taken into account}// Enables Test AgentenableTestAgent {version = 0.23.10}}
Maven#
To enable test recommendations add the following properties to your Maven pom.xml file:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Group ID --><groupId>my-group</groupId><!-- ID of the application under test --><appId>my-application</appId><!-- Identifies the version of the application under test that is based on the checked out commit --><buildVersion>1.0.0</buildVersion><testRecommendations><!-- Enables Test Recommendations --><enabled>true<enabled><!-- Optional, sets the period of days for which coverage data is taken into account --><coveragePeriodDays>30</coveragePeriodDays></testRecommendations></configuration><executions><execution><goals><!-- Enables Test Agent --><goal>enableAppAgent</goal></goals></execution></executions></plugin>
Disabling recommended tests#
Gradle#
To disable recommended tests, make the following changes to your Gradle file:
enableTestRecommendations {// Optional, disables test recommendationsenabled = false}
Maven#
To disable recommended tests, make the following changes to your Maven file:
<testRecommendations><!-- Disables Test Recommendations --><enabled>false<enabled></testRecommendations>
Comparing with baseline#
Drill4J allows you to run tests only for code that has changed compared to the baseline version. To skip tests for unchanged code, set the baseline version to compare with.
See the Baseline Strategy section for more information.
Gradle#
To set the baseline configuration, add the following properties to your Gradle build file:
drill {// Group IDgroupId = "my-group"// ID of the application under testappId = "my-application"// Identifies the version of the application under test that is based on the checked out commitbuildVersion = "1.0.0"// Set either to SEARCH_BY_MERGE_BASE or SEARCH_BY_TAG. See "Baseline Strategy" section on the page below for more infobaseline {searchStrategy = "SEARCH_BY_TAG"}// Enable Test Recommendations and Test Agent...}
Maven#
Set the <baseline> Drill4J configuration to your Maven pom.xml file:
<configuration><!-- Group ID --><groupId>my-group</groupId><!-- ID of the application under test --><appId>my-application</appId><!-- Identifies the version of the application under test that is based on the checked out commit --><buildVersion>1.0.0</buildVersion><!-- Set either to SEARCH_BY_MERGE_BASE or SEARCH_BY_TAG. See "Baseline Strategy" section on the page below for more info --><baseline><searchStrategy>SEARCH_BY_TAG</searchStrategy></baseline><!-- Enable Test Recommendations and Test Agent -->...</configuration>
Generating a change testing report#
A Change Testing Report provides insights into the code changes that have been tested, allowing you to ensure the quality of newly introduced changes.
For step-by-step integrations guide see:
Gradle#
Add the following properties to your Gradle build file:
To generate the Change Testing Report, execute the following Gradle command:
The report will be saved in the /build/drill-reports/ directory.
Maven#
Add the following properties to your Maven pom.xml file:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Enter appropriate parameter values --><groupId>my-group</groupId><appId>my-application</appId><!-- Set either to SEARCH_BY_MERGE_BASE or SEARCH_BY_TAG. See "Baseline Strategy" section on the page below for more info --><baseline><searchStrategy>SEARCH_BY_TAG</searchStrategy></baseline></configuration><executions><execution><goals><goal>generateChangeTestingReport</goal></goals></execution></executions></plugin>
To generate the Change Testing Report, execute the following Maven command:
The report will be saved in the /target/drill-reports/ directory.
GitHub Pull Request report#
This feature posts a report of the tested changes as a comment on a GitHub Pull Request. It compares the current build with the merge base build of the target branch for the Pull Request.
IMPORTANT! This command can only be executed within a GitHub workflow and requires specific environment variables available only in a GitHub Actions job.
To execute this command, you need to provide a GitHub API token. API token should have following rights:
- repo
- write:discussion
Gradle#
Add the following properties to your Gradle build file:
To leave a comment on a Pull Request, execute the following Gradle command:
Maven#
Add the following properties to the Drill4J plugin configuration in your Maven pom.xml file:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Enter appropriate parameter values --><groupId>my-group</groupId><appId>my-application</appId><github><!-- Enter your GitHub Token --><token>your-github-token-here</token></github></configuration><executions><execution><goals><goal>githubPullRequestReport</goal></goals></execution></executions></plugin>
To leave a comment on a Pull Request, execute the following Maven command:
GitLab Merge Request report#
This feature posts a report of the tested changes as a comment on a GitLab Merge Request. It compares the current build with the merge base build of the target branch for the Merge Request.
IMPORTANT! This command can only be executed within a GitLab CI/CD job and requires specific environment variables available only during GitLab CI/CD execution.
To execute this command, you need to provide a GitLab private token.
Gradle#
Add the following properties to your Gradle build file:
To post a comment on a Merge Request, execute the following Gradle command:
Maven#
Add the following properties to your Maven pom.xml file:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Set appropriate parameter values --><groupId>my-group</groupId><appId>my-application</appId><gitlab><!-- Adjust if running on a private GitLab instance--><apiUrl>https://gitlab.com/api/v4/</apiUrl><!-- Enter your personal token --><privateToken>someToken</privateToken></gitlab></configuration><executions><execution><goals><goal>gitlabMergeRequestReport</goal></goals></execution></executions></plugin>
To leave a comment on a Merge Request, execute the following Maven command:
Sending Git metadata to Drill4J API#
This enables Drill4J to display additional data on build in the reports, such as:
- Build version
- Current commit SHA
- Current commit message
- Commit author
It makes reports more readable and allows to easily associate reports with particular commits.
Gradle#
Add the following parameters to your Gradle build file:
To send the build information to the Drill4J backend, execute the following Gradle command:
Maven#
Add the following parameters to your Maven pom.xml file:
<plugin><groupId>com.epam.drill.integration</groupId><artifactId>drill-maven-plugin</artifactId><version>0.1.11</version><configuration><!-- Set appropriate parameter values --><groupId>my-group</groupId><appId>my-application</appId><!-- Optional, identifies app version built from checked out commit --><buildVersion>1.0.0</buildVersion></configuration><executions><execution><goals><goal>sendBuildInfo</goal></goals></execution></executions></plugin>
To send the build information to the Drill4J backend, execute the following Maven command
Scanning application archive (JAR/WAR/EAR)#
Drill4J automatically scans information about an application's classes and methods when the application is run with the Application agent. However, you can also obtain this information right after building the application — before it is run. You have two ways to do this: either by running the dedicated Gradle/Maven command, or by enabling the corresponding parameter in the plugin configuration.
Run Gradle/Maven command#
To scan the application archive, execute the dedicated Gradle task or Maven goal as described below.
Note, before executing the command, you need to enable the Application agent and build your application.
Gradle#
Execute the following Gradle command:
Maven#
Execute the following Maven command:
Enable scan on build#
Alternatively, you can set up the archiveScannerEnabled parameter to true in the Application Agent plugin configuration.
This case the application archive will be scanned automatically after the build is completed.
Gradle#
Maven#
Baseline strategy#
To generate a Change Testing Report or enable Test Recommendations, the current build must be compared to a baseline build. Drill4J supports multiple strategies for identifying the baseline build.
- Search by tags
- Search by merge base
Search by tags#
This strategy compares the current build to a baseline build identified by Git tags.
IMPORTANT! You need to have at least one Git tag in your repository for this strategy to work.
Gradle#
Maven#
Search by merge base#
This strategy compares the current build to the baseline based on the common ancestor (merge base) of two branches.
Gradle#
Maven#
Troubleshooting#
How to confirm that agents are enabled when running tests?#
Once loaded, the Drill4J agent prints the following ASCII logo in the Gradle/Maven console log:
IMPORTANT! Maven does not print the Drill4J logs by default, you need to add the
-Xparameter to the command line:
Tests do not appear in Drill4J after running in Maven with Java 17#
If you run tests in Maven with Java 17 or higher and see the following message:
You should provide --add-opens option to the JVM argument line in Maven Surefire Plugin:
IMPORTANT! Don't forget to add
@{argLine}to keep Drill4J agents enabled.