java/xdocs/sources/tests/getstarted.xml

<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<!--
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements. See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership. The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the  "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
-->
<s1 title="Getting Started">
<ul>
<li><link anchor="quickstart">Quick Start</link></li>
<li><link anchor="downloading">Downloading the code</link></li>
<li><link anchor="how-to-build">Building the Tests</link></li>
</ul>

  <anchor name="quickstart"/>
  <s2 title="Quick Start">
    <note>This section assumes you are already familiar with 
    <jump href="http://xml.apache.org/xalan-j/readme.html#build">building Xalan-J</jump> and with 
    <jump href="http://jakarta.apache.org/ant/">Ant</jump>.</note>
    <p>Set JAVA_HOME, and have your classes.zip or tools.jar in the CLASSPATH.</p>
    <p>Here are some sample commands to build and run tests:</p>
    <p><code>cd /builds  </code>
    <br/><code>checkout xml-xalan/java  </code> Get the Xalan-J code (or simply get a nightly build or distro)
    <br/><code>cd xml-xalan/java  </code>
    <br/><code>build jar  </code> Build Xalan-J as usual
    <br/><code>build smoketest   </code> Run the build Smoketest (optional; simply calls the smoketest target below)
    </p>
    <p><code>cd /builds  </code>
    <br/><code>checkout xml-xalan/test  </code>
    <br/><code>cd xml-xalan/test  </code>
    <br/><code>build jar   </code> Build the test framework/harness and most API/conf/etc. tests into <code>java/build/testxsl.jar  </code>
    <br/><code>build smoketest   </code> Run the build Smoketest (includes a selection of API tests and the conf tests); results in smoketest/
    <br/><code>build conf   </code> Run the StylesheetTestletDriver over the conf dir; results in results-conf/
    <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
    <br/><code>build api -DtestClass=TransformerAPITest </code> Run a single API test; results in results-api/
    <br/><code>build harness </code> Run the full set of individual API tests; results in results-api/
    </p>
    <p><code>build extensions.classes   </code> Compile the tests/extensions tests
    <br/><code>build extensions   </code> Run the tests/extensions tests
    <br/><code>build bugzilla.classes   </code> Compile the tests/bugzilla bug regression tests
    <br/><code>build bugzilla   </code> Run the tests/bugzilla bug regression tests
    <br/><code>build clean   </code> Clean up the built automation (does not clean any results you've generated)
    <br/><code>build -h   </code> Get help on build.bat/build.sh options and Ant targets
    </p>
    <p>Changing options:</p>
    <p>Since we use the Ant test/build.xml script to kick off tests, <link idref="run" anchor="test-options">test options</link>
    get passed slightly differently.  The actual options the tests see and use 
    remain the same as before, however when you invoke Ant you need to specify the 
    options with a -D and a prefix that Ant uses and then strips off in XSLTestAntTask.</p>
    <p>Default options (inputDir, loggingLevel, etc.) are now all stored in test.properties. 
    Overall defaults are prefixed with <code>qetest.</code>, which are used if no other 
    type of test is specified.  Each type of test (api, conf, perf, contrib, etc.) has 
    it's own set of some prefixed options - namely api.inputDir, api.outputDir, api.goldDir and 
    api.logFile, etc..</p>
    <p>Users may override the defaults in one of two ways:</p>
    <ul>
    <li>Create a <code>my.test.properties</code> file with any options you wish to use
    in the xml-xalan/test directory.  This will 
    override any options set in the test.properties or build.xml files.  The format 
    is the same as the test.properties file.  A different name of this file may be specified 
    using -Dlocal.properties=new.name.properties on the command line</li>
    <li>Pass options on the command line.  This is the same as passing options to 
    java or your JDK, so you must use the <code>-Dname=value</code> format.</li>
    </ul>
    <p><code>build conf -Dconf.category=axes -Dconf.flavor=trax.sax  </code> This runs 
    the normal conf tests, but only on the axes subdir, and using the TraxSaxWrapper class.
    <br/><code>build api -DtestClass=TransformStateTest -Dapi.loggingLevel=30  </code> This runs 
    the org.apache.qetest.xalanj2.TransformStateTest with a lower loggingLevel (so less is output).
    Note that testClass is one of the few properties that is not prefixed, since it is 
    not passed on to the test itself, but is only used by the Ant script to load the test.
    </p>
  </s2>

  <anchor name="downloading"/>
  <s2 title="Downloading the tests">
    <note>Since these tests are primarily to help developers test their 
    changes to Xalan source code, we don't currently provide prebuilt 
    builds of the test code. Most tests also require Xalan-J, even 
    if you are testing a Xalan-C build.</note>
    <p>To use the tests, you will need both a working build of Xalan-J 
    as well as the sources for the tests themselves.
    </p><p>To download Xalan builds, see the:
    <jump href="http://xml.apache.org/xalan-j/dist/">Xalan-J download page</jump> or the 
    <jump href="http://xml.apache.org/xalan-c/dist/">Xalan-C download page</jump>
    </p><p>To get the test sources, do the following:
    <br/>Check out the xml-xalan\test repository <jump href="http://xml.apache.org/cvs.html">directly from CVS</jump> 
    (<jump href="http://xml.apache.org/cvs.html">read-only access</jump> is available to all).
    <br/><br/>
    </p>
    
  </s2>
      
  <anchor name="how-to-build"/>
  <s2 title="Building the Tests">
    <p>Since the test automation is written in Java, you must build it before running 
    any tests.  Like Xalan-J, we use Ant build.xml files as 'makefiles' to build the 
    project.  A copy of the Ant runtime files is provided in the xml-xalan/java/tools directory if you 
    need them; you may also use your own copy of Ant if you have it installed.  
    Unless specifically noted, all testing code should work either on Windows or 
    UNIX systems; adjust .sh/.bat and path\separators/as needed.  Note that paths 
    in .properties files may always use forward / slashes since Ant's path 
    handling will always do the proper thing.</p>

    <p>This assumes you already have a version of Xalan-J in \builds\xml-xalan\java  
    This may either be a distribution or a copy you pulled from CVS and built yourself.</p>
    <p>Download the tests to \builds\xml-xalan\test.</p>
    <p><code>cd \builds\xml-xalan\test  </code>
    <br/><code>build jar   </code> This calls build.bat/.sh to find a copy of ant.jar and an 
    xml parser (which Ant requires).  It then calls Ant to run the 'jar' target in the 
    default build.xml file.  This will compile all the base test reporting libraries and 
    framework, as well as the most common test drivers and API tests.
    </p>
    <p>The default way to build and run the tests assumes you have both the xml-xalan/java 
    and xml-xalan/test directories locally, as if you were a developer on xalan.  See below 
    for a simple alternate way to set your classpath using JARDIR.  This allows QE/QA/test 
    people to run the same set of tests quickly against different versions of the product.</p>
    <note>Using JARDIR is no longer fully supported due to lack of 
    interest.  Those wishing to manage custom classpaths are welcome 
    to submit patches to allow this in an automated fashion.</note>

    <p>The default jar target builds all TestletDrivers and most of the tests.  
    A few kinds of tests require separate targets to compile since they have 
    extra dependencies.  In particular, any XSLTC-specific API tests or 
    TransformWrapper subclasses are compiled in a separate set of targets.</p>

    <p>Users of automated IDE's that automatically compile all *.java files 
    in the source tree will either have to use the Ant build.xml script or may 
    have to manually compile certain files with the extra dependencies.  Note that 
    JUnit is only required for the special qetesttest directory, which is only used to 
    test the qetest framework itself and is not needed to test Xalan.</p>
    <p>Note that there are a few precompiled .class files in the test/java/src/ area.  
    By default these are simply copied into the testxsl.jar for you.  These are files 
    that require extra dependencies to compile, and change infrequently, so as a 
    convenience they're checked in to the repository as precompiled .class files as well as source.</p>
    <p>Building the Javadocs for the tests is done by <code>build.bat javadocs  </code>, and 
    is best done under JDK 1.2.2 or higher - they will build with JDK 1.1.8, but not 
    all the links will work properly.</p>
    <p>Building these top-level documents in the xdocs directory can 
    be done with <code>build.bat docs  </code> and must be done under JDK 1.2.2 or higher, 
    since the Xalan-related stylebook code that we use requires that. </p>
  </s2>
</s1>