Parasoft Test Ant Plugin
This topic covers the Parasoft Test Ant plugin that allows you to configure Parasoft testing and build analysis actions to be invoked from Ant. It assumes a basic familiarity with Ant usage.
Sections include:
•
Prerequisites
•
Setup
•
Configuration
•
Available Tasks
•
Environment Variables
•
Usage Tips
•
Examples
Prerequisites
The Parasoft Test Ant plugin requires:
•
JDK 1.5
•
Ant 1.6.2
There are no minimum requirements for disk space or memory space.
Setup
Before you can use the Parasoft Test Ant plugin, you need to get the jar file from http://build.parasoft.com/docs/overview.html, then do one of the following:
•
Add the jar file to your Ant library.
•
Add the jar file to your Ant repository.
•
Add the jar file’s directory as a command line -lib argument.
Configuration
To configure execution of the Parasoft plugin:
1.
Create a new file (e.g., parasoft.xml or jtest.xml). In this file, you will import your original Ant build file as well as specify how you want Ant to run the Parasoft plugin.
2.
Start that file by defining the project and calling the Parasoft Ant library. Add one project definition for each logical project in your build script. Each project defined here will be reported to Parasoft Concerto as a separate project. For example:
<project name="Parasoft Test Build" default="parasoft-test" xmlns:parasoft="antlib:com.parasoft.antlib">
If the build.xml being imported has its project definition basedir set to anything other than the current directory ".", add the same basedir to this configuration. For example:
<project name="Parasoft Test Build" default="parasoft-test" xmlns:parasoft="antlib:com.parasoft.antlib" basedir="..">
(If omitted, it defaults to ".")
3.
Import the original Ant build.xml file. For example:
<import file="build.xml"/>

This step is not required for running SOAtest.
4.
Add a target for the Parasoft task you want executed and use dependencies to specify the task to integrate with (e.g., build). For example:
<target name="parasoft-test" depends="build">

For SOAtest, you do not need to use dependencies to specify the task to integrate with.
5.
Configure the target for the task. Be sure to specify

a. Any required or desired task options described in the plugin reference page
b. (Not required for SOAtest) Either javacref or monitorref (described below) to specify which compilation targets you want to operate on.

For example:

<!-- To use and configure Parasoft Test Plugin -->
 <parasoft:jtest config="builtin://Static Analysis">
 <!-- javacref refers to the ID of the specific javac in build.xml -->
 <projectDescription basedir="." javacref="javacId" overwrite="true"/>
 </parasoft:jtest>
6.
Repeat steps 4 and 5 until all of your desired targets are configured.
 
There are two main ways to specify the javac targets you want to operate on:
•
To automatically record the project’s javac targets, use the parasoft:monitor task. As your project builds, the monitor will record every call to the javac compiler. You can then give the monitor an ID then reference the monitor in your Parasoft script. If you are writing an Ant script in a very dynamic way (e.g., using <antcall/> to call the javac compiler multiple times with different arguments), using the monitor is highly recommended. See Using the Monitor below for more details.
•
To have the plugin operate on javac calls specified in build.xml, add refids for those calls, then use javacref to specify the refid(s) you want to operate on. This option gives you more control over project configuration than the monitor option provides. See Using refids below for more details.
Using the Monitor
To use the monitor:
1.
Modify your Parasoft Ant build script so that parasoft:monitor is called prior to compilation.
2.
In the Parasoft task definition in your Parasoft Ant build script, specify
monitorref="your.monitor"
For instance, the following configures a new parasoft-init target for the monitor, then uses a dependency to ensure that the main compilation task (compiler) executes only after the monitor task completes. Note how it defines, then references, the my.monitor id:
<target name="parasoft-init">
    <parasoft:monitor id="my.monitor"/>
</target>
 
<target name="jtest" depends="parasoft-init,clean, compiler">
   <echo>Running Jtest</echo>
 
    <!== build main sources -->
    <parasoft:jtest config="builtin://Static Analysis" overwrite="true">
        <projectDescription monitorref="my.monitor" overwrite="true" /"
    </parasoft:jtest>
