here's (one of) the promised documentation patch(es)
- robert
Index: src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTask.java =================================================================== RCS file: /home/cvs/jakarta-ant/src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTask.java,v retrieving revision 1.18 diff -u -r1.18 JUnitTask.java --- src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTask.java 2001/05/03 15:03:58 1.18 +++ src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTask.java 2001/07/03 21:30:48 @@ -79,17 +79,64 @@ /** * Ant task to run JUnit tests. * - * <p>JUnit is a framework to create unit test. It has been initially + * <p> JUnit is a framework to create unit test. It has been initially * created by Erich Gamma and Kent Beck. JUnit can be found at <a * href="http://www.junit.org";>http://www.junit.org</a>. * - * <p> To spawn a new Java VM to prevent interferences between - * different testcases, you need to enable <code>fork</code>. + * <p> <code>JUnitTask</code> can run a single specific <code>JUnitTest</code> using the <code>test</code> element. + * For example, the following target <code><pre> + * <target name="test-int-chars" depends="jar-test"> + * <echo message="testing international characters"/> + * <junit printsummary="no" haltonfailure="yes" fork="false"> + * <classpath refid="classpath"/> + * <formatter type="plain" usefile="false" /> + * <test name="org.apache.ecs.InternationalCharTest" /> + * </junit> + * </target> + * </pre></code> runs a single junit test (<code>org.apache.ecs.InternationalCharTest</code>) + * in the current VM using the path with id <code>classpath</code> as classpath + * and presents the results formatted using the standard <code>plain</code> formatter on the command line. + * + * <p> This task can also run batches of tests. + * The <code>batchtest</code> element creates a <code>BatchTest</code> based on a fileset. + * This allows, for example, all classes found in directory to be run as testcases. + * For example, <code><pre> + * <target name="run-tests" depends="dump-info,compile-tests" if="junit.present"> + * <junit printsummary="no" haltonfailure="yes" fork="${junit.fork}"> + * <jvmarg value="-classic"/> + * <classpath refid="tests-classpath"/> + * <sysproperty key="build.tests" value="${build.tests}"/> + * <formatter type="brief" usefile="false" /> + * <batchtest> + * <fileset dir="${tests.dir}"> + * <include name="**/*Test*" /> + * </fileset> + * </batchtest> + * </junit> + * </target> + * </pre></code> this target finds any classes with a <code>test</code> directory anywhere in their path + * (under the top <code>${tests.dir}</code>, of course) and creates <code>JUnitTest</code>'s for each one. * + * <p> Of course, <code><junit></code> and <code><batch></code> elements can be combined + * for more complex tests. For an example, see the ant <code>build.xml</code> target <code>run-tests</code> + * (the second example is an edited version). + * + * <p> To spawn a new Java VM to prevent interferences between + * different testcases, you need to enable <code>fork</code>. + * A number of attributes and elements allow you to set up how this JVM runs. + * <ul> + * <li>[EMAIL PROTECTED] #setTimeout} property sets the maximum time allowed before a test is 'timed out' + * <li>[EMAIL PROTECTED] #setMaxmemory} property sets memory assignment for the forked jvm + * <li>[EMAIL PROTECTED] #setJvm} property allows the jvm to be specified + * <li>The <code><jvmarg></code> element sets arguements to be passed to the forked jvm + * </ul> * @author Thomas Haas * @author <a href="mailto:[EMAIL PROTECTED]">Stefan Bodewig</a> * @author <a href="mailto:[EMAIL PROTECTED]">Stephane Bailliez</a> - * @author <a href="mailto:[EMAIL PROTECTED]">Gerrit Riessen</a> - + * @author <a href="mailto:[EMAIL PROTECTED]">Gerrit Riessen</a> + * + * @see JUnitTest + * @see BatchTest */ public class JUnitTask extends Task { @@ -107,7 +154,7 @@ * Tells this task to halt when there is an error in a test. * this property is applied on all BatchTest (batchtest) and JUnitTest (test) * however it can possibly be overridden by their own properties. - * @param value <tt>true</tt> if it should halt, otherwise <tt>false<tt> + * @param value <tt>true</tt> if it should halt, otherwise <tt>false</tt> */ public void setHaltonerror(boolean value) { Enumeration enum = allTests(); @@ -121,7 +168,7 @@ * Tells this task to halt when there is a failure in a test. * this property is applied on all BatchTest (batchtest) and JUnitTest (test) * however it can possibly be overridden by their own properties. - * @param value <tt>true</tt> if it should halt, otherwise <tt>false<tt> + * @param value <tt>true</tt> if it should halt, otherwise <tt>false</tt> */ public void setHaltonfailure(boolean value) { Enumeration enum = allTests(); @@ -137,9 +184,8 @@ * between testcases and possibly avoids hanging the build. * this property is applied on all BatchTest (batchtest) and JUnitTest (test) * however it can possibly be overridden by their own properties. - * @param value <tt>true</tt> if a JVM should be forked, otherwise <tt>false<tt> - * @see #setTimeout(Integer) - * @see #haltOntimeout(boolean) + * @param value <tt>true</tt> if a JVM should be forked, otherwise <tt>false</tt> + * @see #setTimeout */ public void setFork(boolean value) { Enumeration enum = allTests(); @@ -184,7 +230,6 @@ * @param value the maximum time (in milliseconds) allowed before declaring the test * as 'timed-out' * @see #setFork(boolean) - * @see #haltOnTimeout(boolean) */ public void setTimeout(Integer value) { timeout = value; @@ -238,6 +283,9 @@ commandline.addSysproperty(sysp); } + /** + * <code><classpath></code> allows classpath to be set for tests. + */ public Path createClasspath() { return commandline.createClasspath(project).createPath(); } @@ -289,6 +337,9 @@ } } + /** + * Run the tests. + */ protected void execute(JUnitTest test) throws BuildException { // set the default values if not specified //@todo should be moved to the test class instead. @@ -453,7 +504,7 @@ } /** - * get the default output for a formatter. + * Get the default output for a formatter. */ protected OutputStream getDefaultOutput(){ return new LogOutputStream(this, Project.MSG_INFO);
