9.3. Ant integration

Table of Contents

9.3.1. Obtaining the Ant Plugin
9.3.2. Installing the Ant Plugin
9.3.3. Using the Ant Plugin
9.3.4. Ant Plugin XML reference

Apache Ant is a software tool for automating software build processes. It is similar to make but it is written in Java and requires a Java runtime to execute it. Ant is cross-platform to the extent that Java is, and is best suited to building Java projects.

The Squish plugin for Ant makes it possible to run Squish tests from an Ant build file.

9.3.1. Obtaining the Ant Plugin

The Ant plugin is available from: download.froglogic.com/resources/squish-ant-plugin_latest.zip

9.3.2. Installing the Ant Plugin

After the zip file has been unzipped the Ant plugin can be installed in any of the ways listed below:

  • Copy the jar files to ANT_HOME/lib. This often requires Administrator rights.

  • Copy the jar files to USER_HOME/.ant/lib.

  • When calling ant use the -lib option to specify the folder which contains the Squish plugin.

Details for installing external Ant libraries are described in the Ant Installation Manual.

9.3.3. Using the Ant Plugin

Here is a typical Ant build.xml file:


<project name="MyProject" basedir="." xmlns:squish="antlib:com.froglogic.squish.ant">
  <description>
    simple example build file
  </description>

  <!-- set global properties for this build -->
  <property name="src" location="src" />
  <property name="build" location="build" />
  <property name="dist" location="dist" />

  <target name="init">
    <!-- create the time stamp -->
    <tstamp />
    <!-- create the build directory structure used by compile -->
    <mkdir dir="${build}" />
  </target>

  <target name="compile" depends="init" description="compile the source">
    <!-- compile the Java code from ${src} into ${build} -->
    <javac srcdir="${src}" destdir="${build}" includeantruntime="false" />
  </target>

  <target name="dist" depends="compile" description="generate the distribution">
    <!-- create the distribution directory -->
    <mkdir dir="${dist}/lib" />

    <!-- put everything in ${build} into the MyProject-${DSTAMP}.jar file -->
    <jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar" basedir="${build}" />
  </target>

  <target name="test" depends="compile" description="run the tests">
    <squish:runtest
      suite="C:\Squish\examples\qt\addressbook\suite_py"
      path="C:\Squish" />
  </target>

  <target name="clean" description="clean up">
    <!-- delete the ${build} and ${dist} directory trees -->
    <delete dir="${build}" />
    <delete dir="${dist}" />
  </target>
</project>

To use the plugin functionality, the squish namespace must be mentioned. For example:

<project name="MyProject" basedir="." xmlns:squish="antlib:com.froglogic.squish.ant">
  <description>
    simple example build file
  </description>
  ...

In this case it may make sense to run the Squish test as a separate target. The following will accomplish this:

  ...
  <target name="test" depends="compile" description="run the tests">
    <squish:runtest
      suite="C:\Squish\examples\qt\addressbook\suite_py"
      path="C:\Squish" />
  </target>
  ...

Running a Squish test from the command line produces the following output for the above example when using target test:

$ ant test
Buildfile: C:\ant-test\build.xml

init:

compile:

test:
[squish:runtest] Squish Ant Plugin version 5.0
[squish:runtest] Tests run : 3, Failures : 0, Errors : 0, Fatals : 0
[squish:runtest] Running test cases took 17 seconds

BUILD SUCCESSFUL
Total time: 20 seconds

9.3.4. Ant Plugin XML reference

This section provides an overview of the tags that can be used after installing the Ant plugin.

9.3.4.1. squish:config

The squish:config tag can be used as a convenient way to set the path to the Squish installation that should be used to run the tests. The table below shows the attributes that can be used:

Table 9.1. squish:config tag

Attribute Description
path The absolute path to Squish's root directory.
host The hostname where the squishserver is running. Leave this attribute out to let the plugin start the squishserver automatically.
port The port number that the squishserver is listening on. Leave this attribute out to let the plugin start the squishserver automatically.
snoozefactor The snooze factor to use when running Squish tests, defaults to 1.
reportdir Deprecated The directory where test reports should be output to, available for backwards compatibility only. To generate reports use the squish:report (Section 9.3.4.4) element instead.
webbrowser When executing a web test the browser to be used. Supported values are listed at the squishrunner's --webbrowser option at Executing a Test Case (Advanced) (Section 7.4.3.24).
webbrowserargs When executing a web test the command line arguments passed to the used browser.


Here is an example of using the squish:config tag in an Ant build file:

