blob: b481d8e5525ab1196de9fd15c87bd8124c35470f [file] [log] [blame]
<HTML><HEAD><SCRIPT language="JavaScript" src="resources/script.js" type="text/javascript"></SCRIPT><TITLE>Getting Started</TITLE></HEAD><BODY alink="#ff0000" bgcolor="#ffffff" leftmargin="4" link="#0000ff" marginheight="4" marginwidth="4" text="#000000" topmargin="4" vlink="#0000aa"><TABLE border="0" cellpadding="0" cellspacing="0" width="620"><TR><TD align="left" height="60" rowspan="3" valign="top" width="135"><IMG alt="logo" border="0" height="60" hspace="0" src="resources/logo.gif" vspace="0" width="135"></TD><TD align="left" colspan="4" height="5" valign="top" width="456"><IMG alt="line" border="0" height="5" hspace="0" src="resources/line.gif" vspace="0" width="456"></TD><TD align="left" height="60" rowspan="3" valign="top" width="29"><IMG alt="right" border="0" height="60" hspace="0" src="resources/right.gif" vspace="0" width="29"></TD></TR><TR><TD align="left" bgcolor="#0086b2" colspan="4" height="35" valign="top" width="456"><IMG alt="" border="0" height="35" hspace="0" src="graphics/getstarted-header.jpg" vspace="0" width="456"></TD></TR><TR><TD align="left" height="20" valign="top" width="168"><IMG alt="bottom" border="0" height="20" hspace="0" src="resources/bottom.gif" vspace="0" width="168"></TD><TD align="left" height="20" valign="top" width="96"><A href="http://xml.apache.org/" onMouseOut="rolloverOff('xml');" onMouseOver="rolloverOn('xml');" target="new"><IMG alt="http://xml.apache.org/" border="0" height="20" hspace="0" name="xml" onLoad="rolloverLoad('xml','resources/button-xml-hi.gif','resources/button-xml-lo.gif');" src="resources/button-xml-lo.gif" vspace="0" width="96"></A></TD><TD align="left" height="20" valign="top" width="96"><A href="http://www.apache.org/" onMouseOut="rolloverOff('asf');" onMouseOver="rolloverOn('asf');" target="new"><IMG alt="http://www.apache.org/" border="0" height="20" hspace="0" name="asf" onLoad="rolloverLoad('asf','resources/button-asf-hi.gif','resources/button-asf-lo.gif');" src="resources/button-asf-lo.gif" vspace="0" width="96"></A></TD><TD align="left" height="20" valign="top" width="96"><A href="http://www.w3.org/" onMouseOut="rolloverOff('w3c');" onMouseOver="rolloverOn('w3c');" target="new"><IMG alt="http://www.w3.org/" border="0" height="20" hspace="0" name="w3c" onLoad="rolloverLoad('w3c','resources/button-w3c-hi.gif','resources/button-w3c-lo.gif');" src="resources/button-w3c-lo.gif" vspace="0" width="96"></A></TD></TR></TABLE><TABLE border="0" cellpadding="0" cellspacing="0" width="620"><TR><TD align="left" valign="top" width="120"><IMG alt="join" border="0" height="14" hspace="0" src="resources/join.gif" vspace="0" width="120"><BR>
<A href="overview.html" onMouseOut="rolloverOff('side-overview');" onMouseOver="rolloverOn('side-overview');"><IMG alt="Overview" border="0" height="12" hspace="0" name="side-overview" onLoad="rolloverLoad('side-overview','graphics/overview-label-2.jpg','graphics/overview-label-3.jpg');" src="graphics/overview-label-3.jpg" vspace="0" width="120"></A><BR>
<IMG alt="Getting Started" border="0" height="12" hspace="0" src="graphics/getstarted-label-1.jpg" vspace="0" width="120"><BR>
<IMG alt="separator" border="0" height="6" hspace="0" src="resources/separator.gif" vspace="0" width="120"><BR>
<A href="apidocs/index.html" onMouseOut="rolloverOff('side-ext-10');" onMouseOver="rolloverOn('side-ext-10');"><IMG alt="Java API" border="0" height="12" hspace="0" name="side-ext-10" onLoad="rolloverLoad('side-ext-10','graphics/ext-10-label-2.jpg','graphics/ext-10-label-3.jpg');" src="graphics/ext-10-label-3.jpg" vspace="0" width="120"></A><BR>
<IMG alt="separator" border="0" height="6" hspace="0" src="resources/separator.gif" vspace="0" width="120"><BR>
<A href="faq.html" onMouseOut="rolloverOff('side-faq');" onMouseOver="rolloverOn('side-faq');"><IMG alt="FAQ" border="0" height="12" hspace="0" name="side-faq" onLoad="rolloverLoad('side-faq','graphics/faq-label-2.jpg','graphics/faq-label-3.jpg');" src="graphics/faq-label-3.jpg" vspace="0" width="120"></A><BR>
<A href="run.html" onMouseOut="rolloverOff('side-run');" onMouseOver="rolloverOn('side-run');"><IMG alt="Running Tests" border="0" height="12" hspace="0" name="side-run" onLoad="rolloverLoad('side-run','graphics/run-label-2.jpg','graphics/run-label-3.jpg');" src="graphics/run-label-3.jpg" vspace="0" width="120"></A><BR>
<A href="submit.html" onMouseOut="rolloverOff('side-submit');" onMouseOver="rolloverOn('side-submit');"><IMG alt="Writing New Tests" border="0" height="12" hspace="0" name="side-submit" onLoad="rolloverLoad('side-submit','graphics/submit-label-2.jpg','graphics/submit-label-3.jpg');" src="graphics/submit-label-3.jpg" vspace="0" width="120"></A><BR>
<A href="design.html" onMouseOut="rolloverOff('side-design');" onMouseOver="rolloverOn('side-design');"><IMG alt="Test Standards" border="0" height="12" hspace="0" name="side-design" onLoad="rolloverLoad('side-design','graphics/design-label-2.jpg','graphics/design-label-3.jpg');" src="graphics/design-label-3.jpg" vspace="0" width="120"></A><BR>
<A href="xalanc.html" onMouseOut="rolloverOff('side-xalanc');" onMouseOver="rolloverOn('side-xalanc');"><IMG alt="Xalan-C Tests" border="0" height="12" hspace="0" name="side-xalanc" onLoad="rolloverLoad('side-xalanc','graphics/xalanc-label-2.jpg','graphics/xalanc-label-3.jpg');" src="graphics/xalanc-label-3.jpg" vspace="0" width="120"></A><BR>
<IMG alt="separator" border="0" height="6" hspace="0" src="resources/separator.gif" vspace="0" width="120"><BR>
<A href="http://xml.apache.org/xalan-j" onMouseOut="rolloverOff('side-ext-28');" onMouseOver="rolloverOn('side-ext-28');"><IMG alt="Xalan-J 2.x" border="0" height="12" hspace="0" name="side-ext-28" onLoad="rolloverLoad('side-ext-28','graphics/ext-28-label-2.jpg','graphics/ext-28-label-3.jpg');" src="graphics/ext-28-label-3.jpg" vspace="0" width="120"></A><BR>
<A href="http://xml.apache.org/xalan" onMouseOut="rolloverOff('side-ext-30');" onMouseOver="rolloverOn('side-ext-30');"><IMG alt="Xalan-J 1.x" border="0" height="12" hspace="0" name="side-ext-30" onLoad="rolloverLoad('side-ext-30','graphics/ext-30-label-2.jpg','graphics/ext-30-label-3.jpg');" src="graphics/ext-30-label-3.jpg" vspace="0" width="120"></A><BR>
<A href="http://xml.apache.org/xalan-c" onMouseOut="rolloverOff('side-ext-32');" onMouseOver="rolloverOn('side-ext-32');"><IMG alt="Xalan-C 1.x" border="0" height="12" hspace="0" name="side-ext-32" onLoad="rolloverLoad('side-ext-32','graphics/ext-32-label-2.jpg','graphics/ext-32-label-3.jpg');" src="graphics/ext-32-label-3.jpg" vspace="0" width="120"></A><BR>
<IMG alt="close" border="0" height="14" hspace="0" src="resources/close.gif" vspace="0" width="120"><BR></TD><TD align="left" valign="top" width="500"><TABLE border="0" cellpadding="3" cellspacing="0"><TR><TD>
<UL>
<LI><A href="#quickstart">Quick Start</A></LI>
<LI><A href="#downloading">Downloading the code</A></LI>
<LI><A href="#how-to-build">Building the Tests</A></LI>
</UL>
<A name="quickstart"><!--anchor--></A>
<TABLE border="0" cellpadding="0" cellspacing="0" width="494"><TR><TD bgcolor="666699" colspan="2" width="494"><TABLE border="0" cellpadding="0" cellspacing="0" width="494"><TR><TD bgcolor="#039acc" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#039acc" height="1" width="492"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="492"></TD><TD bgcolor="#0086b2" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#039acc" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#0086b2" width="492"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG alt="" border="0" height="2" hspace="0" src="resources/void.gif" vspace="0" width="2"><B>Quick Start</B></FONT></TD><TD bgcolor="#017299" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#0086b2" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#017299" height="1" width="492"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="492"></TD><TD bgcolor="#017299" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></TD></TR><TR><TD width="10">&nbsp;</TD><TD width="484"><FONT color="#000000" face="arial,helvetica,sanserif">
<TABLE border="0" cellpadding="0" cellspacing="3" width="100%"><TR><TD valign="top" width="20"><IMG alt="Note" border="0" height="24" hspace="0" src="resources/note.gif" vspace="0" width="20"></TD><TD valign="top"><FONT color="#000000" face="arial,helvetica,sanserif" size="-1"><I>This section assumes you are already familiar with
<A href="http://xml.apache.org/xalan-j/readme.html#build">building Xalan-J</A> and with
<A href="http://jakarta.apache.org/ant/">Ant</A>.</I></FONT></TD></TR></TABLE>
<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><FONT face="courier, monospaced">cd /builds </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">checkout xml-xalan/java </FONT></CODE> Get the Xalan-J code (or simply get a nightly build or distro)
<BR><CODE><FONT face="courier, monospaced">cd xml-xalan/java </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">build jar </FONT></CODE> Build Xalan-J as usual
<BR><CODE><FONT face="courier, monospaced">build smoketest </FONT></CODE> Run the build Smoketest (optional; simply calls the smoketest target below)
</P>
<P><CODE><FONT face="courier, monospaced">cd /builds </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">checkout xml-xalan/test </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">cd xml-xalan/test </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">build jar </FONT></CODE> Build the test framework/harness and most API/conf/etc. tests into <CODE><FONT face="courier, monospaced">java/build/testxsl.jar </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">build smoketest </FONT></CODE> Run the build Smoketest (includes a selection of API tests and the conf tests); results in smoketest/
<BR><CODE><FONT face="courier, monospaced">build conf </FONT></CODE> Run the StylesheetTestletDriver over the conf dir; results in results-conf/
<BR><CODE><FONT face="courier, monospaced">build conf -Dqetest.optionName=valueName -Dqetest.category=axes </FONT></CODE> Run the StylesheetTestletDriver over the conf dir; passing options, and only on the axes subdirectory
<BR><CODE><FONT face="courier, monospaced">build api -DtestClass=TransformerAPITest </FONT></CODE> Run a single API test; results in results-api/
<BR><CODE><FONT face="courier, monospaced">build harness </FONT></CODE> Run the full set of individual API tests; results in results-api/
</P>
<P><CODE><FONT face="courier, monospaced">build extensions.classes </FONT></CODE> Compile the tests/extensions tests
<BR><CODE><FONT face="courier, monospaced">build extensions </FONT></CODE> Run the tests/extensions tests
<BR><CODE><FONT face="courier, monospaced">build bugzilla.classes </FONT></CODE> Compile the tests/bugzilla bug regression tests
<BR><CODE><FONT face="courier, monospaced">build bugzilla </FONT></CODE> Run the tests/bugzilla bug regression tests
<BR><CODE><FONT face="courier, monospaced">build clean </FONT></CODE> Clean up the built automation (does not clean any results you've generated)
<BR><CODE><FONT face="courier, monospaced">build -h </FONT></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, <A href="run.html#test-options">test options</A>
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><FONT face="courier, monospaced">qetest.</FONT></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><FONT face="courier, monospaced">my.test.properties</FONT></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><FONT face="courier, monospaced">-Dname=value</FONT></CODE> format.</LI>
</UL>
<P><CODE><FONT face="courier, monospaced">build conf -Dconf.category=axes -Dconf.flavor=trax.sax </FONT></CODE> This runs
the normal conf tests, but only on the axes subdir, and using the TraxSaxWrapper class.
<BR><CODE><FONT face="courier, monospaced">build api -DtestClass=TransformStateTest -Dapi.loggingLevel=30 </FONT></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>
</FONT></TD></TR></TABLE><BR>
<A name="downloading"><!--anchor--></A>
<TABLE border="0" cellpadding="0" cellspacing="0" width="494"><TR><TD bgcolor="666699" colspan="2" width="494"><TABLE border="0" cellpadding="0" cellspacing="0" width="494"><TR><TD bgcolor="#039acc" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#039acc" height="1" width="492"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="492"></TD><TD bgcolor="#0086b2" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#039acc" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#0086b2" width="492"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG alt="" border="0" height="2" hspace="0" src="resources/void.gif" vspace="0" width="2"><B>Downloading the tests</B></FONT></TD><TD bgcolor="#017299" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#0086b2" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#017299" height="1" width="492"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="492"></TD><TD bgcolor="#017299" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></TD></TR><TR><TD width="10">&nbsp;</TD><TD width="484"><FONT color="#000000" face="arial,helvetica,sanserif">
<TABLE border="0" cellpadding="0" cellspacing="3" width="100%"><TR><TD valign="top" width="20"><IMG alt="Note" border="0" height="24" hspace="0" src="resources/note.gif" vspace="0" width="20"></TD><TD valign="top"><FONT color="#000000" face="arial,helvetica,sanserif" size="-1"><I>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.</I></FONT></TD></TR></TABLE>
<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:
<A href="http://xml.apache.org/xalan-j/dist/">Xalan-J download page</A> or the
<A href="http://xml.apache.org/xalan-c/dist/">Xalan-C download page</A>
</P><P>To get the test sources, do the following:
<BR>Check out the xml-xalan\test repository <A href="http://xml.apache.org/cvs.html">directly from CVS</A>
(<A href="http://xml.apache.org/cvs.html">read-only access</A> is available to all).
<BR><BR>
</P>
</FONT></TD></TR></TABLE><BR>
<A name="how-to-build"><!--anchor--></A>
<TABLE border="0" cellpadding="0" cellspacing="0" width="494"><TR><TD bgcolor="666699" colspan="2" width="494"><TABLE border="0" cellpadding="0" cellspacing="0" width="494"><TR><TD bgcolor="#039acc" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#039acc" height="1" width="492"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="492"></TD><TD bgcolor="#0086b2" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#039acc" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#0086b2" width="492"><FONT color="#ffffff" face="arial,helvetica,sanserif" size="+1"><IMG alt="" border="0" height="2" hspace="0" src="resources/void.gif" vspace="0" width="2"><B>Building the Tests</B></FONT></TD><TD bgcolor="#017299" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR><TR><TD bgcolor="#0086b2" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD><TD bgcolor="#017299" height="1" width="492"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="492"></TD><TD bgcolor="#017299" height="1" width="1"><IMG alt="" border="0" height="1" hspace="0" src="resources/void.gif" vspace="0" width="1"></TD></TR></TABLE></TD></TR><TR><TD width="10">&nbsp;</TD><TD width="484"><FONT color="#000000" face="arial,helvetica,sanserif">
<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><FONT face="courier, monospaced">cd \builds\xml-xalan\test </FONT></CODE>
<BR><CODE><FONT face="courier, monospaced">build jar </FONT></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>
<TABLE border="0" cellpadding="0" cellspacing="3" width="100%"><TR><TD valign="top" width="20"><IMG alt="Note" border="0" height="24" hspace="0" src="resources/note.gif" vspace="0" width="20"></TD><TD valign="top"><FONT color="#000000" face="arial,helvetica,sanserif" size="-1"><I>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.</I></FONT></TD></TR></TABLE>
<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><FONT face="courier, monospaced">build.bat javadocs </FONT></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><FONT face="courier, monospaced">build.bat docs </FONT></CODE> and must be done under JDK 1.2.2 or higher,
since the Xalan-related stylebook code that we use requires that. </P>
</FONT></TD></TR></TABLE><BR>
</TD></TR></TABLE></TD></TR></TABLE><BR><TABLE border="0" cellpadding="0" cellspacing="0" width="620"><TR><TD bgcolor="#0086b2"><IMG alt="dot" height="1" src="resources/dot.gif" width="1"></TD></TR><TR><TD align="center"><FONT color="#0086b2" size="-1"><I>
Copyright &copy; 2000 The Apache Software Foundation.
All Rights Reserved.
</I></FONT></TD></TR></TABLE></BODY></HTML>