As an aggregator, the Jtest Plugin form Maven must be executed only once during the build. We recommend configuring the jtest
goal execution directly from command line or as a reporting plugin.
You do not need to build a project before running analysis, but we recommend compiling multi-module projects beforehand. Doing so enables Jtest to use artifacts from the local repository, reducing the amount of time necessary to test and analyze code.
Running Static Analysis
To perform static analysis on your code:
- Ensure that the Jtest Plugin for Maven is set up (see Configuring the Jtest Plugin for Maven).
Execute the jtest:jtest goal. Your command line may resemble the following:
mvn jtest:jtest
The Jtest Plugin for Maven will collect the necessary build data in the .json file, and analyze your code depending on the configuration you provided (see Configuring Jtest Execution).
- Review the analysis results (see Reviewing Results).
If Jtest reports compilation problems related to importing dependencies in the Maven test scope, try running the jtest:jtest
goal with the mvn test
command:
mvn test jtest:jtest
Executing Unit Tests
You can include unit test results in the Jtest report by running your tests with the jtest:jtest goal and the dedicated Unit Tests
built-in test configuration:
- Ensure that the Jtest Plugin for Maven is set up (see Configuring the Jtest Plugin for Maven).
Execute the jtest:jtest goal with Maven. Your command line may resemble the following:
mvn clean test jtest:jtest -Djtest.config="builtin://Unit Tests"
Collecting Coverage for Unit Tests
You can collect coverage information during execution of unit tests by your tests with the jtest:jtestand jtest:agent goals, and the dedicated Unit Tests
built-in test configuration:
- Ensure that the Jtest Plugin for Maven is set up (see Configuring the Jtest Plugin for Maven).
Execute the jtest:agent and jtest:jtest goals Maven. Ensure that the tests and classes are compiled before the
jtest:agent
goal is run. Your command line may resemble the following:mvn clean test-compile jtest:agent test jtest:jtest -Djtest.config="builtin://Unit Tests"
Executing the jtest:agent
goal before the classes are compiled, may result in empty coverage. If your build uses Tycho plugins, or any other plugins that are detached from the default lifecycle, invoke the dedicated (non-default) compiler to ensure that the classes are properly compiled and coverage information is collected. Your command line may resemble the following:
mvn clean tycho-compiler:compile jtest:agent verify jtest:jtest -Djtest.config="builtin://Unit Tests"
About the jtest:agent
Goal
The jtest:agent goal generates the Jtest agent settings based on the build modules, and sets the javaagent VM agument in the properties specified with the agentPropertyNames parameter in the initialize phase.
By default, it tries to inject javaagent VmArg
into maven-surefire-plugin
and eclipse-test-plugin
through specific properties.
Prerequisites for using the jtest:agent
goal with the Maven test plugins:
- tests must be executed in the forked process (for example, with the parameters
forkCount
orforkMode
) - additional VmArgs must contain Jtest javaagent VmArgs (the
argLine
parameter)
The jtest:agent
goal attempts to automatically configure the Maven test plugins (maven-surefire-plugin and tycho-surefire-plugin) by setting up the properties of their VmArgs
parameters (by default through the argLine and tycho.testArgLine properties). You can customize the default values of these parameters if one of the following ways:
Through the default property. The
jtest:agent
goal will extend the properties with the Jtestjavaagent VmArg
:<project> <!-- ... --> <properties> <!-- argLine property which will be extended by jtest:agent goal ---> <argLine>-Xmx=1024m -XX:MaxPermSize=256m</argLine> </properties> <!-- ... --> <build> <plugins><!-- or pluginManagement --> <plugin> <artifactId>maven-surefire-plugin</artifactId> <configuration> <forkCount>1</forkCount> <!-- do not configure argLine parameter here --> </configuration> </plugin> </plugin> </build> </project>
Through a parameter value with an injected custom property:
<project> <!-- ... --> <build> <plugins> <plugin> <groupId>com.parasoft.jtest</groupId> <artifactId>jtest-maven-plugin</artifactId> <version>1.2.15</version> <configuration> <!-- jtest:agent goal will set Jtest Java agent VmArg into properties below --> <agentPropertyNames>jtest.argLine</agentPropertyNames> <!-- optional coverage block with parameters identical as in offline coverage --> <coverage> <!-- ... --> </coverage> </configuration> </plugin> <plugin> <artifactId>maven-surefire-plugin</artifactId> <configuration> <argLine>${jtest.argLine} -Xmx=1024m -XX:MaxPermSize=256m</argLine> </configuration> </plugin> </plugin> </build> </project>
About the jtest:instrument
Goal (deprecated)
You can collect coverage for unit tests by running the jtest:instrument goal, which instruments the .class files before test execution (in the process-test-classes phase). Your command line may resemble the following:
mvn clean test-compile jtest:instrument test jtest:jtest -Djtest.config="builtin://Unit Tests"
Ensure that the primary reporting scope is wider than the instrumentation scope for coverage to be collected. You can customize the reporting scope with the resource
parameter. By default, everything is in scope.
<project> <!-- ... --> <build> <!-- ... --> <plugins> <!-- ... --> <plugin> <groupId>com.parasoft.jtest</groupId> <artifactId>jtest-maven-plugin</artifactId> <version>1.2.15</version> <configuration> <includes><!-- reporting scope configuration --> <!-- report coverage for all files in specified package --> <include>**/my/package/*</include> <includes> <coverage> <excludes> <!-- classes instrumentatio excludes --> <exclude>**/AnnotationProcessor.class</exclude> </excludes> <testExcludes> <!-- test classes instrumentation excludes --> <exclude>**/*Util.class</exclude> </testExcludes> </coverage> </configuration> </plugin> </plugins> </build> </project>
Configuration Guidelines
- Disable incremental compilation by adding -Dmaven.compiler.useIncrementalCompilation=false to your command line to prevent instrumented classes from being overridden during recompilation. This option is available only for Maven 3.1 or later, and requires older Maven versions to be upgraded. Instrumented classes are overridden during recompilation due to a known problem in the maven-compiler-plugin (version 3.0 and later).
The maven-compiler-plugin (version 3.0 and later) has a known problem If your build uses other plugins that instrument code (for example, aspectj), ensure that the Jtest Plugin for Maven is executed in the process-classes phase. To achieve this, explicitly configure the execution in the POM file:
<build> <!-- ... --> <plugins> <!-- other plugin that instruments the code --> <plugin> <groupId>com.parasoft.jtest</groupId> <artifactId>jtest-maven-plugin</artifactId> <version>1.2.15</version> <executions> <execution> <goals> <goal>instrument</goal> </goals> <phase>process-classes</phase> </execution> </executions> </plugin> </plugins> </build>
- If your project includes a defined annotation processor that transforms compiled classes, ensure that the class (or module that contains the annotation processor) is excluded from instrumentation. See jtest:instrument for information on how to use the excludes option to exclude specific files from instrumentation (you can use the skip option to exclude the entire module).
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 Maven 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:
- Add the test impact analysis plugin (
cbt-maven-plugin
) shipped with Jtest to your Maven build. - Configure the plugin.
- Execute the
affected-tests
goal.
Prerequisites
- Jtest 10.4.1 or higher
- Apache Maven 2.2.1 or higher (versions 3.3.1 and 3.3.3 are not supported)
- Surefire 2.19.1 or higher
In addition, the Jtest Plugin for Maven must be configured to ensure access to the Maven repository shipped with Jtest (see Initial Setup).
Licensing
Test impact analysis requires customizing your Parasoft license settings. Ensure that the 'custom_edition' license with the 'Change Based Testing' and 'Automation' features is enabled in your jtest.properties file.
Test impact analysis may require additional memory. We recommend increasing the memory allocated to the Maven build.
Jtest does not support test impact analysis for Maven parallel builds.
Jtest does not support excluding tests when the runModifiedTests
option is set to true
(see Optional Parameters).
Integrating with the Test Impact Analysis Plugin
You can integrate with the test impact analysis plugin by adding cbt-maven-plugin
to the list of plugins in the POM file:
<build> <plugins> <plugin> <groupId>com.parasoft.xtest.cbt</groupId> <artifactId>cbt-maven-plugin</artifactId> <version>1.0.0</version> </plugin> </plugins> </build>
Configuring the Plugin
You can customize test impact analysis of your project in the POM file or in the command line by configuring cbt-maven-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 Goals Reference for Maven for the complete list of available options.
In the POM file
If you configure the plugin in the POM file, you can add the cbt-maven-plugin
properties to:
plugin declaration
pom.xml<plugin> <groupId>com.parasoft.xtest.cbt</groupId> <artifactId>cbt-maven-plugin</artifactId> <version>1.0.0</version> <configuration> <coverageFile>target/jtest/coverage.xml</coverageFile> <testFile>target/jtest/report.xml</testFile> <runFailingTests>false</runFailingTests> <runModifiedTests>true</runModifiedTests> <jtestHome>${jtest.home}</jtestHome> <settingsFiles>jtestcli.properties</settingsFiles> </configuration> </plugin>
plugin execution
pom.xml<plugin> <groupId>com.parasoft.xtest.cbt</groupId> <artifactId>cbt-maven-plugin</artifactId> <version>1.0.0</version> <executions> <execution> <goals> <goal>affected-tests</goal> </goals> <configuration> <coverageFile>target/jtest/coverage.xml</coverageFile> <testFile>target/jtest/report.xml</testFile> <runFailingTests>false</runFailingTests> <runModifiedTests>true</runModifiedTests> <jtestHome>${jtest.home}</jtestHome> <settingsFiles>jtestcli.properties</settingsFiles> </configuration> </execution> </executions> </plugin>
Maven properties
pom.xml<properties> <parasoft.coverage.file>target/jtest/coverage.xml</parasoft.coverage.file> <parasoft.test.file>target/jtest/report.xml</parasoft.test.file> <parasoft.runFailingTests>false</parasoft.runFailingTests> <parasoft.runModifiedTests>true</parasoft.runModifiedTests> <jtest.home>${env.JTEST_HOME}</jtest.home> <jtest.settings>jtestcli.properties</jtest.settings> </properties>
In the Command Line
If you customize test impact analysis in the command line, pass the cbt-maven-plugin
properties with the -D
switch. The properties must include the "parasoft" or "jtest" prefix (see Jtest Goals Reference for Maven for details). Your command line may resemble the following:
mvn cbt:affected-tests test -Dparasoft.coverage.file=target/jtest/coverage.xml -Dparasoft.test.file=target/jtest/report.xml -Dparasoft.runFailingTests=false -Dparasoft.runModifiedTests=true -Djtest.home=$JTEST_HOME -Djtest.settings=jtestcli.properties
Configuring and Executing the affected-tests
Goal
You can configure execution of the affected-tests
goal from the command line or by configuring the goal in the POM file.
In the Command Line
When cbt-maven-plugin
is included in the Maven build file (see Integrating with the Test Impact Analysis Plugin), you can execute the cbt:affected-tests
goal from the command line. Ensure it is executed before the test
goal:
mvn cbt:affected-tests test
In the POM file
You can configure execution of the affected-tests
goal in the build plugins or in the the build plugins of the profile.
If you include the
affected-tests
goal in the build plugins:pom.xml<build> <plugins> <plugin> <groupId>com.parasoft.xtest.cbt</groupId> <artifactId>cbt-maven-plugin</artifactId> <version>1.0.0</version> <executions> <execution> <goals> <goal>affected-tests</goal> </goals> </execution> </executions> </plugin> </plugins> </build>
it will be automatically executed with the Maven
test
goal:Command Linemvn test
If you include the
affected-tests
goal in the build plugins of the profile:pom.xml<profile> <id>cbt</id> <build> <plugins> <plugin> <groupId>com.parasoft.xtest.cbt</groupId> <artifactId>cbt-maven-plugin</artifactId> <version>1.0.0</version> <executions> <execution> <goals> <goal>affected-tests</goal> </goals> </execution> </executions> </plugin> </plugins> </build> </profile>
you must execute the Maven
test
goal using the profile:Command Linemvn test -P cbt