Some javadoc enhancements in JUnitTask.

Submitted by:	robert burrell donkin <robertdonkin@mac.com>

<junit> can now set a property on failed tests.

PR: 1794
Submitted by:	Robert Watkins <robert.watkins@qsipayments.com>

Don't format the test run-times in XML report. They are not intended
to be read by humans anyway but give the XSLT processor a hard time to
parse otherwise.

PR: 2314


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@269336 13f79535-47bb-0310-9956-ffa450edef68

WHATSNEW

@@ -28,6 +28,9 @@ Changes that could break older environments:
   this may yield different results on filesystems that support
   symbolic links.
 
+* The output generated by the xml formatter for <junit> has changed
+  again, it doesn't format the numeric value in the time attribute anymore.
+
 Other changes:
 --------------
 
@@ -115,6 +118,8 @@ Other changes:
 * <available> has a new filepath attribute/nested element that allows
   you top search for a file in a given path.
 
+* <junit> can now optionally set a property on test failure.
+
 Fixed bugs:
 -----------
 

src/main/org/apache/tools/ant/taskdefs/optional/junit/BaseTest.java

@@ -73,6 +73,9 @@ public abstract class BaseTest {
     /** destination directory */
     protected File destDir = null;
 
+    protected String failureProperty;
+    protected String errorProperty;
+
     public void setFork(boolean value) {
         fork = value;
     }
@@ -127,4 +130,19 @@ public abstract class BaseTest {
         return null;
     }
 
+    public java.lang.String getFailureProperty() {
+        return failureProperty;
+    }
+    
+    public void setFailureProperty(String failureProperty) {
+        this.failureProperty = failureProperty;
+    }
+    
+    public java.lang.String getErrorProperty() {
+        return errorProperty;
+    }
+    
+    public void setErrorProperty(String errorProperty) {
+        this.errorProperty = errorProperty;
+    }
 }

src/main/org/apache/tools/ant/taskdefs/optional/junit/JUnitTask.java

@@ -84,18 +84,65 @@ import java.net.URL;
 /**
  * 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>
+ *   &lt;target name="test-int-chars" depends="jar-test"&gt;
+ *       &lt;echo message="testing international characters"/&gt;
+ *       &lt;junit printsummary="no" haltonfailure="yes" fork="false"&gt;
+ *           &lt;classpath refid="classpath"/&gt;
+ *           &lt;formatter type="plain" usefile="false" /&gt;
+ *           &lt;test name="org.apache.ecs.InternationalCharTest" /&gt;
+ *       &lt;/junit&gt;
+ *   &lt;/target&gt;
+ * </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>
+ * &lt;target name="run-tests" depends="dump-info,compile-tests" if="junit.present"&gt;
+ *   &lt;junit printsummary="no" haltonfailure="yes" fork="${junit.fork}"&gt;
+ *     &lt;jvmarg value="-classic"/&gt;
+ *     &lt;classpath refid="tests-classpath"/&gt;
+ *     &lt;sysproperty key="build.tests" value="${build.tests}"/&gt;
+ *     &lt;formatter type="brief" usefile="false" /&gt;
+ *     &lt;batchtest&gt;
+ *       &lt;fileset dir="${tests.dir}"&gt;
+ *         &lt;include name="**&#047;*Test*" /&gt;
+ *       &lt;/fileset&gt;
+ *     &lt;/batchtest&gt;
+ *   &lt;/junit&gt;
+ * &lt;/target&gt;
+ * </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>&lt;junit&gt;</code> and <code>&lt;batch&gt;</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>{@link #setTimeout} property sets the maximum time allowed before a test is 'timed out'
+ * <li>{@link #setMaxmemory} property sets memory assignment for the forked jvm
+ * <li>{@link #setJvm} property allows the jvm to be specified
+ * <li>The <code>&lt;jvmarg&gt;</code> element sets arguements to be passed to the forked jvm 
+ * </ul>
  * @author Thomas Haas
  * @author <a href="mailto:stefan.bodewig@epost.de">Stefan Bodewig</a>
  * @author <a href="mailto:sbailliez@imediation.com">Stephane Bailliez</a>
- * @author <a href="mailto:Gerrit.Riessen@web.de">Gerrit Riessen</a> -
+ * @author <a href="mailto:Gerrit.Riessen@web.de">Gerrit Riessen</a>
  * @author <a href="mailto:erik@hatcher.net">Erik Hatcher</a>
+ *
+ * @see JUnitTest
+ * @see BatchTest
  */
 public class JUnitTask extends Task {
 
@@ -113,7 +160,7 @@ public class JUnitTask extends Task {
      * 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();
@@ -123,11 +170,25 @@ public class JUnitTask extends Task {
         }
     }
 
+    /**
+     * Tells this task to set the named property to "true" when there is a error in a test.
+     * This property is applied on all BatchTest (batchtest) and JUnitTest (test),
+     * however, it can possibly be overriden by their own properties.
+     * @param  value  the name of the property to set in the event of an error.
+     */
+    public void setErrorProperty(String propertyName) {
+        Enumeration enum = allTests();
+        while (enum.hasMoreElements()) {
+            BaseTest test = (BaseTest) enum.nextElement();
+            test.setErrorProperty(propertyName);
+        }
+    }
+
     /**
      * 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,15 +198,27 @@ public class JUnitTask extends Task {
         }
     }
 
+    /**
+     * Tells this task to set the named property to "true" when there is a failure in a test.
+     * This property is applied on all BatchTest (batchtest) and JUnitTest (test),
+     * however, it can possibly be overriden by their own properties.
+     * @param  value  the name of the property to set in the event of an failure.
+     */
+    public void setFailureProperty(String propertyName) {
+        Enumeration enum = allTests();
+        while (enum.hasMoreElements()) {
+            BaseTest test = (BaseTest) enum.nextElement();
+            test.setFailureProperty(propertyName);
+        }
+    }
 
     /**
      * Tells whether a JVM should be forked for each testcase. It avoids interference
      * 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();
@@ -190,7 +263,6 @@ public class JUnitTask extends Task {
      * @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;
@@ -244,6 +316,9 @@ public class JUnitTask extends Task {
         commandline.addSysproperty(sysp);
     }
     
+    /**
+     * <code>&lt;classpath&gt;</code> allows classpath to be set for tests.
+     */
     public Path createClasspath() {
         return commandline.createClasspath(project).createPath();
     }
@@ -306,6 +381,9 @@ public class JUnitTask extends Task {
         }
     }
 
