Using the ScalaTest ant task

ScalaTest provides an ant task to make it easier to run ScalaTest as part of an ant build. Instructions on how to specify various options are below. See the documentation for the Runner for a description of what each of the options does.

To use the ScalaTest ant task, you must first define it in your ant file using taskdef. Here's an example:

 <path id="scalatest.classpath">
   <pathelement location="${lib}/scalatest.jar"/>
   <pathelement location="${lib}/scala-library.jar"/>
   <-- scala-actors.jar needed only for ScalaTest <= 1.9.1 on Scala >= 2.10.0 -->
   <pathelement location="${lib}/scala-actors.jar"/>
 </path>

 <target name="main" depends="dist">
   <taskdef name="scalatest" classname="org.scalatest.tools.ScalaTestAntTask">
     <classpath refid="scalatest.classpath"/>
   </taskdef>

   <scalatest ...
 </target>

Note that you only need the scala-actors.jar if you are using ScalaTest version 1.9.1 or earlier with Scala 2.10 or later. Once defined, you use the task by specifying information in a scalatest element:

  <scalatest ...>
    ...
  </scalatest>

You can place key value pairs into the config map using nested <config> elements, like this:

  <scalatest>
    <config name="dbname" value="testdb"/>
    <config name="server" value="192.168.1.188"/>

You can specify a runpath using either a runpath attribute and/or nested <runpath> elements, using standard ant path notation:

  <scalatest runpath="serviceuitest-1.1beta4.jar:myjini">

or

  <scalatest>
    <runpath>
      <pathelement location="serviceuitest-1.1beta4.jar"/>
      <pathelement location="myjini"/>
    </runpath>

To add a URL to your runpath, use a <runpathurl> element (since ant paths don't support URLs):

  <scalatest>
    <runpathurl url="http://foo.com/bar.jar"/>

You can specify reporters using nested <reporter> elements, where the type attribute must be one of the following:

• graphic
• file
• memory
• junitxml
• html
• stdout
• stderr
• reporterclass

Each may include a config attribute to specify the reporter configuration. Types file, memory, junitxml, html, and reporterclass require additional attributes (the css attribute is optional for the html reporter):

  <scalatest>
    <reporter type="stdout" config="FD"/>
    <reporter type="file" filename="test.out"/>
    <reporter type="memory" filename="target/memory.out"/>
    <reporter type="junitxml" directory="target"/>
    <reporter type="html" directory="target" css="src/main/html/mystylesheet.css"/>
    <reporter type="reporterclass" classname="my.ReporterClass"/>

Specify tags to include and/or exclude using <tagsToInclude> and <tagsToExclude> elements, like this:

  <scalatest>
    <tagsToInclude>
        CheckinTests
        FunctionalTests
    </tagsToInclude>

    <tagsToExclude>
        SlowTests
        NetworkTests
    </tagsToExclude>

Tags to include or exclude can also be specified using attributes tagsToInclude and tagsToExclude, with arguments specified as whitespace- delimited lists.

To specify suites to run, use either a suite attribute or nested <suite> elements:

  <scalatest suite="com.artima.serviceuitest.ServiceUITestkit">

or

  <scalatest>
    <suite classname="com.artima.serviceuitest.ServiceUITestkit"/>

To specify suites using members-only or wildcard package names, use either the membersonly or wildcard attributes, or nested <membersonly> or <wildcard> elements:

  <scalatest membersonly="com.artima.serviceuitest">

or

  <scalatest wildcard="com.artima.joker">

or

  <scalatest>
    <membersonly package="com.artima.serviceuitest"/>
    <wildcard package="com.artima.joker"/>

Use attribute suffixes="[pipe-delimited list of suffixes]" to specify that only classes whose names end in one of the specified suffixes should be included in discovery searches for Suites to test. This can be used to improve discovery time or to limit the scope of a test. E.g.:

  <scalatest suffixes="Spec|Suite">

Use attribute testsfile="[file name]" or nested elements to specify files containing a list of tests to be run. This is used to rerun failed/canceled tests listed in files written by the memory reporter. E.g.:

  <scalatest testsfile="target/memory.out">

or

  <scalatest>
    <testsfile filename="target/memory.out"/>

Use attribute parallel="true" to specify parallel execution of suites. (If the parallel attribute is left out or set to false, suites will be executed sequentially by one thread.) When parallel is true, you can include an optional sortSuites attribute to request that events be sorted on-the-fly so that events for the same suite are reported together, with a timeout, (e.g., sortSuites="true"), and an optional numthreads attribute to specify the number of threads to be created in thread pool (e.g., numthreads="10").

Use attribute haltonfailure="true" to cause ant to fail the build if there's a test failure.

Use attribute fork="true" to cause ant to run the tests in a separate process.

When fork is true, attribute maxmemory may be used to specify the maximum memory size that will be passed to the forked jvm.  For example, the following setting will cause "-Xmx1280M" to be passed to the java command used to run the tests.

  <scalatest maxmemory="1280M">

When fork is true, nested <jvmarg> elements may be used to pass additional arguments to the forked jvm. For example, if you are running into 'PermGen space' memory errors, you could add the following jvmarg to bump up the JVM's MaxPermSize value:

  <jvmarg value="-XX:MaxPermSize=128m"/>