| <!-- |
| 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. |
| --> |
| <html> |
| <head> |
| <meta http-equiv="Content-Language" content="en-us"></meta> |
| <link rel="stylesheet" type="text/css" href="style.css"> |
| <title>AntUnit Task</title> |
| </head> |
| |
| <body> |
| <h2><a name="antunit">AntUnit</a></h2> |
| |
| <h3>Description</h3> |
| |
| <p>Runs Ant on targets of a build file that follow a certain |
| naming convention. If Ant throws the special subclass of |
| <code>BuildException</code> that the |
| <a href="assert.html"><code>assertTrue</code></a> |
| 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.</p> |
| |
| <p>Tests are specified via ResourceCollections.</p> |
| |
| <p>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.</p> |
| |
| <p>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).</p> |
| |
| <p>Each test target is run in a fresh Ant project, i.e. each test |
| target has a fresh set of properties and references.</p> |
| |
| <p>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.</p> |
| |
| <p><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.</p> |
| |
| <p>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:</p> |
| |
| <pre> |
| /* |
| * 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 <code>logLevel == Project.MSG_ERR</code>. |
| */ |
| public String getErrLog(); |
| /** |
| * All messages with <code>logLevel == Project.MSG_WARN</code> or |
| * more severe. |
| */ |
| public String getWarnLog(); |
| /** |
| * All messages with <code>logLevel == Project.MSG_INFO</code> or |
| * more severe. |
| */ |
| public String getInfoLog(); |
| /** |
| * All messages with <code>logLevel == Project.MSG_VERBOSE</code> or |
| * more severe. |
| */ |
| public String getVerboseLog(); |
| /** |
| * All messages with <code>logLevel == Project.MSG_DEBUG</code> or |
| * more severe. |
| */ |
| public String getDebugLog(); |
| } |
| </pre> |
| |
| <p>Additionally, the contents of the log can be accessed through a |
| <a href="logcontent.html">LogContent</a> resource.</p> |
| |
| <h3>Parameters</h3> |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">failOnError</td> |
| <td valign="top">Whether to stop the build if one of the tests |
| fails/causes an error. Defaults to true.</td> |
| <td align="center">No.</td> |
| </tr> |
| <tr> |
| <td valign="top">errorProperty</td> |
| <td valign="top">Name of the Ant property to set if one of the |
| tests fails/causes an error. Only useful if the failOnError |
| attribute is set to false.</td> |
| <td align="center">No.</td> |
| </tr> |
| </table> |
| |
| <h3>Parameters specified as nested elements</h3> |
| |
| <h4>any file system resource collection</h4> |
| |
| <p>Specifies the build files to run as tests. At least one |
| resource is required.</p> |
| |
| <h4>any implementation of AntUnitListener</h4> |
| |
| <p>Creates a test listener that gets attached to the task.</p> |
| |
| <p>Some listeners are part of this antlib:</p> |
| |
| <ul> |
| <li><a href="plainlistener.html"><plainlistener/></a> |
| creates reports similar to the "plain" <formatter> of the |
| <junit> task.</li> |
| <li><a href="xmllistener.html"><xmllistener/></a> is similar |
| to the "xml" <formatter>.</li> |
| <li><a href="logforwarder.html"><logforwarder/></a> |
| forwards log output from the project under test to the project |
| executing the antunit task.</li> |
| </ul> |
| |
| <h4>propertyset</h4> |
| |
| <p><a |
| href="http://ant.apache.org/manual/Types/propertyset.html"><propertyset></a>s |
| can be used to pass properties to the build files under test.</p> |
| |
| <h4>reference</h4> |
| |
| <p>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.</p> |
| |
| <table border="1" cellpadding="2" cellspacing="0"> |
| <tr> |
| <td valign="top"><b>Attribute</b></td> |
| <td valign="top"><b>Description</b></td> |
| <td align="center" valign="top"><b>Required</b></td> |
| </tr> |
| <tr> |
| <td valign="top">refid</td> |
| <td valign="top">The reference ID to inherit</td> |
| <td align="center" valign="middle" rowspan="2">Exactly one of these</td> |
| </tr> |
| <tr> |
| <td valign="top">regex</td> |
| <td valign="top">A regular expression identifying a group of reference IDs to inherit.</td> |
| </tr> |
| <tr> |
| <td valign="top">torefid</td> |
| <td valign="top">The ID of the reference in the test project. </td> |
| <td align="center" valign="middle" width="25%">No. If this reference appears inside |
| a <a href="#referenceset"><referenceset></a> with a nested mapper element, the mapper |
| will be used to determine the target reference ID. Otherwise, defaults to the source |
| reference ID.</td> |
| </tr> |
| </table> |
| |
| <a name="referenceset"/><h4>referenceset</h4> |
| |
| <p>References can be grouped inside a <referenceset> element for clarity. Additionally, <referenceset> |
| elements may contain exactly one nested <a href="http://ant.apache.org/manual/CoreTypes/mapper.html"><mapper></a> |
| element, which defines how source reference IDs are translated into target reference IDs. For example, |
| |
| <pre> |
| <au:antunit> |
| <referenceset> |
| <reference refid="first.ref"/> |
| <reference refid="second.ref"/> |
| <mapper type="regexp" from="(.*)\.ref" to="mapped.ref.\1"/> |
| </referenceset> |
| </au:antunit> |
| </pre> |
| </p> |
| |
| <h3>Examples</h3> |
| |
| <p>This build file snippet (from src/etc/testcases/antunit/base.xml)</p> |
| <pre> |
| <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> |
| </pre> |
| |
| <p>together with</p> |
| |
| <pre> |
| <au:antunit> |
| <file file="antunit/base.xml"/> |
| <au:plainlistener/> |
| </au:antunit> |
| </pre> |
| |
| <p>results in output similar to</p> |
| |
| <pre> |
| [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 |
| </pre> |
| </body> |
| </html> |