Add some documentation
git-svn-id: https://svn.apache.org/repos/asf/ant/sandbox/antlibs/antunit/trunk@202481 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Stefan Bodewig
parent
a052a4f9bf
commit
2684d535fb
|
|
@ -0,0 +1,119 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us"></meta>
|
||||
<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 ceratin
|
||||
naming convention. If Ant throws the special subclass of
|
||||
BuildException that the <a href="assert.html">assertTrue</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 filesets (to become ResourceCollection
|
||||
soon).</p>
|
||||
|
||||
<p>All targets whose name starts with "test" 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. Each
|
||||
test target is run in a fresh ant project.</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 only a single implementation of this interface is
|
||||
provided with this ant library.</p>
|
||||
|
||||
<h3>Parameters</h3>
|
||||
<p>This task doesn't support any attributes.</p>
|
||||
|
||||
<h3>Parameters specified as nested elements</h3>
|
||||
|
||||
<h4>fileset - or a child type</h4>
|
||||
|
||||
<p>Specifies the build files to run as tests. At least one
|
||||
fileset is required.</p>
|
||||
|
||||
<h4>any implementation of AntUnitListener</h4>
|
||||
|
||||
<p>Creates a test listener that gets attached to the task.</p>
|
||||
|
||||
<p>The only listener that is part of this antlib is
|
||||
<plainlistener/> this one creates reports similar to the
|
||||
"plain" <formatter> of the <junit> task.</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="tearDown">
|
||||
<echo>tearDown</echo>
|
||||
</target>
|
||||
</pre>
|
||||
|
||||
<p>together with</p>
|
||||
|
||||
<pre>
|
||||
<au:antunit>
|
||||
<fileset dir="antunit" includes="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: 4, Failures: 1, Errors: 1, Time elapsed: 0,187 sec
|
||||
[au:antunit] Target: test5 took 0,016 sec
|
||||
[au:antunit] Caused an ERROR
|
||||
[au:antunit] test5 exits with error
|
||||
[au:antunit] Target: test4 took 0,129 sec
|
||||
[au:antunit] FAILED
|
||||
[au:antunit] test4 fails
|
||||
[au:antunit] Target: test2 took 0 sec
|
||||
[au:antunit] Target: test1 took 0 sec
|
||||
</pre>
|
||||
|
||||
<hr/>
|
||||
<p align="center">Copyright © 2005 The Apache Software Foundation. All rights Reserved.</p>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,54 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us"></meta>
|
||||
<title>assertTrue Task</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<h2><a name="assertTrue">AssertTrue</a></h2>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
<p>Asserts a condition and makes the build fail (using a special
|
||||
kind of BuildException) if it doesn't hold true.</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">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Assertion failed".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Parameters specified as nested elements</h3>
|
||||
<h4>exactly one supported condition</h4>
|
||||
|
||||
<p>You can use all supported conditions of Ant's core as well as
|
||||
any class that implements the Condition interface as a nested
|
||||
child element. This element is required - exactly one child - and
|
||||
specifies the condition to assert.</p>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail with the message "foo is bar" if the
|
||||
property foo has the value bar:</p>
|
||||
|
||||
<pre>
|
||||
<assertTrue message="foo is bar">
|
||||
<not>
|
||||
<equals arg1="${foo}" arg2="bar"/>
|
||||
</not>
|
||||
</assertTrue message="foo is bar">
|
||||
</pre>
|
||||
|
||||
<hr/>
|
||||
<p align="center">Copyright © 2005 The Apache Software Foundation. All rights Reserved.</p>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,305 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us"></meta>
|
||||
<title>More Assertion Tasks</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<h1>More Assertion Tasks</h1>
|
||||
|
||||
<p>This Ant library also provides a couple of pre-defined
|
||||
assertions that are specializations of the <a
|
||||
href="assert.html"><assertTrue></a> task.</p>
|
||||
|
||||
<h2><a name="assertFalse">AssertFalse</a></h2>
|
||||
|
||||
<h3>Description</h3>
|
||||
|
||||
<p>Negates <assertTrue>. Supports the same attributes and
|
||||
nested elements as <assertTrue> but makes the build fail if
|
||||
the nested condition is true.</p>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail with the message "foo is bar" if the
|
||||
property foo has the value bar:</p>
|
||||
|
||||
<pre>
|
||||
<assertFalse message="foo is bar">
|
||||
<equals arg1="${foo}" arg2="bar"/>
|
||||
</assertFalse message="foo is bar">
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertEquals">assertEquals</a></h2>
|
||||
|
||||
<p>Asserts that its two arguments are equal.</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">expected</td>
|
||||
<td valign="top">First string to test.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">actual</td>
|
||||
<td valign="top">Second string to test.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Expected
|
||||
'<em>expected</em>' but was '<em>actual</em>'".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">casesensitive</td>
|
||||
<td valign="top">Perform a case sensitive comparision.
|
||||
Default is true.</td>
|
||||
<td valign="top" align="center">No</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail with the message "foo is not bar" if the
|
||||
property foo doesn't hold the value bar regardless of case:</p>
|
||||
|
||||
<pre>
|
||||
<assertEquals message="foo is bar" expected="bar"
|
||||
actual="${foo}" casesensitive="false"/>
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertPropertySet">assertPropertySet</a></h2>
|
||||
|
||||
<p>Asserts that a property has a value.</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">name</td>
|
||||
<td valign="top">Name of the property.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Expected
|
||||
property '<em>name</em>'".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail with the message "Expected property 'foo'"
|
||||
if the property foo is not defined:</p>
|
||||
|
||||
<pre>
|
||||
<assertPropertySet name="foo"/>
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertPropertyEquals">assertPropertyEquals</a></h2>
|
||||
|
||||
<p>Asserts that a given property is set and holds a certain
|
||||
value.</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">name</td>
|
||||
<td valign="top">Name of the property.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">value</td>
|
||||
<td valign="top">Expected value.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Expected property
|
||||
'<em>name</em>' to have value '<em>value</em>' but was
|
||||
'<em>value of property name</em>'".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">casesensitive</td>
|
||||
<td valign="top">Perform a case sensitive comparision.
|
||||
Default is true.</td>
|
||||
<td valign="top" align="center">No</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail with the message "foo is not bar" if the
|
||||
property foo doesn't hold the value bar regardless of case:</p>
|
||||
|
||||
<pre>
|
||||
<assertPropertyEquals message="foo is not bar" value="bar"
|
||||
name="foo" casesensitive="false"/>
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertFileExists">assertFileExists</a></h2>
|
||||
|
||||
<p>Asserts that a given file exists.</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">file</td>
|
||||
<td valign="top">Location of the file.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Expected
|
||||
file '<em>file</em>' to exist".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail if the file ${ant.home}/lib/ant.jar doesn't
|
||||
exist:</p>
|
||||
|
||||
<pre>
|
||||
<assertFileExists name="${ant.home}/lib/ant.jar"/>
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertFileDoesntExist">assertFileDoesntExists</a></h2>
|
||||
|
||||
<p>Asserts that a given file does not exists.</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">file</td>
|
||||
<td valign="top">Location of the file.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Didn't expect
|
||||
file '<em>file</em>' to exist".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail if the file ${ant.home}/lib/ant.jar
|
||||
exists:</p>
|
||||
|
||||
<pre>
|
||||
<assertFileDoesntExist name="${ant.home}/lib/ant.jar"/>
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertDestIsUpToDate">assertDestIsUpToDate</a></h2>
|
||||
|
||||
<p>Asserts that a dest file is more recent than the source
|
||||
file.</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">src</td>
|
||||
<td valign="top">source file.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">dest</td>
|
||||
<td valign="top">dest file.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Expected '<em>dest</em>'
|
||||
to be more recent than '<em>src</em>'".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail if the file ${ant.home}/lib/ant.jar is
|
||||
more recent than the current build file:</p>
|
||||
|
||||
<pre>
|
||||
<assertDestIsUptodate dest="${ant.file}" src="${ant.home}/lib/ant.jar"/>
|
||||
</pre>
|
||||
|
||||
<h2><a name="assertDestIsOutofDate">assertDestIsOutofDate</a></h2>
|
||||
|
||||
<p>Asserts that a source file is more recent than the dest
|
||||
file.</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">src</td>
|
||||
<td valign="top">source file.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">dest</td>
|
||||
<td valign="top">dest file.</td>
|
||||
<td valign="top" align="center">Yes</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td valign="top">message</td>
|
||||
<td valign="top">Message for the exception if the condition
|
||||
doesn't hold true. Defaults to "Expected '<em>src</em>'
|
||||
to be more recent than '<em>dest</em>'".</td>
|
||||
<td align="center">No.</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<h3>Examples</h3>
|
||||
|
||||
<p>Make the build fail if the file ${ant.home}/lib/ant.jar is
|
||||
older than the current build file:</p>
|
||||
|
||||
<pre>
|
||||
<assertDestIsOutofdate dest="${ant.file}" src="${ant.home}/lib/ant.jar"/>
|
||||
</pre>
|
||||
|
||||
<hr/>
|
||||
<p align="center">Copyright © 2005 The Apache Software Foundation. All rights Reserved.</p>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,109 @@
|
|||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us"></meta>
|
||||
<title>AntUnit Ant Library</title>
|
||||
</head>
|
||||
|
||||
<body>
|
||||
<h2>Introduction</h2>
|
||||
|
||||
<p>This is a library of Ant tasks that support writing tests for
|
||||
tasks using build files instead of JUnit.</p>
|
||||
|
||||
<h2>Requirements</h2>
|
||||
|
||||
<p>The current version requires Ant 1.7.x (read CVS HEAD).</p>
|
||||
|
||||
<h2>Where is it?</h2>
|
||||
|
||||
<p>The source code for the library currently lives in the
|
||||
developer sandbox in Ant's SVN - <a
|
||||
href="http://svn.apache.org/viewcvs.cgi/ant/sandbox/antlibs/antunit/trunk/">http://svn.apache.org/viewcvs.cgi/ant/sandbox/antlibs/antunit/trunk/</a>.</p>
|
||||
|
||||
<h2>Installation</h2>
|
||||
|
||||
<p>If you are building this from sources, run the antlib target
|
||||
and you'll get a file <code>ant-antunit.jar</code>.</p>
|
||||
|
||||
<p>There are several ways to use the tasks:</p>
|
||||
|
||||
<ul>
|
||||
<li>The traditional way:
|
||||
<pre>
|
||||
<taskdef
|
||||
resource="org/apache/ant/antunit/antlib.xml">
|
||||
<classpath>
|
||||
<pathelement location="YOUR-PATH-TO/ant-antunit.jar"/>
|
||||
</classpath>
|
||||
</taskdef>
|
||||
</pre>
|
||||
|
||||
With this you can use the tasks like plain Ant tasks, they'll
|
||||
live in the default namespace. I.e. if you can run
|
||||
<exec> without any namespace prefix, you can do so for
|
||||
<antunit> as well.
|
||||
</li>
|
||||
|
||||
<li>Similar, but assigning a namespace URI
|
||||
<pre>
|
||||
<taskdef
|
||||
uri="antlib:org.apache.ant.antunit"
|
||||
resource="org/apache/ant/antunit/antlib.xml">
|
||||
<classpath>
|
||||
<pathelement location="YOUR-PATH-TO/ant-antunit.jar"/>
|
||||
</classpath>
|
||||
</taskdef>
|
||||
</pre>
|
||||
|
||||
This puts you task into a separate namespace than Ant's
|
||||
namespace. You would use the tasks like
|
||||
|
||||
<pre>
|
||||
<project
|
||||
xmlns:au="antlib:org.apache.ant.antunit"
|
||||
xmlns="antlib:org.apache.tools.ant">
|
||||
...
|
||||
<au:assertTrue>
|
||||
<equals arg1="1" arg2="2"/>
|
||||
</au:assertTrue>
|
||||
</pre>
|
||||
|
||||
or a variation thereof.
|
||||
</li>
|
||||
|
||||
<li>Using Ant's autodiscovery. Place <code>ant-antunit.jar</code>
|
||||
into a directory and use <code>ant -lib
|
||||
DIR-CONTAINING-THE-JAR</code> or copy it into
|
||||
<code>ANT_HOME/lib</code> - and then in your build file, simply
|
||||
declare the namespace on the <code>project</code> tag:
|
||||
|
||||
<pre>
|
||||
<project
|
||||
xmlns:au="antlib:org.apache.ant.antunit"
|
||||
xmlns="antlib:org.apache.tools.ant">
|
||||
</pre>
|
||||
|
||||
And all tasks of this library will automatically be available
|
||||
in the <code>au</code> namespace without any
|
||||
<code>taskdef</code>.
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h2>Tasks</h2>
|
||||
|
||||
<ul>
|
||||
<li><a href="antunit.html">antunit</a> - run unit tests, the
|
||||
tests are defined using build files that contain targets which
|
||||
follow a certain namin convention. This task borrows a lot of
|
||||
ideas from JUnit 3 and the junit task.</li>
|
||||
|
||||
<li><a href="assert.html">assertTrue</a> - asserts a condition
|
||||
and throws a custom BuildException if the assertion fails.</li>
|
||||
|
||||
<li><a href="assertions.html">more assertions</a> - useful
|
||||
specialized versions of assertTrue.</li>
|
||||
|
||||
<hr/>
|
||||
<p align="center">Copyright © 2005 The Apache Software Foundation. All rights Reserved.</p>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
Reference in New Issue