<!-- Fragment document type declaration subset:
Arbortext, Inc., 1988-2008, v.4002
<!DOCTYPE SOLBOOK PUBLIC "-//Sun Microsystems//DTD SolBook 3.1//EN" [
<!ENTITY % TCKentities SYSTEM "TCKentities.ent">
%TCKentities;
]>
-->
<?Pub UDT _bookmark _target>
<?Pub CX solbook(book(title()subtitle()bookinfo()chapter()>
<chapter id="GBFVV"><title>Setup and Configuration</title>
<highlights>
<para>This chapter describes how to set up the &TCKShortName; and JavaTest
harness software. Before proceeding with the instructions in this chapter,
be sure to install all required software, as described in <olink
targetptr="GBFTP">Chapter&nbsp;3, Installation</olink>.</para>
<para>After completing the instructions in this chapter, proceed to <olink
targetptr="GBFWO">Chapter&nbsp;5, Executing Tests</olink> for instructions
on running the &TCKShortName;.</para>
<para>This chapter includes the following topics:</para>
<itemizedlist remap="jumplist">
<listitem><para><olink targetptr="GBFVU">Configuring Your Environment to Run
the &TCKShortName; Against the Sun Reference Implementation</olink></para>
</listitem>
<listitem><para><olink targetptr="GCLHU">Configuring Your Environment to Repackage
and Run the &TCKShortName; Against the Vendor Implementation</olink></para>
</listitem>
<listitem><para><olink targetptr="GHGDG">Publishing the &TCKShortName; Test
Applications</olink></para></listitem>
<listitem><para><olink targetptr="GBFUY">Using the JavaTest Harness Software</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFWG">Using the JavaTest Harness Configuration
GUI</olink></para></listitem>
</itemizedlist>
</highlights>
<sect1 id="GBFVU"><title>Configuring Your Environment to Run the &TCKShortName; Against
the Sun Reference Implementation</title>
<para>After configuring your environment as described in this section, continue
with the instructions in <olink targetptr="GBFUY">Using the JavaTest Harness
Software</olink>.</para>
<note>
<itemizedlist>
<listitem><para>In these instructions, variables in angle brackets need to
be expanded for each platform. For example, <literal>&lt;TS_HOME></literal> becomes <literal>
$TS_HOME</literal> on Solaris/Linux and <literal>%TS_HOME%</literal> on Windows.
In addition, the forward slashes (<literal>/</literal>) used in all of the
examples need to be replaced with backslashes (<literal>\</literal>) for Windows.
Finally, be sure to use the appropriate separator for your operating system
when specifying multiple path entries (<literal>;</literal> on Windows, <literal>
:</literal> on UNIX/Linux).</para></listitem>
<listitem><para>On Windows, you must escape any backslashes with an extra
backslash in path separators used in any of the following properties, or use
forward slashes as a path separator instead.</para></listitem>
</itemizedlist>
</note>
<task id="GBFWN"><title>To Configure Your Environment to Run the &TCKShortName; Against
the Sun RI</title>
<procedure>
<step><para>Set the following environment variables in your shell environment:</para>
<substeps>
<step><para><literal>JAVA_HOME</literal> to the directory in which &J2SEversion; is
installed</para></step>
<step><para><literal>TS_HOME</literal> to the directory in which the &TCKShortName; &TechnologyVersion; software
is installed</para></step>
<step><para><literal>ANT_HOME</literal> should <emphasis>not</emphasis> be
set in your environment. If it is set, either unset it or make sure it is
set to <filename>&lt;TS_HOME>/tools/ant</filename>. The <command>&lt;TS_HOME>/bin/ant
</command> script automatically sets <literal>ANT_HOME</literal> if it is
unset in the environment.</para></step></substeps>
</step>
<step><para>Edit your <filename>&lt;TS_HOME>/bin/ts.jte</filename> file and
set the following environment variables:</para>
<substeps>
<step><para>Set the <literal>webServerHost</literal> property to the name
of the host on which &J2EEversion; RI is running.</para><para>The default
setting is <literal>localhost</literal>.</para></step>
<step><para>Set the <literal>webServerPort</literal> property to the port
number of the host on which &J2EEversion; RI  is running.</para><para>The
default setting is <literal>8080</literal>.</para></step>
<step><para>Set the <literal>web.home</literal> property to the installation
directory of &J2EEversion; RI .</para></step>
<step><para>Set the <literal>jaxrs.classes</literal> property to point to
the classes or JAR for the &JSR; API.</para><para>The default setting for
this property is <literal>${web.home}/modules/jsr311-api.jar</literal>.</para>
</step>
<step><para>Set the <literal>jaxrs_impl.classes</literal> and <literal>jaxrs_impl_lib
</literal> properties to point to the Jersey RI.</para><para>The default setting
for these properties is <literal>${web.home}/modules/jersey-gf-bundle.jar</literal> .
</para></step>
<step><para>Set the <literal>servlet_adaptor</literal> property to point to
the Servlet adaptor class for the JAX-RS implementation.</para><para>The default
setting for this property is <literal>com/sun/jersey/spi/container/servlet/ServletContainer.class
</literal>, the servlet adaptor supplied in Jersey.</para></step>
<step><para>Set the <literal>impl.vi</literal> property to the name of the &J2EEversion; RI
.</para><para>The relevant porting files are located under the <literal>$TS_HOME/bin/xml/impl/glassfish/
</literal> directory. </para><para>The default setting for this property is <literal>
glassfish</literal>.</para></step>
<step><para>Set the <literal>jaxrs_impl_name</literal> property to the name
of the JAX-RS RI.</para><para>A file bearing this name has been created under <literal>
$TS_HOME/bin/xml/impl/glassfish/jersey.xml</literal> with packaging instructions.
</para><para>The default setting for this property is <literal>jersey</literal>.</para>
</step>
<step><para>Set the <literal>impl.vi.deploy.dir</literal> property to point
to the <filename>autodeploy</filename> directory of the &J2EEversion; RI .</para>
<para>The default setting for this property is <literal>${web.home}/domains/domain1/autodpeloy
</literal>.</para></step>
<step><para>Set the <literal>servlet.classes</literal> property to point to
the class files for the Servlet APIs.</para><para> The default setting for
this property is <literal>${web.home}/modules/javax.servlet.jar</literal>.</para>
</step>
<step><para>Verify that the <literal>tools.jar</literal> property is set to
the location of the <filename>tools.jar</filename> file that is distributed
with &J2SEversion;.</para></step>
<step><para>Set the <literal>porting.ts.url.class.1</literal> property to
your porting implementation class that is used for obtaining URLs.</para></step>
</substeps>
</step>
<step><para>Provide your own implementations of the porting package interfaces
provided with the &TCKShortName;.</para><para>The porting interfaces are:</para>
<itemizedlist>
<listitem><para><literal>TSURLInterface.java</literal> &mdash; Obtains URL
strings for web resources in an implementation-specific manner</para></listitem>
</itemizedlist>
<para>API documentation for the <literal>TSURLInterface.java</literal> porting
package interface is available in the <filename>&lt;TS_HOME>/docs/api</filename> directory.
</para></step>
<step><para>If the &TCKShortName; test applications are published on a Servlet
3.0-compliant Web container to certify the VI, the <literal>servlet_adaptor</literal> property
needs to be set in the <filename>ts.jte</filename> file, and VI-specific WAR
files containing the Servlet information need to be created for publishing.</para>
<para>The VI-specific WAR files should never override any existing files that
come with the TCK.  Refer to <olink targetptr="GCLIZ">Appendix&nbsp;B, Packaging
the JAX-RS TCK Test Applications in Servlet&ndash;Compliant WAR Files With
VI-Specific Information</olink> for more information.</para></step>
<step><para>When creating VI-specific WAR files, deploying &TechnologyShortName; test
applications, or running the &TCKShortName;, it is recommended that you create
a porting file named <filename>$jaxrs_impl_name</filename> under <filename>$TS_HOME/bin/xml/${impl_vi}
</filename>.</para><para>Use the <filename>jersey.xml</filename> file as a
reference.</para></step>
</procedure>
</task>
</sect1>
<sect1 id="GCLHU"><title>Configuring Your Environment to Repackage and Run
the &TCKShortName; Against the Vendor Implementation</title>
<para>After configuring your environment as described in this section, continue
with the instructions in <olink targetptr="GBFUY">Using the JavaTest Harness
Software</olink>.</para>
<note>
<itemizedlist>
<listitem><para>In these instructions, variables in angle brackets need to
be expanded for each platform. For example, <literal>&lt;TS_HOME></literal> becomes <literal>
$TS_HOME</literal> on Solaris/Linux and <literal>%TS_HOME%</literal> on Windows.
In addition, the forward slashes (<literal>/</literal>) used in all of the
examples need to be replaced with backslashes (<literal>\</literal>) for Windows.
Finally, be sure to use the appropriate separator for your operating system
when specifying multiple path entries (<literal>;</literal> on Windows, <literal>
:</literal> on UNIX/Linux).</para></listitem>
<listitem><para>On Windows, you must escape any backslashes with an extra
backslash in path separators used in any of the following properties, or use
forward slashes as a path separator instead.</para></listitem>
</itemizedlist>
</note>
<task id="GCLIC"><title>To Configure Your Environment to Repackage and Run
the &TCKShortName; Against the Vendor Implementation</title>
<taskprerequisites>
<para>Decide against which JAX-RS implementation the tests will be run and
determine to which Servlet&ndash;compliant Web server the JAX-RS TCK applications
will be published.</para>
<para>Package the JAX-RS test applications for that JAX-RS implementation
and Servlet&ndash;compliant Web server.</para>
<para>See <olink targetptr="GCLIZ">Appendix&nbsp;B, Packaging the JAX-RS TCK
Test Applications in Servlet&ndash;Compliant WAR Files With VI-Specific Information
</olink> for information about repackaging the JAX-RS test application.</para>
</taskprerequisites>
<procedure>
<step><?Pub Caret1><para>Set the following environment variables in your shell
environment:</para>
<substeps>
<step><para><literal>JAVA_HOME</literal> to the directory in which &J2SEversion; is
installed</para></step>
<step><para><literal>TS_HOME</literal> to the directory in which the &TCKShortName; &TechnologyVersion; software
is installed</para></step>
<step><para><literal>ANT_HOME</literal> should <emphasis>not</emphasis> be
set in your environment. If it is set, either unset it or make sure it is
set to <filename>&lt;TS_HOME>/tools/ant</filename>. The <command>&lt;TS_HOME>/bin/ant
</command> script automatically sets <literal>ANT_HOME</literal> if it is
unset in the environment.</para></step></substeps>
</step>
<step><para>Edit your <filename>&lt;TS_HOME>/bin/ts.jte</filename> file and
set the following environment variables:</para>
<substeps>
<step><para>Set the <literal>webServerHost</literal> property to the name
of the host on which your Web server is running that is configured with the
Vendor Implementation.</para><para>The default setting is <literal>localhost</literal>.
</para></step>
<step><para>Set the <literal>webServerPort</literal> property to the port
number of the host on which the Web server is running that is configured with
the Vendor &TechnologyShortName; &TechnologyVersion; Vendor Implementation.</para>
<para>The default setting is <literal>8080</literal>.</para></step>
<step><para>Set the <literal>web.home</literal> property to the installation
directory of the Web server.</para></step>
<step><para>Set the <literal>jaxrs.classes</literal> property to point to
the classes or JAR for the &JSR; API.</para><para>The default setting for
this property is <literal>${web.home}/modules/jsr311-api.jar</literal>.</para>
</step>
<step><para>Set the <literal>jaxrs_impl.classes</literal> and <literal>jaxrs_impl_lib
</literal> properties to point to all classes/JARs for the &JSR; VI implementation
and all dependent libraries.</para><para>The default setting for these properties
is <literal>${web.home}/modules/jersey-gf-bundle.jar</literal> .</para></step>
<step><para>Set the <literal>servlet_adaptor</literal> property to point to
the Servlet adaptor class for the JAX-RS implementation.</para><para>The class
must be located in the JAR file defined by the <literal>jaxrs_impl_lib</literal> property.
The JAX-RS TCK test application is published on a Servlet-compliant Web container.
By default, this property is set to <literal>com/sun/jersey/spi/container/servlet/ServletContainer.class
</literal>, the servlet adaptor supplied in Jersey.</para></step>
<step><para>Set the <literal>impl.vi</literal> property to the name of the
Web server.</para><para>The relevant porting files are located under the <literal>
$TS_HOME/bin/xml/impl/${impl.vi}/</literal> directory. </para><para>The default
setting for this property is <literal>glassfish</literal>.</para></step>
<step><para>Set the <literal>jaxrs_impl_name</literal> property to the name
of the JAX-RS implementation to be tested.</para><para>The name of the property
must be unique. A file bearing this name will be created under <literal>$TS_HOME/bin/xml/impl/${impl.vi}/${jaxrs_impl_name}.xml
</literal> with packaging and/or deployment instructions.</para><para>The
default setting for this property is <literal>jersey</literal>.</para></step>
<step><para>Set the <literal>impl.vi.deploy.dir</literal> property to point
to the <filename>autodeploy</filename> directory for the Web server.</para>
<para>The default setting for this property is <literal>${web.home}/domains/domain1/autodpeloy
</literal>.</para></step>
<step><para>Set the <literal>servlet.classes</literal> property to point to
the class files for the Servlet APIs.</para><para> The default setting for
this property is <literal>${web.home}/modules/javax.servlet.jar</literal>.</para>
</step>
<step><para>Verify that the <literal>tools.jar</literal> property is set to
the location of the <filename>tools.jar</filename> file that is distributed
with &J2SEversion;.</para></step>
<step><para>Set the <literal>porting.ts.url.class.1</literal> property to
your porting implementation class that is used for obtaining URLs.</para></step>
</substeps>
</step>
<step><para>Provide your own implementations of the porting package interfaces
provided with the &TCKShortName;.</para><para>The porting interfaces are:</para>
<itemizedlist>
<listitem><para><literal>TSURLInterface.java</literal> &mdash; Obtains URL
strings for web resources in an implementation-specific manner</para></listitem>
</itemizedlist>
<para>API documentation for the <literal>TSURLInterface.java</literal> porting
package interface is available in the <filename>&lt;TS_HOME>/docs/api</filename> directory.
</para></step>
<step><para>If the &TCKShortName; test applications are published on a Servlet
3.0-compliant Web container to certify the VI, the <literal>servlet_adaptor</literal> property
needs to be set in the <filename>ts.jte</filename> file, and VI-specific WAR
files containing the Servlet information need to be created for publishing.</para>
<para>The VI-specific WAR files should never override any existing files that
come with the TCK.  Refer to <olink targetptr="GCLIZ">Appendix&nbsp;B, Packaging
the JAX-RS TCK Test Applications in Servlet&ndash;Compliant WAR Files With
VI-Specific Information</olink> for more information.</para></step>
<step><para>When creating VI-specific WAR files, deploying &TechnologyShortName; test
applications, or running the &TCKShortName;, it is recommended that you create
a porting file named <filename>$jaxrs_impl_name</filename> under <filename>$TS_HOME/bin/xml/${impl_vi}
</filename>.</para><para>Use the <filename>jersey.xml</filename> file as a
reference.</para></step>
</procedure>
</task>
</sect1>
<sect1 id="GHGDG"><title>Publishing the &TCKShortName; Test Applications</title>
<para>The &TCKShortName; provides an automatic way of deploying both the prebuilt
and Vendor-built archives to the configured web container(s) via deployment
handlers.</para>
<para>The handler file (<filename>&lt;TS_HOME>/bin/xml/impl/glassfish/jersey.xml</filename> is
written to be used with Jersey and &J2EEversion; RI . If the Vendor chooses
not to use &J2EEversion; RI  to run with their implementation but still chooses
to publish to a Servlet-compliant Web container, then a VI-specific &TCKShortName; tests
Web archive needs to be created. This archive contains the VI-specific servlet
class, and the Vendor should create their own version handler file to provide
this functionality. It is recommended that the handler file be named <filename>${jaxrs_impl_name}
</filename> and be located in <filename>$TS_HOME/bin/xml/${impl.vi}/${jaxrs_impl_name}
</filename>. Refer to <olink targetptr="GCLIZ">Appendix&nbsp;B, Packaging
the JAX-RS TCK Test Applications in Servlet-Compliant WAR Files With VI-Specific
Information</olink> for more information.</para>
<para>This section describes the various commands used for deploying the classes
or WAR files to the configured web container.</para>
<itemizedlist remap="jumplist">
<listitem><para><olink targetptr="GCLJG">Generic Deployment Command Scenarios</olink></para>
</listitem>
<listitem><para><olink targetptr="GCLIW">Deploying the &TCKShortName; Prebuilt
Archives</olink></para></listitem>
<listitem><para><olink targetptr="GCLIL">Deploying the &TCKShortName; Test
Applications Against the Vendor Implementation</olink></para></listitem>
</itemizedlist>
<sect2 id="GCLJG"><title>Generic Deployment Command Scenarios</title>
<para>You can deploy all &TechnologyShortName; WAR files to &J2EEversion; RI
 or the Web server chosen by a Vendor, deploy just a single test directory,
or deploy of subset of test directories.</para>
<task id="GCLJK"><title>To Deploy all the WAR Files From the <filename>&lt;TS_HOME>/dist
</filename> to a Web Server</title>
<procedure role="single-step">
<step><para>Enter the following command:</para>
<screen>&lt;TS_HOME>/bin/ant deploy.all</screen>
</step>
</procedure>
</task>
<task id="GCLII"><title>To Deploy a Single Test Directory</title>
<procedure role="single-step">
<step><para>Enter the following commands:</para>
<screen>cd &lt;TS_HOME>/src/com/sun/ts/tests/jaxrs/api/rs/getTest
&lt;TS_HOME>/bin/ant deploy</screen>
</step>
</procedure>
</task>
<task id="GCLJC"><title>To Deploy a Subset of Test Directories</title>
<procedure role="single-step">
<step><para>Enter the following commands:</para>
<screen>cd &lt;TS_HOME>/src/com/sun/ts/tests/jaxrs/api 
&lt;TS_HOME>/bin/ant deploy</screen>
</step>
</procedure>
</task>
</sect2>
<sect2 id="GCLIW"><title>Deploying the &TCKShortName; Prebuilt Archives</title>
<para>This section explains issues regarding the deployment of the &TCKShortName; prebuilt
archives. Before conducting any deployment, ensure that your environment has
been configured by following the instructions in either <olink targetptr="GBFVU">
Configuring Your Environment to Run the JAX-RS TCK Against the Sun Reference
Implementation</olink> or <olink targetptr="GCLHU">Configuring Your Environment
to Repackage and Run the JAX-RS TCK Against the Vendor Implementation</olink>.</para>
<para>The <filename>&lt;TS_HOME>/dist</filename> directory contains all WAR
files for the &TCKShortName; tests that have been compiled  and packaged using
the Sun Reference Implementation for deployment on a Servlet-compliant Web
container, &J2EEversion; RI , using the standard Web Archive (WAR) format. </para>
<para>These WAR files contain only Jersey, a &J2EEversion; RI -specfic servlet
adaptor, and are tailored to run against the Sun Reference Implementation.
These WAR files allow you to deploy (without any additional setup or modification)
against the Sun Reference Implementation to test the various features and
functionality of this implementation. </para>
<para>To deploy the &TCKShortName; tests, use either the <literal>deploy</literal> or <command>
deploy.all</command> batch command as described in <olink targetptr="GCLJG">Generic
Deployment Command Scenarios</olink>.</para></sect2>
<sect2 id="GCLIL"><title>Deploying the &TCKShortName; Test Applications Against
the Vendor Implementation</title>
<para>This section describes how to deploy the &TCKShortName; test applications
against the Vendor Implementation and vendor's choice of Web server. Before
conducting the deployment, ensure that you have followed the instructions
in <olink targetptr="GCLHU">Configuring Your Environment to Repackage and
Run the JAX-RS TCK Against the Vendor Implementation</olink>. Vendors can
deploy &TCKShortName; tests in either Java class or WAR format. All test resource
classes are located under <filename>$TS_HOME/classes</filename>. All test
resources packaged in WAR files are located under <filename>$TS_HOME/dist</filename>.
</para>
<para>If a vendor chooses to deploy WAR files on a Servlet&ndash;compliant
Web container other than &J2EEversion; RI , it is necessary to build test
WAR files that contain the VI's servlet class and servlet class property in
the <literal>web.xml</literal> deployment descriptor, as specified in the &TechnologyShortName; specification.
The &TCKShortName; comes with a <filename>web.xml.template</filename> file
for each test, which contains all information except the servlet class. The &TCKShortName; also
comes with a tool to replace the RI or VI's servlet adaptor class name in
the <filename>web.xml.template</filename>. Refer to <olink targetptr="GCLIZ">Appendix&nbsp;B,
Packaging the JAX-RS TCK Test Applications in Servlet-Compliant WAR Files
With VI-Specific Information</olink> for more information about repackaging
the JAX-RS TCK tests.</para>
<para>To deploy a resource class in class file format, a vendor must create
a handler file that supports deploy options  as described in  <olink
targetptr="GCLJG">Generic Deployment Command Scenarios</olink>.  All tests
with resource classes have a <literal>${resource.classes}</literal> property
set in each test's individual <filename>build.xml</filename> file; this value
contains all resource classes in the test.</para>
<para>To deploy the tests, the vendor should perform a deployment using either
the <command>deploy</command> or <command>deploy.all</command> batch command,
as described in <olink targetptr="GCLJG">Generic Deployment Command Scenarios</olink>.
</para></sect2>
</sect1>
<sect1 id="GBFUY"><title>Using the JavaTest Harness Software</title>
<para>There are two general ways to run the &TCKShortName; test suite using
the JavaTest harness software:</para>
<itemizedlist>
<listitem><para>Through the JavaTest GUI; if using this method, please continue
on to <olink targetptr="GBFWG">Using the JavaTest Harness Configuration GUI</olink>.
</para></listitem>
<listitem><para>In JavaTest batch mode, from the command line in your shell
environment; if using this method, please proceed directly to <olink
targetptr="GBFWO">Chapter&nbsp;5, Executing Tests</olink>.</para></listitem>
</itemizedlist>
</sect1>
<sect1 id="GBFWG"><title>Using the JavaTest Harness Configuration GUI</title>
<para>You can use the JavaTest harness GUI to modify general test settings
and to quickly get started with the default &TCKShortName; test environment.
This section covers the following topics:</para>
<itemizedlist>
<listitem><para><olink targetptr="GBFVA">Configuration GUI Overview</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFVD">Starting the Configuration GUI</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFVX">The Configuration Interview</olink></para>
</listitem>
<listitem><para><olink targetptr="GBFUU">Modifying the Default Test Configuration
</olink></para></listitem>
</itemizedlist>
<note><para>It is only necessary to proceed with this section if you want
to run the JavaTest harness in GUI mode. If you plan to run the JavaTest harness
in command-line mode, skip the remainder of this chapter, and continue with <olink
targetptr="GBFWO">Chapter&nbsp;5, Executing Tests</olink>.</para></note>
<sect2 id="GBFVA"><title>Configuration GUI Overview</title>
<para>In order for the JavaTest harness to execute the test suite, it requires
information about how your computing environment is configured. The JavaTest
harness requires two types of configuration information:</para>
<itemizedlist>
<listitem><para><emphasis role="strong">Test environment</emphasis> &mdash;
This is data used by the tests. For example, the path to the Java runtime,
how to start the product being tested, network resources, and other information
required by the tests in order to run. This information does not change frequently
and usually stays constant from test run to test run.</para></listitem>
<listitem><para><emphasis role="strong">Test parameters</emphasis> &mdash;
This is information used by the JavaTest harness to run the tests. Test parameters
are values used by the JavaTest harness that determine which tests in the
test suite are run, how the tests should be run, and where the test reports
are stored. This information often changes from test run to test run.</para>
</listitem>
</itemizedlist>
<para>The first time you run the JavaTest harness software, you are asked
to specify the test suite and work directory that you want to use. (These
parameters can be changed later from within the JavaTest harness GUI.)</para>
<para>Once the JavaTest harness GUI is displayed, whenever you choose <emphasis>Run
Tests->Start</emphasis> to begin a test run, the JavaTest harness determines
whether all of the required configuration information has been supplied:</para>
<itemizedlist>
<listitem><para>If the test environment and parameters have been completely
configured, the test run starts immediately.</para></listitem>
<listitem><para>If any required configuration information is missing, the
configuration editor displays a series of questions asking you the necessary
information. This is called the configuration interview . When you have entered
the configuration data, you are asked if you wish to proceed with running
the test.</para></listitem>
</itemizedlist>
</sect2>
<sect2 id="GBFVD"><title>Starting the Configuration GUI</title>
<para>Before you start the JavaTest harness software, you must have a valid
test suite and &J2SEversion; installed on your system.</para>
<para>The &TCKShortName; includes an Ant script that is used to execute the
JavaTest harness from the <literal>&lt;TS_HOME></literal> directory. Using
this Ant script to start the JavaTest harness is part of the procedure described
in <olink targetptr="GBFVX">The Configuration Interview</olink>.</para>
<para>When you execute the JavaTest harness software for the first time, the
JavaTest harness displays a Welcome dialog box that guides you through the
initial startup configuration.</para>
<itemizedlist>
<listitem><para>If it is able to open a test suite, the JavaTest harness displays
a Welcome to JavaTest dialog box that guides you through the process of either
opening an existing work directory or creating a new work directory as described
in the JavaTest online help.</para></listitem>
<listitem><para>If the JavaTest harness is unable to open a test suite, it
displays a Welcome to JavaTest dialog box that guides you through the process
of opening both a test suite and a work directory as described in the JavaTest
documentation.</para></listitem>
</itemizedlist>
<para>After you specify a work directory, you can use the Test Manager to
configure and run tests as described in <olink targetptr="GBFVX">The Configuration
Interview</olink>.</para></sect2>
<sect2 id="GBFVX"><title>The Configuration Interview</title>
<para>The answers you give to some of the configuration interview questions
are specific to your site. For example, the name of the host on which the
JavaTest harness is running. Other configuration parameters can be set however
you wish. For example, where you want test report files to be stored.</para>
<task id="GBFUW"><title>To Configure the JavaTest Harness to Run the &TCKShortName; Tests
</title>
<tasksummary>
<para>Note that you only need to complete all these steps the first time you
start the JavaTest test harness. After you complete these steps, you can either
run all of the tests by completing the steps in <olink targetptr="GBFUZ">Starting
JavaTest</olink> or run a subset of the tests by completing the steps in <olink
targetptr="GBFWM">Running a Subset of the Tests</olink>.</para></tasksummary>
<procedure>
<step><para>Change to the <filename>&lt;TS_HOME>/bin</filename> directory
and start the JavaTest test harness:</para>
<literallayout><command>cd &lt;TS_HOME>/bin</command>
<command>&lt;TS_HOME>/bin/ant gui</command></literallayout><para>If the Welcome
Screen does not appear do the following, otherwise skip to next step.</para>
</step>
<step><para>Click <emphasis>File->Open Quick Start Wizard</emphasis>.</para>
<para>The Welcome screen displays.</para></step>
<step><para>Click <emphasis>Start a new test run</emphasis>, and then click <emphasis>
Next</emphasis>.</para><para>You are prompted to Create a new configuration
or use a configuration template.</para></step>
<step><para>Select <emphasis>Create a new configuration</emphasis>, and then
click <emphasis>Next</emphasis>.</para><para>You are prompted to select a
test suite.</para></step>
<step><para>Accept the default suite (<filename>&lt;TS_HOME>/src</filename>),
and then click <emphasis>Next</emphasis>.</para><para>You are prompted to
specify a work directory to use to store your test results.</para></step>
<step><para>Type a work directory name or use the <emphasis>Browse</emphasis> button
to select a work directory, and then click <emphasis>Next</emphasis>.</para>
<para>You are prompted to start the configuration editor or start a test run.
At this point, the &TCKShortName; is configured to run the default test suite.</para>
</step>
<step><para>Uncheck the <emphasis>Start the configuration editor</emphasis> option,
and then click <emphasis>Finish</emphasis>.</para></step>
<step><para>Click Run Tests->Start.</para><para>The JavaTest harness starts
running the tests.</para></step>
<step><para>To Reconfigure the JavaTest test harness, click <emphasis>Configuration->New
Configuration</emphasis> or <emphasis>Configuration->Change Configuration</emphasis>.
</para></step>
<step><para>Click <emphasis>Report->Create Report</emphasis>.</para></step>
<step><para>Specify the directory in which the JavaTest test harness will
write the report, and then click <emphasis>OK</emphasis>.</para><para>A report
is created, and you are asked whether you want to view it.</para></step>
<step><para>Click <emphasis>Yes</emphasis> to view the report.</para></step>
</procedure>
</task>
</sect2>
<sect2 id="GBFUU"><title>Modifying the Default Test Configuration</title>
<para>The JavaTest GUI enables you to configure numerous test options. These
options are divided into two general dialog box groups:</para>
<itemizedlist>
<listitem><para><emphasis role="strong">Group 1</emphasis> &mdash; Available
from the JavaTest <emphasis>Configure->Change Configuration</emphasis> submenus,
the following options are displayed in a tabbed dialog box:</para>
<itemizedlist>
<listitem><para><emphasis>Tests to Run</emphasis></para></listitem>
<listitem><para><emphasis>Exclude List</emphasis></para></listitem>
<listitem><para><emphasis>Keywords</emphasis></para></listitem>
<listitem><para><emphasis>Prior Status</emphasis></para></listitem>
<listitem><para><emphasis>Test Environment</emphasis></para></listitem>
<listitem><para><emphasis>Concurrency</emphasis></para></listitem>
<listitem><para><emphasis>Timeout Factor</emphasis></para></listitem>
</itemizedlist>
</listitem>
<listitem><para><emphasis role="strong">Group 2</emphasis> &mdash; Available
from the JavaTest <emphasis>Configure->Change Configuration->Other Values</emphasis> submenu,
or by pressing <keycap>Ctrl+E</keycap>, the following options are displayed
in a paged dialog box:</para>
<itemizedlist>
<listitem><para><emphasis>Environment Files</emphasis></para></listitem>
<listitem><para><emphasis>Test Environment</emphasis></para></listitem>
<listitem><para><emphasis>Specify Tests to Run</emphasis></para></listitem>
<listitem><para><emphasis>Specify an Exclude List</emphasis></para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
<para>Note that there is some overlap between the functions in these two dialog
boxes; for those functions use the dialog that is most convenient for you.
Please refer to the JavaTest Harness documentation or the online help for
complete information about these various options.</para></sect2>
</sect1>
</chapter>
<?Pub *0000032819 0>
