improved formating and comments, to use as 'template' to point others to in build wiki pages
diff --git a/tests/org.eclipse.wst.sse.core.tests/test.xml b/tests/org.eclipse.wst.sse.core.tests/test.xml index b8e3cbe..4344774 100644 --- a/tests/org.eclipse.wst.sse.core.tests/test.xml +++ b/tests/org.eclipse.wst.sse.core.tests/test.xml
@@ -1,16 +1,24 @@ <?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 --> + <!-- + ===================================================== + 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.wst.sse.core.tests" /> @@ -20,46 +28,85 @@ <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}" /> + --> - <!-- 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="plugin-name: ${plugin-name}" /> - <echo message="classname: ${classname}" /> - <echo message="testType ${testType}" /> - - + <!-- + ===================================================== + 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 proved" + unless="eclipse-home" /> + <fail + message="Error: missing property. buildDirectory must be proved" + unless="buildDirectory" /> + <fail + message="Error: missing property. buildLabel must be proved" + unless="buildLabel" /> + <echo + message="basedir: ${basedir}" /> + <echo + message="eclipse-home: ${eclipse-home}" /> + <echo + message="buildDirectory: ${buildDirectory}" /> + <echo + message="plugin-name: ${plugin-name}" /> + <echo + message="classname: ${classname}" /> + <echo + message="testType ${testType}" /> <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"> + + <!-- + 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" /> </delete> - <!-- make directory, in case path doesn't exist yet --> - <mkdir dir="${workspace}" /> - <!-- but delete to make sure fresh contents--> + + <!-- + 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"> - + <!-- + This suite target defines the tests that need to be run. + --> + <target + name="suite"> <ant target="${testType}" antfile="${library-file}" @@ -77,24 +124,31 @@ name="plugin-path" value="${eclipse-home}/plugins/${plugin-name}" /> </ant> - <copy failonerror="false" file="${workspace}/.metadata/.log" tofile="${buildDirectory}/${buildLabel}/testResults/consolelogs/${plugin-name}.consolelog.txt" /> + </target> + + <!-- + 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 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" /> --> - </target> - - <!-- This target runs the test suite. Any actions that need to happen --> - <!-- after all the tests have been run should go here. --> + <!-- + 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"> @@ -110,5 +164,4 @@ value="${plugin-name}.xml" /> </ant> </target> - </project> \ No newline at end of file