Using refids
To use refids:
1.
In your original Ant build script, go to the project definitions and define IDs for your javac targets.
2.
In the Parasoft task definition in your Parasoft Ant build script, specify which refids you want the task to operate on:
•
To operate on specific javac calls, use javacref ="javacId" or javacref ="javacId, javacId2, javacId3, ..".
•
To have the plugin operate on all javac calls specified in build.xml, use javacref="all".
•
To have the plugin operate on all javac calls that have refids, use javacref="allrefs".
For example, you might update your build.xml file to include refids as follows:
<javac target="${jdk.version.class}"
      source="${jdk.version.source}"
      ...
      id="main.javac"
      ...
      .../>
Then, you would add the following to the target description in your parasoft.xml file:
   <target name="parasoft-test" depends="build">
        ...
        <!-- To use and configure Parasoft Test Plugin -->
        <parasoft:jtest config="builtin://Static Analysis">
            <!-- javacref refers to the ID of the specific javac in build.xml -->
            <projectDescription basedir="." javacref="main.javac" overwrite="true"/>
        </parasoft:jtest>
        ...
    </target>
Available Tasks
See the plugin reference page.
Environment Variables
Environment variables can be used for options that will remain constant for all builds on a specific machine.
Each Parasoft Test product has its own OPTS variable:
•
CPPTEST_OPTS
•
DOTTEST_OPTS
•
JTEST_OPTS
•
SOATEST_OPTS
For options that will be used for all Parasoft Test products, use PARASOFT_OPTS.
For options that will be used only in the project import phase, use IMPORT_OPTS.
These options are commonly used for tasks like changing user names or increasing Java memory.
For example:
1.
Set the Jtest user name.
2.
Create the environment variable JTEST_OPTS and set it to -J-Duser.name=user1
Usage Tips
This section provides tips for using the tasks described in the plugin reference page.
Preparing for Jtest or SOAtest Execution
In order to execute Jtest, you need to have .classpath and .project files that work in the server environment. In order to execute SOAtest, you need to have a .project file that works in the server environment. To generate the files that Eclipse requires, use the parasoft:eclipse task.
If you have decided to store localsettings for Jtest and SOAtest execution on Concerto (as described in the Concerto documentation)—and/or if you are specifying localsettings options in the Ant script— parasoft:localsettings will generate a localsettings file with these options, then save it in the project so that it can easily be used for your Ant-driven tests.
For Monitoring the Build
The parasoft:monitor task (described above in Using the Monitor) also executes the Parasoft Build Monitor, which analyzes your build and sends Parasoft Concerto data regarding build warnings, errors, and the number of files successfully compiled. This must be performed before compilation.
When using this task for Concerto build monitoring, be sure to specify the Concerto host, port, and project name.
For backwards compatibility, the Parasoft Test Ant plugin also supports the previous (now deprecated) mode of configuring Build Monitor. This is described in Configuring Parasoft Build Monitor with Ant (Deprecated).
Running Several Different Configurations
Here is a sample Ant script that can run several different Jtest configurations (as separate targets):
<?xml version="1.0"?>
<project name="Jtest Build" default="jtest" xmlns:parasoft="antlib:com.parasoft.antlib">
    <import file="build.xml"/>
 
    <property name="concerto" value="developers.parasoft.com"/>
    <property name="projectName" value="Default Project"/>
    <property name="config" value="builtin://Static Analysis"/>
 
    <!-- Installs the parasoft monitor to track the build -->
    <target name="parasoft-init">
        <parasoft:monitor id="parasoft.monitor" concertoHost="${concerto}" concertoPort="8080" projectName="${projectName}"/>
    </target>
 
    <!-- Creates the localsettings file used by parasoft tools, can optionally retrieve settings from Concerto (4.5 or higher) -->
    <target name="localsettings">
        <parasoft:localsettings concertoHost="${concerto}" concertoPort="8080" projectName="${projectName}">
            <additionalProperty key="scope.author" value="false"/>
            <additionalProperty key="scope.local" value="true"/>
            <additionalProperty key="report.mail.enabled" value="true"/>
        </parasoft:localsettings>
    </target>
 
    <!-- runs Jtest by statically analyzing the build.  id attributes must be added to javac targets. A separate project is setup for each javac -->
    <target name="jtest-multiple-projects" depends="parasoft-init, clean, compile, localsettings">
        <echo>Running Jtest Using Multiple Projects</echo>
        <parasoft:jtest config="${config}">
            <projectDescription javacref="main.javac" overwrite="true"/>
            <projectDescription javacref="submodule.javac" overwrite="true"/>
        </parasoft:jtest>
    </target>
 
    <!-- runs Jtest by statically analyzing the build.  id attributes must be added to javac targets. A single project is setup which combines the referenced javac targets -->
    <target name="jtest-single-project" depends="parasoft-init, clean, compile, localsettings">
        <echo>Running Jtest Using Single Project</echo>
        <parasoft:jtest config="${config}">
            <projectDescription javacref="main.javac, submodule.javac" overwrite="true"/>
        </parasoft:jtest>
    </target>
 
    <!-- runs Jtest by statically analyzing the build.  Collects all javac targets from build file -->
    <target name="jtest-single-project-all" depends="parasoft-init, clean, compile, localsettings">
        <echo>Running Jtest Using With All javac targets</echo>
        <parasoft:jtest config="${config}">
            <projectDescription javacref="all" overwrite="true"/>
        </parasoft:jtest>
    </target>
 
    <!-- runs Jtest by statically analyzing the build.  Collects all javac references from build file -->
    <target name="jtest-single-project-allrefs" depends="parasoft-init, clean, compile, localsettings">
        <echo>Running Jtest Using With All javac targets that have references</echo>
        <parasoft:jtest config="${config}">
            <projectDescription javacref="allrefs" overwrite="true"/>
        </parasoft:jtest>
    </target>
 
    <!-- runs Jtest by analyzing the build dynamically.  The monitor will collect information during the build to setup and run Jtest -->
    <target name="jtest-with-monitor" depends="parasoft-init, clean, compile, localsettings">
        <echo>Running Jtest With Monitor</echo>
        <parasoft:jtest config="${config}">
            <projectDescription monitorref="parasoft.monitor" overwrite="true"/>
        </parasoft:jtest>
    </target>
 