<project name="MyProject" basedir="." xmlns:squish="antlib:com.froglogic.squish.ant">
    <squish:config path="C:\Squish" />
    ...

When the squish:config tag is used at the start of the document—as in the above example—the path that is set is used for all the Squish tests in the targets. For finer control, the squish:config tag can be used inside a target container, in which case the path will only apply to tests in that container.

[Note]Note

It is also possible to set the Squish path in the squish:runtest tag, but if there are many Squish tests to be run and they all use the same Squish installation, using the squish:config tag is much more convenient.

9.3.4.2. squish:runtest

The squish:runtest tag can be used to run a Squish test case or test suite. The table below shows the attributes that can be used:

Table 9.2. squish:runtest tag

Attribute Description Required
suite The absolute path to the Squish suite that is to be run. Yes
testcase Deprecated The one test case from the suite to be run, available for backwards compatibility only. Leave this attribute out to run the complete test suite. To specify which test cases should be executed explicitly use the squish:testcase (Section 9.3.4.3) element instead. No
path The absolute path to Squish's root directory. Only if not set in the squish:config (Section 9.3.4.1) tag.
host The hostname of the machine where the squishserver is running. Leave this parameter out to let the plugin start the squishserver automatically. No
port The port number that the squishserver is listening on. Leave this parameter out to let the plugin start the squishserver automatically. No
snoozefactor The snooze factor to use when running Squish tests, defaults to 1. No
resultdir The absolute path to a directory which is used to save test results, corresponds to the squishrunner's --resultdir which is documented at Executing a Test Case (Advanced) (Section 7.4.3.24). No
webbrowser When executing a web test the browser to be used. Supported values are listed at the squishrunner's --webbrowser option at Executing a Test Case (Advanced) (Section 7.4.3.24). No
webbrowserargs When executing a web test the command line arguments passed to the used browser. No
haltonerror Whether to stop the build when a test error or test fatal occurs, defaults to false. No
haltonfailedverification Whether to stop the build when a test verification failed, defaults to false. No


[Note]Note

Attributes set in the squish:runtest tag will overwrite attributes set in the squish:config tag.

Here is an example of using the squish:runtest tag in an Ant build file:

<project name="MyProject" basedir="." xmlns:squish="antlib:com.froglogic.squish.ant">
  ...
  <target name="test" depends="compile" description="run the tests">
    <squish:runtest
      suite="C:\Squish\examples\qt\addressbook\suite_py"
      path="C:\Squish" />
  </target>
  ...

For the squish:runtest tag to work, the suite attribute must indicate a valid Squish suite. Also, the absolute path to the Squish installation to use for running tests must be known, either by using the squish:runtest tag's path attribute or the squish:config tag's path attribute. When an ant process runs a Squish test, it waits for the test to be completed; the results are reported back on the standard output (e.g., the console).

9.3.4.3. squish:testcase

The squish:testcase tag can be used to specify which test cases should be executed explicitly. It must be a child of the squish:runtest tag.

Here is an example of using the squish:testcase tag in an Ant build file:

<project name="MyProject" basedir="." xmlns:squish="antlib:com.froglogic.squish.ant">
  ...
  <target name="test" depends="compile" description="run the tests">
    <squish:runtest
      suite="C:\Squish\examples\qt\addressbook\suite_py"
      path="C:\Squish"
      <squish:testcase>tst_adding</squish:testcase>
      <squish:testcase>tst_general</squish:testcase>
    </squish:runtest>
  </target>
  ...

9.3.4.4. squish:report

The squish:report tag can be used to specify which reports should be generated.

Table 9.3. squish:report tag

Attribute Description Required
format Report format to be generated. Supported values are listed at the squishrunner's --reportgen option at Executing a Test Case (Advanced) (Section 7.4.3.24). Yes


Here is an example of using the squish:report tag in an Ant build file:

<project name="MyProject" basedir="." xmlns:squish="antlib:com.froglogic.squish.ant">
  ...
  <target name="test" depends="compile" description="run the tests">
    <squish:runtest
      suite="C:\Squish\examples\qt\addressbook\suite_py"
      path="C:\Squish"
      <squish:testcase>tst_adding</squish:testcase>
      <squish:testcase>tst_general</squish:testcase>
      <squish:report format="xml2.2">C:\xml_reports\addressbook.xml</squish:report>
      <squish:report format="xmljunit">C:\junit_reports\addressbook.xml</squish:report>
    </squish:runtest>
  </target>
  ...