Ant Integration

Apache Ant automates 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 for building Java projects.

The Squish plugin for Ant enables running Squish tests from an Ant build file.

Obtaining the Ant Plugin

The Ant plugin is available from: https://resources.qt.io/hubfs/Squish/squish-ant-plugin_latest.zip

Installing the Ant Plugin

After you extract the zip archive, you can install the Ant plugin in the following ways:

  • 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.

For more information about installing external Ant libraries, see Ant Installation Manual.

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 build file must specify the squish namespace. 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 as follows:

...
<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 the 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

Ant Plugin XML Reference

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

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:

AttributeDescription
pathThe absolute path to Squish's root directory.
hostThe hostname where the squishserver is running. Leave this attribute out to let the plugin start the squishserver automatically.
portThe port number that the squishserver is listening on. Leave this attribute out to let the plugin start the squishserver automatically.
snoozefactorThe snooze factor to use when running Squish tests, defaults to 1.
reportdirDeprecated The directory where test reports should be output to, available for backwards compatibility only. To generate reports use the squish:report element instead.
webbrowserWhen 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).
webbrowserargsWhen 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: You can set the Squish path also 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.

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:

AttributeDescriptionRequired
suiteThe absolute path to the Squish suite that is to be run.Yes
testcaseDeprecated 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 element instead.No
pathThe absolute path to Squish's root directory.Only if not set in the squish:config tag.
hostThe hostname of the machine where the squishserver is running. Leave this parameter out to let the plugin start the squishserver automatically.No
portThe port number that the squishserver is listening on. Leave this parameter out to let the plugin start the squishserver automatically.No
snoozefactorThe snooze factor to use when running Squish tests, defaults to 1.No
resultdirThe 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).No
webbrowserWhen 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).No
webbrowserargsWhen executing a web test the command line arguments passed to the used browser.No
haltonerrorWhether to stop the build when a test error or test fatal occurs, defaults to false.No
haltonfailedverificationWhether to stop the build when a test verification failed, defaults to false.No

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).

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>
  ...

squish:report

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

AttributeDescriptionRequired
formatReport format to be generated. Supported values are listed at the squishrunner's --reportgen option at Executing a Test Case (Advanced).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>
  ...

© 2023 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners.
The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation.
Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.