295239 confusing "could not find .log file" message in JUnit logs
diff --git a/tests/org.eclipse.wtp.releng.tests/test.xml b/tests/org.eclipse.wtp.releng.tests/test.xml
index ab7a3a7..0ab97c7 100644
--- a/tests/org.eclipse.wtp.releng.tests/test.xml
+++ b/tests/org.eclipse.wtp.releng.tests/test.xml
@@ -1,123 +1,190 @@
 <?xml version="1.0" encoding="UTF-8"?>
-
-<project name="testsuite" default="run" basedir=".">
-
-    <!-- The following properties should be passed into this script -->
-    <!-- ${eclipse-home}   -->
-    <!-- ${buildDirectory}  -->
-    <!-- ${buildLabel}        -->
-
-    <!-- should be little need to change what's above  -->
-
-    <property name="plugin-name"
-              value="org.eclipse.wtp.releng.tests" />
-    <property name="classname"
-              value="org.eclipse.wtp.releng.tests.TestBuild" />
-    <property name="testType" value="core-test" />
-
-     <!-- if not otherwise defined, try the workbench value -->
-	<property name="eclipse-home" value="${eclipse.home}" />
-	
-
-    <!-- should be little need to change what's below -->
-
-    <echo message="basedir: ${basedir}" />
-    <echo message="eclipse-home: ${eclipse-home}" />
-    <echo message="buildDirectory: ${buildDirectory}" />
-    <echo message="buildLabel: ${buildLabel}" />
-    <echo message="plugin-name: ${plugin-name}" />
-    <echo message="classname: ${classname}" />
-    <echo message="testType ${testType}" />
-    <echo message="buildId ${buildId}" />
-
-
-    <property name="library-file"
-              value="${eclipse-home}/plugins/org.eclipse.test_3.1.0/library.xml" />
-    <property name="workspace"
-              value="${eclipse-home}/junitworkspaces/${plugin-name}" />
-
-    <!-- This target holds all initialization code that needs to be done for -->
-    <!-- all tests that are to be run. Initialization for individual tests -->
-    <!-- should be done within the body of the suite target. -->
-    <target name="init">
-        <tstamp />
+<project
+    name="testsuite"
+    default="run"
+    basedir=".">
+    <!--
+        ===================================================== There
+        should be no need to change what's above. (if there is, let us
+        know if the script can be improved.)
+        =====================================================
+    -->
+    <!--
+        Every suite needs to specify three thing: plugin-name, classname
+        - that provides the suite to test, and testType - either
+        core-test, or ui-test. There is an optional extraVMargs property
+        that some tests need to use in order to specify extra,
+        non-standard properties to the VM when it runs. If not need, no
+        need to specify it.
+    -->
+    <property
+        name="plugin-name"
+        value="org.eclipse.wtp.releng.tests"/>
+    <property
+        name="classname"
+        value="org.eclipse.wtp.releng.tests.TestBuild"/>
+    <property
+        name="testType"
+        value="core-test"/>
+    <!--
+        some test suites need to add special vm arguments when they run.
+        This is just an example. <property name="extraVMargs"
+        value="-DjsfRuntimeJarsDirectoryV1.1=${testDir}/${jsf1.1Dir}" />
+        <echo message="extraVMargs ${extraVMargs}" />
+    -->
+    <!--
+        ===================================================== There
+        should be no need to change what's below. (if there is, let us
+        know if the script can be improved.)
+        =====================================================
+    -->
+    <!--
+        There are some properties that must be provided by caller.
+    -->
+    <fail
+        message="Error: missing property. eclipse-home must be provided"
+        unless="eclipse-home"/>
+    <fail
+        message="Error: missing property. buildDirectory must be provided"
+        unless="buildDirectory"/>
+    <fail
+        message="Error: missing property. buildLabel must be provided"
+        unless="buildLabel"/>
+    <echo
+        message="basedir: ${basedir}"/>
+    <echo
+        message="eclipse-home: ${eclipse-home}"/>
+    <echo
+        message="buildDirectory: ${buildDirectory}"/>
+    <echo
+        message="buildLabel: ${buildLabel}"/>
+    <echo
+        message="plugin-name: ${plugin-name}"/>
+    <echo
+        message="classname: ${classname}"/>
+    <echo
+        message="testType ${testType}"/>
+    <echo
+        message="buildId ${buildId}"/>
+    <property
+        name="library-file"
+        value="${eclipse-home}/plugins/org.eclipse.test_3.1.0/library.xml"/>
+    <property
+        name="workspace"
+        value="${eclipse-home}/junitworkspaces/${plugin-name}"/>
+    <!--
+        This init target holds all initialization code that needs to be
+        done for all tests that are to be run. Initialization for
+        individual tests should be done within the body of the suite
+        target. Here it's a good idea to delete things that might have
+        been created if the test has already been ran, just in case the
+        test is being re-ran.
+    -->
+    <target
+        name="init">
+        <tstamp/>
         <delete>
-            <fileset dir="${eclipse-home}"
-                     includes="${plugin-name}.*xml" />
+            <fileset
+                dir="${eclipse-home}"
+                includes="${plugin-name}.*xml"/>
         </delete>