</project>
Examples
Automating Jtest with Ant
In the example below, the Parasoft Ant script imports an existing build.xml and calls Jtest to execute static analysis on the build.
<!-- Project definition and call to Parasoft Ant library -->
<project name="Parasoft Test Build" default="parasoft-test"
xmlns:parasoft="antlib:com.parasoft.antlib">
    <!-- To import the original Ant build.xml file and specify the task to integrate to -->
    <import file="build.xml"/>
    <target name="parasoft-test" depends="build">
        <!-- To run Jtest on the specified project directory in projectDescription, using the
configuration in config and Jtest in jtestHome -->
        <parasoft:jtest config="builtin://Static Analysis" jtestHome="C:\Program
Files\Parasoft\Jtest\9.5">
            <projectDescription basedir="."/>
        </parasoft:jtest>
    </target>
</project>
 
In the next example, the Parasoft Ant script imports an existing build.xml whose basedir is set to a different directory (for example, basedir="../sources"):
<!-- Project definition and call to Parasoft Ant library -->
<project name="Parasoft Test Build" default="parasoft-test" 
xmlns:parasoft="antlib:com.parasoft.antlib">
    <!-- To import the original Ant build.xml file and specify the task to integrate to -->
    <import file="build.xml"/>
    <target name="parasoft-test" depends="build">
        <!-- To run Jtest on the specified project directory in projectDescription, using the
configuration in config and Jtest in jtestHome -->
        <parasoft:jtest config="builtin://Static Analysis" jtestHome="C:\Program
Files\Parasoft\Jtest\9.5">
            <projectDescription basedir="."/>
        </parasoft:jtest>
    </target>
</project>
 
Automating SOAtest with Ant
In the example below, the Parasoft Ant script calls SOAtest to run the .tst files with the "Run Web Functional Tests in Browser Specified by Test" Test Configuration.
<!-- Project definition and call to Parasoft Ant library -->
<project name="Parasoft Test Build" default="parasoft-test"
xmlns:parasoft="antlib:com.parasoft.antlib" basedir="../sources">
    <target name="soatest-test">
        <!-- To generate .project file needed to run SOAtest if it does not exist -->
        <parasoft:eclipse/>
        <!-- To run SOAtest with the selected configuration -->
        <parasoft:soatest config="builtin://Run Web Functional Tests in Browser Specified by Test"
soatestHome="C:\Program Files\Parasoft\SOAtest\9.4"/>
    </target>
</project>
Note that this differs from a Jtest build file in that you do not need to:
•
Import the original build.xml file.
•
Use dependencies to specify the task to integrate with (e.g., build).
•
Use either javacref or monitorref to specify which compilation targets you want to operate on.