ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From bode...@apache.org
Subject svn commit: r202481 - in /ant/sandbox/antlibs/antunit/trunk/docs: ./ antunit.html assert.html assertions.html index.hmtl
Date Thu, 30 Jun 2005 04:48:50 GMT
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>&lt;antunit&gt; 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
+    &lt;plainlistener/&gt; this one creates reports similar to the
+    "plain" &lt;formatter&gt; of the &lt;junit&gt; task.</p>
+
+    <h3>Examples</h3>
+
+    <p>This build file snippet (from src/etc/testcases/antunit/base.xml)</p>
+<pre>
+  &lt;target name="setUp">
+    &lt;echo>setup&lt;/echo>
+  &lt;/target>
+
+  &lt;target name="test1">
+    &lt;echo>test1&lt;/echo>
+  &lt;/target>
+
+  &lt;target name="test2">
+    &lt;echo>test2&lt;/echo>
+  &lt;/target>
+
+  &lt;target name="Xtest3">
+    &lt;echo>test3&lt;/echo>
+  &lt;/target>
+
+  &lt;target name="test4">
+    &lt;au:assertTrue message="test4 fails">
+      &lt;istrue value="false"/>
+    &lt;/au:assertTrue>
+  &lt;/target>
+
+  &lt;target name="test5">
+    &lt;fail message="test5 exits with error"/>
+  &lt;/target>
+
+  &lt;target name="tearDown">
+    &lt;echo>tearDown&lt;/echo>
+  &lt;/target>
+</pre>
+
+    <p>together with</p>
+
+<pre>
+    &lt;au:antunit>
+      &lt;fileset dir="antunit" includes="base.xml"/>
+      &lt;au:plainlistener/>
+    &lt;/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 &copy; 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>
+      &lt;assertTrue message="foo is bar"&gt;
+        &lt;not&gt;
+          &lt;equals arg1="${foo}" arg2="bar"/&gt;
+        &lt;/not&gt;
+      &lt;/assertTrue message="foo is bar"&gt;
+    </pre>
+
+    <hr/>
+      <p align="center">Copyright &copy; 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">&lt;assertTrue&gt;</a> task.</p>
+
+    <h2><a name="assertFalse">AssertFalse</a></h2>
+
+    <h3>Description</h3>
+
+    <p>Negates &lt;assertTrue&gt;.  Supports the same attributes and
+    nested elements as &lt;assertTrue&gt; 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>
+      &lt;assertFalse message="foo is bar"&gt;
+        &lt;equals arg1="${foo}" arg2="bar"/&gt;
+      &lt;/assertFalse message="foo is bar"&gt;
+    </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>
+      &lt;assertEquals message="foo is bar" expected="bar"
+                      actual="${foo}" casesensitive="false"/&gt;
+    </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>
+      &lt;assertPropertySet name="foo"/&gt;
+    </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>
+      &lt;assertPropertyEquals message="foo is not bar" value="bar"
+                              name="foo" casesensitive="false"/&gt;
+    </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>
+      &lt;assertFileExists name="${ant.home}/lib/ant.jar"/&gt;
+    </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>
+      &lt;assertFileDoesntExist name="${ant.home}/lib/ant.jar"/&gt;
+    </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>
+      &lt;assertDestIsUptodate dest="${ant.file}" src="${ant.home}/lib/ant.jar"/&gt;
+    </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>
+      &lt;assertDestIsOutofdate dest="${ant.file}" src="${ant.home}/lib/ant.jar"/&gt;
+    </pre>
+
+    <hr/>
+      <p align="center">Copyright &copy; 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>
+          &lt;taskdef 
+            resource="org/apache/ant/antunit/antlib.xml"&gt;
+            &lt;classpath&gt;
+              &lt;pathelement location="YOUR-PATH-TO/ant-antunit.jar"/&gt;
+            &lt;/classpath&gt;
+          &lt;/taskdef&gt;
+        </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
+        &lt;exec&gt; without any namespace prefix, you can do so for
+        &lt;antunit&gt; as well.
+      </li>
+
+      <li>Similar, but assigning a namespace URI
+        <pre>
+          &lt;taskdef 
+            uri="antlib:org.apache.ant.antunit"
+            resource="org/apache/ant/antunit/antlib.xml"&gt;
+            &lt;classpath&gt;
+              &lt;pathelement location="YOUR-PATH-TO/ant-antunit.jar"/&gt;
+            &lt;/classpath&gt;
+          &lt;/taskdef&gt;
+        </pre>
+
+        This puts you task into a separate namespace than Ant's
+        namespace.  You would use the tasks like
+
+        <pre>
+          &lt;project
+            xmlns:au="antlib:org.apache.ant.antunit"
+            xmlns="antlib:org.apache.tools.ant"&gt;
+            ...
+            &lt;au:assertTrue&gt;
+              &lt;equals arg1="1" arg2="2"/&gt;
+            &lt;/au:assertTrue&gt;
+        </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>
+          &lt;project
+            xmlns:au="antlib:org.apache.ant.antunit"
+            xmlns="antlib:org.apache.tools.ant"&gt;
+        </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 &copy; 2005 The Apache Software Foundation. All
rights Reserved.</p>
+  </body>
+</html>



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org


Mime
View raw message