Initial Setup

The Jtest Plugin for Ant is shipped with Jtest as a JAR file in the following location: [INSTALL_DIR]/integration/ant. Add jtest-ant-plugin.jar to the build classpath in one of the following ways:

Deploy the file in the Ant's libs directory: $HOME/.ant/lib
Deploy the file in the Ant's system installation lib directory: $ANT_HOME/lib
Note: If your IDE, continuous integration (CI) software, or other tools you are using use embedded Ant installations, the $ANT_HOME/lib directory is omitted and you need to use the $HOME/.ant/lib directory to add the JAR file.
Add the following parameter to the Ant command line each time you build and analyze your projects:
-lib $JTEST_HOME/integration/ant/jtest-ant-plugin.jar

Specify taskdef tasks in the root build script:

<project name="project" default="sth" xmlns:jtest="antlib:com.parasoft.jtest.plugin.ant">
 
  <taskdef uri="antlib:com.parasoft.jtest.plugin.ant"
  
   resource="com/parasoft/jtest/plugin/ant/antlib.xml"
 
   classpath="PATH/TO/JTEST/integration/ant/jtest-ant-plugin.jar"/>
 
  <!-- ... -->

</project>

Configuring Jtest Execution

You can configure Jtest execution in an external XML build file, in the regular Ant XML build file, or in the command line – by specifying individual settings with the dedicated switch.

The following examples assume that jtest-ant-plugin.jar has been deployed into one of Ant's lib directories, so the command line argument -lib is not used.

Configuring Analysis in the `build.xml` File

You can configure analysis by modifying Ant's build.xml file:

<project name="Analyzed Project" default="build"
    xmlns:jtest="antlib:com.parasoft.jtest.plugin.ant">
  <!-- ... -->
  <jtest:listener />
  <!-- ... -->
  <target name="jtest-analysis" depends="build">
    <jtest:jtest>
       <!-- jtest task configuration -->
    </jtest:jtest>
  </target>
  <!-- ... -->
  <target name="build">
    <!-- analyzed project build target -->
  </target>
</project>

If you configure analysis in the build.xml file, execute analysis with the following command:

ant jtest-analysis

Configuring Analysis in the External XML Build File

You can configure analysis in the external jtest.xml build file.

<project name="Analyzed Project" default="build"
    xmlns:jtest="antlib:com.parasoft.jtest.plugin.ant">
  <property name="jtest.home" value="PATH/TO/JTEST" />
  <jtest:listener />
  <target name="jtest-analysis" depends="build">
    <jtest:jtest>
      <config>builtin://Recommended Rules</config>
      <home>PATH/TO/JTEST</home>
      <resource>Analyzed Project/src/**/*.java</resource>
      <report>report</report>
      <publish>true</publish>
    </jtest:jtest>
  </target>
  <!-- ... -->
  <target name="build">
    <!-- ant task makes subproject to inherit properties (including jtest.home) 
         which may be used by instrument and instrument-test tasks -->
    <ant target="build" dir="${basedir}" antfile="build.xml" />
  </target>
</project>

If you configure analysis in the jtest.xml file, you must add it to your command line with the -file switch. Failing to do so will result in using the default Ant build.xml file during analysis. Execute analysis with the following command:

ant jtest-analysis

Hierarchy

The above example shows the home parameter configured in three different ways in the descending hierarchical order:

Directly in the task tag.
With the project property (the property task).
With the with JVM environment variable. You can configure Jtest options using the -D command line option, for example -Djtest.home=value.
Note: The built-in Ant options have priority over Jtest options. If Ant options are used for configuration, they override values passed with the Jtest-D.

Advanced Configuration in the XML Build File

The following configuration loads the jtest-ant-plugin.jar and starts the listener form the build file. As a result:

Ant command line does not require any additional options to execute analysis with Jtest
you don't need to pass jtest-ant-plugin.jar with the -lib option or deploy the file in the $ANT_HOME/lib directory

<project name="Analyzed Project" default="jtest-analysis"
        xmlns:jtest="antlib:com.parasoft.jtest.plugin.ant">
  <!-- ... -->
  <property name="jtest.home" value="PATH/TO/JTEST" />
  <taskdef uri="antlib:com.parasoft.jtest.plugin.ant"
    resource="com/parasoft/jtest/plugin/ant/antlib.xml"
    classpath="${jtest.home}/integration/ant/jtest-ant-plugin.jar"/>
  <!-- listener has to be specified after taskdef -->
  <jtest:listener />
  <!-- ... -->
  <target name="build">
    <!-- analyzed project build target -->
  </target>
  <!-- ... -->
  <target name="jtest-analysis" depends="build">
    <jtest:jtest/>
  </target>
</project>

Configuring Analysis in the Command Line

You can configure analysis in the command line by passing individual settings with the -Dproperty option (-Dproperty.KEY=VALUE). For example:

ant jtest-analysis -Dproperty.console.verbosity.level=high

Manual Customization of Compilation Data

In rare cases, highly customized Ant builds may lead to gaps or errors in the compilation data automatically detected by the Jtest Plugin for Ant. Jtest reports such issues in the Setup Problems section of the generated report, as well as in the console output. If you verify that the detected compilation data contains errors, you can extend or override the data in the build.xml file of the analyzed project.

The following example shows customized compilation data of an analyzed Ant build. The configuration is extended with an additional binary path element.

By default, Ant has no compilation id. When the project triggers the javac task more then once, you must define an id for javac to match it with custom the compilation data. A custom compilation data configuration with no id will apply to all compilation data collected from the javac task that does not have the id parameter specified.

<project name="Jtest Analysis" default="jtest-analysis"
    xmlns:jtest="antlib:com.parasoft.jtest.plugin.ant">
  <!-- properties etc. -->
  
  <target name="build">
    <javac id="main_compilation" srcdir="${src.dir}" 
      destdir="${target.dir}" source="1.5" />
    <!-- copying additional jar into target.dir which cannot be detected by plugin -->
  </target>
    
  <target name="jtest-analysis" depends="build">
    <jtest:jtest>
      <config>builtin://Recommended Rules</config>
      <home>${env.JTEST_HOME}</home>
      <compilation>
        <!-- will apply to every compilation data if ID not specified -->
        <id>main_compilation</id>
        <classpath>
            <!-- filesets can be used in classpath and bootpath -->
            <fileset dir="C:/some_directory/lib">
                <include name="**/*.jar"/>
            </fileset>
            <path>some_jar_file.jar</path>
        </classpath>
        <binarypath>
          <path>${additional.jar.file}</path>
          <path>${other.jar.file}</path>
        </binarypath>
      </compilation>
    </jtest:jtest>
  </target>  
</project>

If you need to modify compilation data for all projects, you can use the -Djtest.dataUpdate command line option.

See Compilation Data Model for more information about how to customize compilation data automatically detected by the Jtest plugins.