-        <!-- make directory, in case path doesn't exist yet -->
-        <mkdir dir="${workspace}" />
-        <!--  but delete to make sure fresh contents-->
-        <delete dir="${workspace}" quiet="true" />
-
+        <!--
+            make the workspace directory, in case path doesn't exist yet
+            but delete to make sure fresh contents, if it does exist
+        -->
+        <delete
+            dir="${workspace}"
+            quiet="true"/>
+        <mkdir
+            dir="${workspace}"/> 
     </target>
-
-    <!-- This target defines the tests that need to be run. -->
-    <target name="suite">
-
-        <ant target="${testType}"
-             antfile="${library-file}"
-             dir="${eclipse-home}">
-            <property name="data-dir"
-                      value="${workspace}" />
-            <property name="plugin-name"
-                      value="${plugin-name}" />
-            <property name="classname"
-                      value="${classname}" />
-            <property name="vmargs"
-                      value="-DbuildDirectory='${buildDirectory}' -DbuildLabel='${buildLabel}'" />
-            <property name="extraVMargs" value="-DrelengTestsPropertiesFile=${keyCfgFile}"/>
-
+    <!--
+        This suite target defines the tests that need to be run.
+    -->
+    <target
+        name="suite">
+        <ant
+            target="${testType}"
+            antfile="${library-file}"
+            dir="${eclipse-home}">
+            <property
+                name="data-dir"
+                value="${workspace}"/>
+            <property
+                name="plugin-name"
+                value="${plugin-name}"/>
+            <property
+                name="classname"
+                value="${classname}"/>
+            <property
+                name="vmargs"
+                value="-DbuildDirectory='${buildDirectory}' -DbuildLabel='${buildLabel}'"/>
+            <property
+                name="extraVMargs"
+                value="-DrelengTestsPropertiesFile=${keyCfgFile}"/>
         </ant>
+        <copy
+            failonerror="false"
+            file="${workspace}/.metadata/.log"
+            tofile="${buildDirectory}/${buildLabel}/testResults/consolelogs/${plugin-name}.consolelog.txt"/>
 
-        <copy failonerror="false"
-              file="${workspace}/.metadata/.log"
-              tofile="${buildDirectory}/${buildLabel}/testResults/consolelogs/${plugin-name}.consolelog.txt" />
+
+
 
         <!-- copy our particular xsl files to web directory for prosperity-->
-        <copy todir="${buildDirectory}/${buildLabel}/"
-              flatten="true">
-            <fileset dir="${eclipse-home}/plugins/">
-                     <include name="**/org.eclipse.wtp.releng.tests*/*.xsl" />
-    	     </fileset>
+        <copy
+            todir="${buildDirectory}/${buildLabel}/"
+            flatten="true">
+            <fileset
+                dir="${eclipse-home}/plugins/">
+                <include
+                    name="**/org.eclipse.wtp.releng.tests*/*.xsl"/>
+            </fileset>
         </copy>
-		<!-- and use them to create basic display -->
-        <xslt basedir="${buildDirectory}/${buildLabel}/"
-              includes="versioningReport_*"
-              destdir="${buildDirectory}/${buildLabel}/"
-              style="versioningReportToHTML.xsl"
-              force="true" />
-        
-        <echo file="${buildDirectory}/${buildLabel}/versioningReportName.php">
+        <!-- and use them to create basic display -->
+        <xslt
+            basedir="${buildDirectory}/${buildLabel}/"
+            includes="versioningReport_*"
+            destdir="${buildDirectory}/${buildLabel}/"
+            style="versioningReportToHTML.xsl"
+            force="true"/>
+        <echo
+            file="${buildDirectory}/${buildLabel}/versioningReportName.php">
             <![CDATA[<?php $versionReportFilename="versioningReport_${buildLabel}" ?>]]>
         </echo>
-        
-        
-        
-        
-        
     </target>
 
-    <!-- This target holds code to cleanup the testing environment after -->
-    <!-- after all of the tests have been run. You can use this target to -->
-    <!-- delete temporary files that have been created. -->
-    <target name="cleanup">
-        <!-- usually no need to delete workspace until next run, and leaving it allows inspection -->
-        <!-- <delete dir="${workspace}" quiet="true" /> -->
+    <!--
+        This clean target holds code to cleanup the testing environment
+        after after all of the tests have been run. You can use this
+        target to delete temporary files that have been created, if
+        required. But, it's usually best to leave it all, in case you'd
+        like to inspect it after a failed run. It will be deleted
+        eventually by the next clean build.
+    -->
+    <target
+        name="cleanup">
     </target>
-
-    <!-- This target runs the test suite. Any actions that need to happen -->
-    <!-- after all the tests have been run should go here. -->
-    <target name="run" depends="init,suite,cleanup">
-        <ant target="collect"
-             antfile="${library-file}"
-             dir="${eclipse-home}">
-            <property name="includes"
-                      value="${plugin-name}.*xml" />
-            <property name="output-file"
-                      value="${plugin-name}.xml" />
+    <!--
+        This run target is the master target that get's all the work
+        done. Most activity is actually done in the 'depends' tasks, but
+        any actions that need to happen after all the tests have been
+        run should go here, such as copying the results to a common
+        'save' directory.
+    -->
+    <target
+        name="run"
+        depends="init,suite,cleanup">
+        <ant
+            target="collect"
+            antfile="${library-file}"
+            dir="${eclipse-home}">
+            <property
+                name="includes"
+                value="${plugin-name}.*xml"/>
+            <property
+                name="output-file"
+                value="${plugin-name}.xml"/>
         </ant>
-
     </target>
-
 </project>
\ No newline at end of file