Author: bodewig
Date: Wed Jun 29 21:48:49 2005
New Revision: 202481
URL: http://svn.apache.org/viewcvs?rev=202481&view=rev
Log:
Add some documentation
Added:
ant/sandbox/antlibs/antunit/trunk/docs/
ant/sandbox/antlibs/antunit/trunk/docs/antunit.html (with props)
ant/sandbox/antlibs/antunit/trunk/docs/assert.html (with props)
ant/sandbox/antlibs/antunit/trunk/docs/assertions.html (with props)
ant/sandbox/antlibs/antunit/trunk/docs/index.hmtl
Added: ant/sandbox/antlibs/antunit/trunk/docs/antunit.html
URL:
http://svn.apache.org/viewcvs/ant/sandbox/antlibs/antunit/trunk/docs/antunit.html?rev=202481&view=auto
==============================================================================
--- ant/sandbox/antlibs/antunit/trunk/docs/antunit.html (added)
+++ ant/sandbox/antlibs/antunit/trunk/docs/antunit.html Wed Jun 29 21:48:49 2005
@@ -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>
\ No newline at end of file
Propchange: ant/sandbox/antlibs/antunit/trunk/docs/antunit.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: ant/sandbox/antlibs/antunit/trunk/docs/assert.html
URL:
http://svn.apache.org/viewcvs/ant/sandbox/antlibs/antunit/trunk/docs/assert.html?rev=202481&view=auto
==============================================================================
--- ant/sandbox/antlibs/antunit/trunk/docs/assert.html (added)
+++ ant/sandbox/antlibs/antunit/trunk/docs/assert.html Wed Jun 29 21:48:49 2005
@@ -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>
\ No newline at end of file
Propchange: ant/sandbox/antlibs/antunit/trunk/docs/assert.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: ant/sandbox/antlibs/antunit/trunk/docs/assertions.html
URL:
http://svn.apache.org/viewcvs/ant/sandbox/antlibs/antunit/trunk/docs/assertions.html?rev=202481&view=auto
==============================================================================
--- ant/sandbox/antlibs/antunit/trunk/docs/assertions.html (added)
+++ ant/sandbox/antlibs/antunit/trunk/docs/assertions.html Wed Jun 29 21:48:49
2005
@@ -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>
\ No newline at end of file
Propchange: ant/sandbox/antlibs/antunit/trunk/docs/assertions.html
------------------------------------------------------------------------------
svn:eol-style = native
Added: ant/sandbox/antlibs/antunit/trunk/docs/index.hmtl
URL:
http://svn.apache.org/viewcvs/ant/sandbox/antlibs/antunit/trunk/docs/index.hmtl?rev=202481&view=auto
==============================================================================
--- ant/sandbox/antlibs/antunit/trunk/docs/index.hmtl (added)
+++ ant/sandbox/antlibs/antunit/trunk/docs/index.hmtl Wed Jun 29 21:48:49 2005
@@ -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>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
