1<?xml version="1.0" standalone="no"?> 2<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd"> 3<!-- 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the "License"); 9 * you may not use this file except in compliance with the License. 10 * You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, software 15 * distributed under the License is distributed on an "AS IS" BASIS, 16 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 17 * See the License for the specific language governing permissions and 18 * limitations under the License. 19--> 20<s1 title="Getting Started"> 21<ul> 22<li><link anchor="quickstart">Quick Start</link></li> 23<li><link anchor="downloading">Downloading the code</link></li> 24<li><link anchor="how-to-build">Building the Tests</link></li> 25</ul> 26 27 <anchor name="quickstart"/> 28 <s2 title="Quick Start"> 29 <note>This section assumes you are already familiar with 30 <jump href="http://xml.apache.org/xalan-j/readme.html#build">building Xalan-J</jump> and with 31 <jump href="http://jakarta.apache.org/ant/">Ant</jump>.</note> 32 <p>Set JAVA_HOME, and have your classes.zip or tools.jar in the CLASSPATH.</p> 33 <p>Here are some sample commands to build and run tests:</p> 34 <p><code>cd /builds </code> 35 <br/><code>checkout xml-xalan/java </code> Get the Xalan-J code (or simply get a nightly build or distro) 36 <br/><code>cd xml-xalan/java </code> 37 <br/><code>build jar </code> Build Xalan-J as usual 38 <br/><code>build smoketest </code> Run the build Smoketest (optional; simply calls the smoketest target below) 39 </p> 40 <p><code>cd /builds </code> 41 <br/><code>checkout xml-xalan/test </code> 42 <br/><code>cd xml-xalan/test </code> 43 <br/><code>build jar </code> Build the test framework/harness and most API/conf/etc. tests into <code>java/build/testxsl.jar </code> 44 <br/><code>build smoketest </code> Run the build Smoketest (includes a selection of API tests and the conf tests); results in smoketest/ 45 <br/><code>build conf </code> Run the StylesheetTestletDriver over the conf dir; results in results-conf/ 46 <br/><code>build conf -Dqetest.optionName=valueName -Dqetest.category=axes </code> Run the StylesheetTestletDriver over the conf dir; passing options, and only on the axes subdirectory 47 <br/><code>build api -DtestClass=TransformerAPITest </code> Run a single API test; results in results-api/ 48 <br/><code>build harness </code> Run the full set of individual API tests; results in results-api/ 49 </p> 50 <p><code>build extensions.classes </code> Compile the tests/extensions tests 51 <br/><code>build extensions </code> Run the tests/extensions tests 52 <br/><code>build bugzilla.classes </code> Compile the tests/bugzilla bug regression tests 53 <br/><code>build bugzilla </code> Run the tests/bugzilla bug regression tests 54 <br/><code>build clean </code> Clean up the built automation (does not clean any results you've generated) 55 <br/><code>build -h </code> Get help on build.bat/build.sh options and Ant targets 56 </p> 57 <p>Changing options:</p> 58 <p>Since we use the Ant test/build.xml script to kick off tests, <link idref="run" anchor="test-options">test options</link> 59 get passed slightly differently. The actual options the tests see and use 60 remain the same as before, however when you invoke Ant you need to specify the 61 options with a -D and a prefix that Ant uses and then strips off in XSLTestAntTask.</p> 62 <p>Default options (inputDir, loggingLevel, etc.) are now all stored in test.properties. 63 Overall defaults are prefixed with <code>qetest.</code>, which are used if no other 64 type of test is specified. Each type of test (api, conf, perf, contrib, etc.) has 65 it's own set of some prefixed options - namely api.inputDir, api.outputDir, api.goldDir and 66 api.logFile, etc..</p> 67 <p>Users may override the defaults in one of two ways:</p> 68 <ul> 69 <li>Create a <code>my.test.properties</code> file with any options you wish to use 70 in the xml-xalan/test directory. This will 71 override any options set in the test.properties or build.xml files. The format 72 is the same as the test.properties file. A different name of this file may be specified 73 using -Dlocal.properties=new.name.properties on the command line</li> 74 <li>Pass options on the command line. This is the same as passing options to 75 java or your JDK, so you must use the <code>-Dname=value</code> format.</li> 76 </ul> 77 <p><code>build conf -Dconf.category=axes -Dconf.flavor=trax.sax </code> This runs 78 the normal conf tests, but only on the axes subdir, and using the TraxSaxWrapper class. 79 <br/><code>build api -DtestClass=TransformStateTest -Dapi.loggingLevel=30 </code> This runs 80 the org.apache.qetest.xalanj2.TransformStateTest with a lower loggingLevel (so less is output). 81 Note that testClass is one of the few properties that is not prefixed, since it is 82 not passed on to the test itself, but is only used by the Ant script to load the test. 83 </p> 84 </s2> 85 86 <anchor name="downloading"/> 87 <s2 title="Downloading the tests"> 88 <note>Since these tests are primarily to help developers test their 89 changes to Xalan source code, we don't currently provide prebuilt 90 builds of the test code. Most tests also require Xalan-J, even 91 if you are testing a Xalan-C build.</note> 92 <p>To use the tests, you will need both a working build of Xalan-J 93 as well as the sources for the tests themselves. 94 </p><p>To download Xalan builds, see the: 95 <jump href="http://xml.apache.org/xalan-j/dist/">Xalan-J download page</jump> or the 96 <jump href="http://xml.apache.org/xalan-c/dist/">Xalan-C download page</jump> 97 </p><p>To get the test sources, do the following: 98 <br/>Check out the xml-xalan\test repository <jump href="http://xml.apache.org/cvs.html">directly from CVS</jump> 99 (<jump href="http://xml.apache.org/cvs.html">read-only access</jump> is available to all). 100 <br/><br/> 101 </p> 102 103 </s2> 104 105 <anchor name="how-to-build"/> 106 <s2 title="Building the Tests"> 107 <p>Since the test automation is written in Java, you must build it before running 108 any tests. Like Xalan-J, we use Ant build.xml files as 'makefiles' to build the 109 project. A copy of the Ant runtime files is provided in the xml-xalan/java/tools directory if you 110 need them; you may also use your own copy of Ant if you have it installed. 111 Unless specifically noted, all testing code should work either on Windows or 112 UNIX systems; adjust .sh/.bat and path\separators/as needed. Note that paths 113 in .properties files may always use forward / slashes since Ant's path 114 handling will always do the proper thing.</p> 115 116 <p>This assumes you already have a version of Xalan-J in \builds\xml-xalan\java 117 This may either be a distribution or a copy you pulled from CVS and built yourself.</p> 118 <p>Download the tests to \builds\xml-xalan\test.</p> 119 <p><code>cd \builds\xml-xalan\test </code> 120 <br/><code>build jar </code> This calls build.bat/.sh to find a copy of ant.jar and an 121 xml parser (which Ant requires). It then calls Ant to run the 'jar' target in the 122 default build.xml file. This will compile all the base test reporting libraries and 123 framework, as well as the most common test drivers and API tests. 124 </p> 125 <p>The default way to build and run the tests assumes you have both the xml-xalan/java 126 and xml-xalan/test directories locally, as if you were a developer on xalan. See below 127 for a simple alternate way to set your classpath using JARDIR. This allows QE/QA/test 128 people to run the same set of tests quickly against different versions of the product.</p> 129 <note>Using JARDIR is no longer fully supported due to lack of 130 interest. Those wishing to manage custom classpaths are welcome 131 to submit patches to allow this in an automated fashion.</note> 132 133 <p>The default jar target builds all TestletDrivers and most of the tests. 134 A few kinds of tests require separate targets to compile since they have 135 extra dependencies. In particular, any XSLTC-specific API tests or 136 TransformWrapper subclasses are compiled in a separate set of targets.</p> 137 138 <p>Users of automated IDE's that automatically compile all *.java files 139 in the source tree will either have to use the Ant build.xml script or may 140 have to manually compile certain files with the extra dependencies. Note that 141 JUnit is only required for the special qetesttest directory, which is only used to 142 test the qetest framework itself and is not needed to test Xalan.</p> 143 <p>Note that there are a few precompiled .class files in the test/java/src/ area. 144 By default these are simply copied into the testxsl.jar for you. These are files 145 that require extra dependencies to compile, and change infrequently, so as a 146 convenience they're checked in to the repository as precompiled .class files as well as source.</p> 147 <p>Building the Javadocs for the tests is done by <code>build.bat javadocs </code>, and 148 is best done under JDK 1.2.2 or higher - they will build with JDK 1.1.8, but not 149 all the links will work properly.</p> 150 <p>Building these top-level documents in the xdocs directory can 151 be done with <code>build.bat docs </code> and must be done under JDK 1.2.2 or higher, 152 since the Xalan-related stylebook code that we use requires that. </p> 153 </s2> 154</s1> 155