Introduction
You can perform analysis and testing by executing the Jtest tasks for Gradle for the main project directory. It is not necessary to build the tested project prior to analysis unless you test a multi-module project. We recommend compiling multi-module projects before running analysis by adding the build
or assemble
task to your command line. Doing so enables Jtest to use artifacts from the local repository, reducing the amount of time necessary to test and analyze code.
In addition, if your project is multi-module, you must execute the tasks for the root project. As a result, Jtest will test or analyze all the subprojects. To test selected subprojects, run the Jtest tasks (jtest
, jtest-agent
, or affectedTests
) for the root project and the Gradle test
task for individual subprojects, see Collecting Coverage for Unit Tests for details.
Running Static Analysis
To perform static analysis on your code:
- Ensure that the Jtest Plugin for Gradle is set up (see Configuring the Jtest Plugin for Gradle).
Execute the jtest task. Your command line may resemble the following:
gradle jtest -I PATH/TO/JTEST/integration/gradle/init.gradle
The Jtest Plugin for Gradle will collect the necessary build data in the .json file, and analyze your code depending on the test configuration you provided.
- Review the analysis results (see Reviewing Results).
By default, test sources are excluded from analysis. To analyze test code, disable the excludeTestSources
option; see Jtest Goals Reference for Gradle.
Executing and Collecting Coverage for Unit Tests
You can include unit test results in the Jtest report by running your tests with the jtest and jtest-agent tasks, and the dedicated Unit Tests
built-in test configuration:
- Ensure that the Jtest Plugin for Gradle is set up (Configuring the Jtest Plugin for Gradle).
Execute Gradle tasks in the following order:
- the jtest-agent task
- thetest
(orbuild
) task to ensure that unit tests are executed
- the jtest task
Your command line may resemble the following:gradle clean jtest-agent test jtest -Djtest.config="builtin://Unit Tests"
By default, Jtest collects coverage data for executed tests. To disable collecting coverage, enable the jtest.coverage.skip
option (see Jtest Tasks Reference for Gradle for details).
It you're testing a multi-module project, Jtest, by default, collects coverage information for all subprojects of the root project. To collect coverage for selected subprojects, modify your command line to execute the Gradle test
task for the subprojects you want to test. Your command line may resemble the following:
gradle clean jtest-agent subproject1:test subproject2:test jtest -Djtest.config="builtin://Unit Tests"
If you skip a test by calling a method from the org.junit.Assume (JUnit 4) or org.junit.jupiter.api.Assumptions (JUnit 5) class, Jtest collects coverage for code lines executed before the method is called. This coverage information is not associated with any test in the coverage report.
Jtest collects test coverage for Gradle multi-module project parallel builds, enabled with the -parallel or --parallel option. For details, see https://docs.gradle.org/current/userguide/performance.html#parallel_execution. For example:
gradle -parallel clean jtest-agent test jtest -Djtest.config="builtin://Unit Tests"
Jtest supports collecting coverage for parallel test execution, but the coverage may not be correctly matched to each executed test.
Collecting Application Coverage
Jtest's coverage agent allows you to collect coverage data during manual or automated tests performed on a running application. See Application Coverage for information about collecting application coverage with Jtest.
Test Impact Analysis
You can extend the capabilities of the Jtest Plugin for Gradle with test impact analysis. It allows you to you to identify and re-run only the tests that are affected by your changes, eliminating the time and effort required to execute a large number of unaffected tests. To perform test impact analysis of your project, you need to:
- Configure the test impact analysis plugin.
- Execute the
affectedTests
task.
You don't need to modify the Gradle build script.
Prerequisites
- Jtest 10.4.1 or higher
- Gradle 3.3 or higher
- JUnit 4 or 5
Test impact analysis may require additional memory. We recommend increasing the memory allocated to the Gradle build.
Integrating with the Test Impact Analysis Plugin
The init.gradle
script shipped with Jtest allows you to integrate the test impact analysis plugin with Gradle – without having to modify your Gradle build script. To integrate Gradle with the plugin, pass the location of the the init.gradle
script with the -I
option to your command line:
gradle affectedTests test -I PATH/TO/JTEST/integration/gradle/init.gradle
Configuring the Plugin
You can customize test impact analysis of your project in the build file or in the command line by configuring the properties of the test impact analysis plugin. At minimum, you must provide the paths to the following files that are generated by Jtest during execution:
coverage.xml
report.xml
See Jtest Tasks Reference for Gradle for the complete list of available options.
In the build script
Specify the properties when declaring a configuration in the build script:
affectedTests { referenceCoverageFile = 'path/to/coverage.xml' referenceReportFile = 'path/to/report.xml' runFailedTests = false runModifiedTests = true jtestHome = 'path/to/jtest' settings = 'path/to/jtestcli.properties' }
In the Command Line
If you configure the plugin in the command line, pass the plugin properties with the -D
switch. The properties must include the "jtest" prefix (see Jtest Tasks Reference for Gradle). Your command line may resemble the following:
gradle affectedTests test -I PATH/TO/JTEST/integration/gradle/init.gradle -Djtest.referenceCoverageFile="path/to/coverage.xml" -Djtest.referenceReportFile="path/to/report.xml" -Djtest.runFailedTests=false -Djtest.runModifiedTests=true -Djtest.home="path/to/jtest" -Djtest.settings="jtestcli.properties"
Configuring and Executing the affectedTest
Task
You can execute the affectedTests
task from the command line without any further configuration. Ensure it is executed before the test
task. Your command line may resemble the following:
gradle clean affectedTests test -I PATH/TO/JTEST/integration/gradle/init.gradle
Alternatively, you can:
Configure execution the task in the
build.gradle
script:build.gradletest.dependsOn affectedTests
Execute the the Gradle
test
task – theaffectedTests
task will be executed automatically:Command Linegradle test -I PATH/TO/JTEST/integration/gradle/init.gradle
If you want to run the affectedTests
task for selected subprojects of a multi-module project, modify your command line to only execute the Gradle test
task for the subprojects you want to test. Your command line may resemble the following:
gradle clean affectedTests subproject1:test subproject2:test -Djtest.referenceCoverageFile=tia/coverage.xml -Djtest.referenceReportFile=tia/report.xml -I path_jtest\integration\gradle\init.gradle
Re-executing Test Suites
Test impact analysis re-runs the entire test suite when at least one test included in that test suit is affected by code changes. Note that this may result in re-running some tests that are not affected if they are included in the same test suite as affected tests.