AntUnit

Description

Runs Ant on targets of a build file that follow a certain naming convention. If Ant throws the special subclass of BuildException that the assertTrue task uses, consider it a failed test. Any other exception is considered a failure. If Ant completes the target without any exception, consider it a passed test.

Tests are specified via ResourceCollections.

All targets whose name starts with "test" (but not if the name is "test" exactly) are considered test cases. If a test build file contains a target named setUp, this gets executed before each test target. If it contains a target named tearDown this gets executed after each test target.

If the test build file contains a target named suiteSetUp, this gets executed before te very first test target (or before the setUp target is executed for the first time). If it contains a target named suiteTearDown this gets executed after the last test target (or tearDown has been executed the last time).

Each test target is run in a fresh Ant project, i.e. each test target has a fresh set of properties and references.

So in a build file with targets setUp, tearDown, test1 and test2, antunit will run two Ant builds. One will run the targets setUp, test1 and tearDown (in that order), the other one will run setUp, test2 and tearDown. The order of those two Ant builds is not defined.

<antunit> also supports AntUnitListeners, i.e. classes that receive notifications on test runs, failures and so one. Currently two implementations of this interface are provided with this Ant library.

Log output during each antunit test case is captured by an instance of the LogCapturer class that is available via a project reference named ant.antunit.log. The published interface of that class is:

/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 * 
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
 *
 */

package org.apache.ant.antunit;

public class LogCapturer {
    public static final String REFERENCE_ID = "ant.antunit.log";

    /**
     * All messages with logLevel == Project.MSG_ERR.
     */
    public String getErrLog();
    /**
     * All messages with logLevel == Project.MSG_WARN or
     * more severe.
     */
    public String getWarnLog();
    /**
     * All messages with logLevel == Project.MSG_INFO or
     * more severe.
     */
    public String getInfoLog();
    /**
     * All messages with logLevel == Project.MSG_VERBOSE or
     * more severe.
     */
    public String getVerboseLog();
    /**
     * All messages with logLevel == Project.MSG_DEBUG or
     * more severe.
     */
    public String getDebugLog();
}

Additionally, the contents of the log can be accessed through a LogContent resource.

Parameters

Parameters specified as nested elements

any file system resource collection

Specifies the build files to run as tests. At least one resource is required.

any implementation of AntUnitListener

Creates a test listener that gets attached to the task.

Some listeners are part of this antlib:

• <plainlistener/> creates reports similar to the "plain" <formatter> of the <junit> task.
• <xmllistener/> is similar to the "xml" <formatter>.
• <logforwarder/> forwards log output from the project under test to the project executing the antunit task.

propertyset

<propertyset>s can be used to pass properties to the build files under test.

reference

One or more references may be passed to the antunit script. For example, paths and filesets can be defined once in the outer build script and passed through to multiple antunit scripts.

References can be grouped inside a <referenceset> element for clarity. Additionally, <referenceset> elements may contain exactly one nested <mapper> element, which defines how source reference IDs are translated into target reference IDs. For example,

  <au:antunit>
    <referenceset>
      <reference refid="first.ref"/>
      <reference refid="second.ref"/>
      <mapper type="regexp" from="(.*)\.ref" to="mapped.ref.\1"/>
    </referenceset>
  </au:antunit>

Examples

This build file snippet (from src/etc/testcases/antunit/base.xml)

  <target name="setUp">
    <echo>setup</echo>
  </target>

  <target name="test1">
    <echo>test1</echo>
  </target>

  <target name="test2">
    <echo>test2</echo>
  </target>

  <target name="Xtest3">
    <echo>test3</echo>
  </target>

  <target name="test4">
    <au:assertTrue message="test4 fails">
      <istrue value="false"/>
    </au:assertTrue>
  </target>

  <target name="test5">
    <fail message="test5 exits with error"/>
  </target>

  <target name="testLogCaptureActive">
    <au:assertReferenceSet refid="ant.antunit.log"/>
  </target>

  <target name="test">
    <fail>should be ignored</fail>
  </target>

  <target name="tearDown">
    <echo>tearDown</echo>
  </target>

together with

    <au:antunit>
      <file file="antunit/base.xml"/>
      <au:plainlistener/>
    </au:antunit>

results in output similar to

[au:antunit] Build File: .../src/etc/testcases/antunit/base.xml
[au:antunit] Tests run: 5, Failures: 1, Errors: 1, Time elapsed: 0.216 sec
[au:antunit] Target: test2 took 0.001 sec
[au:antunit] Target: test1 took 0.001 sec
[au:antunit] Target: testLogCaptureActive took 0.128 sec
[au:antunit] Target: test5  caused an ERROR
[au:antunit]    at line 56, column 45
[au:antunit]    Message: test5 exits with error
[au:antunit]    took 0.01 sec
[au:antunit] Target: test4  FAILED
[au:antunit]    at line 50, column 42
[au:antunit]    Message: test4 fails
[au:antunit]    took 0.003 sec