+    /**
+     * 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.
@@ -335,12 +413,22 @@ public class JUnitTask extends Task {
         // just log a statement
         boolean errorOccurredHere = exitValue == JUnitTestRunner.ERRORS;
         boolean failureOccurredHere = exitValue != JUnitTestRunner.SUCCESS;
-        if (errorOccurredHere && test.getHaltonerror()
-            || failureOccurredHere && test.getHaltonfailure()) {
-            throw new BuildException("Test "+test.getName()+" failed"+(wasKilled ? " (timeout)" : ""),
-                                     location);
-        } else if (errorOccurredHere || failureOccurredHere) {
-            log("TEST "+test.getName()+" FAILED" + (wasKilled ? " (timeout)" : ""), Project.MSG_ERR);
+        if (errorOccurredHere || failureOccurredHere) {
+            if (errorOccurredHere && test.getHaltonerror()
+                || failureOccurredHere && test.getHaltonfailure()) {
+                throw new BuildException("Test "+test.getName()+" failed"
+                                         +(wasKilled ? " (timeout)" : ""),
+                                         location);
+            } else {
+                log("TEST "+test.getName()+" FAILED" 
+                    + (wasKilled ? " (timeout)" : ""), Project.MSG_ERR);
+                if (errorOccurredHere && test.getErrorProperty() != null) {
+                    project.setProperty(test.getErrorProperty(), "true");
+                }
+                if (failureOccurredHere && test.getFailureProperty() != null) {
+                    project.setProperty(test.getFailureProperty(), "true");
+                }
+            }
         }
     }
 
@@ -492,7 +580,7 @@ public class JUnitTask extends Task {
     }
 
     /**
-     * get the default output for a formatter.
+     * Get the default output for a formatter.
      */
     protected OutputStream getDefaultOutput(){
         return new LogOutputStream(this, Project.MSG_INFO);

src/main/org/apache/tools/ant/taskdefs/optional/junit/XMLJUnitResultFormatter.java

@@ -55,7 +55,6 @@
 package org.apache.tools.ant.taskdefs.optional.junit;
 
 import java.io.*;
-import java.text.NumberFormat;
 import java.text.CharacterIterator;
 import java.text.StringCharacterIterator;
 import java.util.*;
@@ -86,11 +85,6 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
         }
     }
 
-    /**
-     * Formatter for timings.
-     */
-    private NumberFormat nf = NumberFormat.getInstance(Locale.US);
-
     /**
      * The XML document.
      */
@@ -157,8 +151,7 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
         rootElement.setAttribute(ATTR_TESTS, ""+suite.runCount());
         rootElement.setAttribute(ATTR_FAILURES, ""+suite.failureCount());
         rootElement.setAttribute(ATTR_ERRORS, ""+suite.errorCount());
-        rootElement.setAttribute(ATTR_TIME,
-                                 nf.format(suite.getRunTime()/1000.0));
+        rootElement.setAttribute(ATTR_TIME, ""+(suite.getRunTime()/1000.0));
         if (out != null) {
             Writer wri = null;
             try {
@@ -199,7 +192,7 @@ public class XMLJUnitResultFormatter implements JUnitResultFormatter, XMLConstan
      */
     public void endTest(Test test) {
         currentTest.setAttribute(ATTR_TIME,
-                                 nf.format((System.currentTimeMillis()-lastTestStart)
+                                 ""+((System.currentTimeMillis()-lastTestStart)
                                            / 1000.0));
     }