Author: dan.j.allen
Date: 2009-07-15 00:20:28 -0400 (Wed, 15 Jul 2009)
New Revision: 3052
Added:
tck/trunk/doc/reference/en-US/eclipse-debugging.xml
tck/trunk/doc/reference/en-US/eclipse-running.xml
tck/trunk/doc/reference/en-US/images/
tck/trunk/doc/reference/en-US/images/in-container-execution.png
Modified:
tck/trunk/doc/reference/en-US/Book_Preface.xml
tck/trunk/doc/reference/en-US/configuration.xml
tck/trunk/doc/reference/en-US/executing.xml
tck/trunk/doc/reference/en-US/installation.xml
tck/trunk/doc/reference/en-US/introduction.xml
tck/trunk/doc/reference/en-US/part1-background.xml
tck/trunk/doc/reference/en-US/part2-setup.xml
tck/trunk/doc/reference/en-US/part3-execution.xml
Log:
rough draft
Modified: tck/trunk/doc/reference/en-US/Book_Preface.xml
===================================================================
--- tck/trunk/doc/reference/en-US/Book_Preface.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/Book_Preface.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -2,31 +2,43 @@
<!-- This document was created with Syntext Serna Free. --><!DOCTYPE preface
PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<preface id="book-preface">
<title>Preface</title>
- <para>This guide describes how to install, configure, and run the Technology
Compatibility Kit (TCK) that is used to verify the compatibility of a licensee's
implementation of the JSR-299: Context and Dependency Injection for Java EE
specification.</para>
- <para>The JSR-299 TCK is built atop the JBoss Test Harness, a portable and
configurable automated test suite for authoring unit and integration tests against Java EE
artifacts. The JSR-299 TCK 1.0 uses the JBoss Test Harness version 1.0.0 to execute the
test suite.</para>
+ <para>This guide describes how to download, install, configure, and run the
Technology Compatibility Kit (TCK) used to verify the compatibility of a
licensee's implementation of the JSR-299: Context and Dependency Injection for
Java EE specification.</para>
+ <para>The JSR-299 TCK is built atop the JBoss Test Harness, a portable and
configurable automated test suite for authoring unit and integration tests in a Java EE
environment. The JSR-299 TCK 1.0.0 uses the JBoss Test Harness version 1.0.0.BETA3 to
execute the test suite.</para>
<section id="target-audience">
<title>Who Should Use This Book</title>
<para>This guide is for licensees of the Context and Dependency Injection for
Java EE 1.0 (JSR-299) technology to assist in running the test suite that verifies the
compatibility of their implementation.</para>
</section>
<section id="before-reading">
<title>Before You Read This Book</title>
- <para>Before reading this guide, you should familiarize yourself with the Java
EE programming model, specifically the Enterprise JavaBeans (EJB) 3.0 and the Contexts and
Dependency Injection (CDI) for Java EE 1.0 specifications. A good resource for the Java EE
programming model is the <ulink url="http://jcp.org">JCP</ulink> web
site.</para>
+ <para>Before reading this guide, you should familiarize yourself with the Java
EE programming model, specifically the Enterprise JavaBeans (EJB) 3.0 and the Contexts and
Dependency Injection for Java EE 1.0 specifications. A good resource for the Java EE
programming model is the <ulink url="http://jcp.org">JCP</ulink> web
site.</para>
<para>The JSR-299 TCK is based on the Context and Dependency Injection for Java
EE technology specification 1.0 (JSR-299). Information about the specification, including
links to the specification documents, can be found on the <ulink
url="http://jcp.org/en/jsr/detail?id=299">JSR-299 JCP
page</ulink>.</para>
- <para>Before running the tests in the JSR-299 TCK, read and become familiar
with the JBoss Test Harness Reference Guide, which describes how the test harness
functions.</para>
+ <para>Before running the tests in the JSR-299 TCK, read and become familiar
with the JBoss Test Harness Reference Guide (pending), which describes how the test
harness functions.</para>
</section>
<section id="book-organization">
<title>How This Book Is Organized</title>
<para>If you are running the JSR-299 TCK for the first time, read Chapter 1 and
Chapter 2 completely for the necessary background information about the TCK and its
purpose. Once you have reviewed that material, perform the steps outlined in the remaining
chapters.</para>
<itemizedlist>
<listitem>
- <para>Chapter 1 gives an overview of the principles that apply generally to
all Technology Compatibility Kits (TCKs) and describes the JSR-299 TCK. This chapter also
includes a broad listing of the steps for starting and running the JSR-299
TCK.</para>
+ <para>Chapter 1 gives an overview of the principles that apply generally to
all Technology Compatibility Kits (TCKs) and describes the JSR-299 TCK architecture and
components. It also includes a broad overview of how the TCK is executed and lists the
platforms on which the TCK has been tested and verified.</para>
</listitem>
<listitem>
- <para>Chapter 2 describes the conformance testing procedure and testing
requirements.</para>
+ <para>Chapter 2 explains where to obtain the required software and how to
install it. It covers both the primary TCK components as well as tools useful for
troubleshooting tests.</para>
</listitem>
<listitem>
- <para>Chapter 3 explains...</para>
+ <para>Chapter 3 details the configuration of the JBoss Test Harness, how to
create a TCK runner for the TCK test suite and the mechanics of how an in-container test
is conducted.</para>
</listitem>
+ <listitem>
+ <para>Chapter 4 documents how the TCK test suite is executed. It covers
both modes supported by the TCK, standalone and in-container, and shows how to dump the
generated test artifacts to disk.</para>
+ </listitem>
+ <listitem>
+ <para>Chapter 5 shows how to run individual tests in Eclipse and advices
the best way to setup your Eclipse workspace for running the tests.</para>
+ </listitem>
+ <listitem>
+ <para>Chapter 6 builds on chapter 5 by detailing how to debug individual
tests in Eclipse.</para>
+ </listitem>
+ <listitem>
+ <para>Chapter 7 (pending) explains the test reports that are generated by
the TCK test suite and introduces the TCK audit report as a tool for measure a
licensee's progress in passing the TCK.</para>
+ </listitem>
</itemizedlist>
</section>
</preface>
Modified: tck/trunk/doc/reference/en-US/configuration.xml
===================================================================
--- tck/trunk/doc/reference/en-US/configuration.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/configuration.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,14 +1,14 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<chapter id="configuration">
<title>Configuration</title>
- <para>This chapter examples...</para>
+ <para>This chapter lays out how to configure the JBoss Test Harness by specifying
the SPI implementation classes, defining the target container connection information, and
various other switches. You then learn how to setup a TCK runner project that executes
the the TCK test suite, putting these settings into practice. Finally, a detailed account
of how the JBoss Test Harness negotiates the execution of the tests in the container is
given.</para>
<section>
<title>JBoss Test Harness Properties</title>
<para>The JBoss Test Harness allows the test suite to be launched in a
pluggable fashion. In order to execute the TCK, the JBoss Test Harness must be configured
by specifying implementations of the test launcher and container APIs. All the required
configuration that pertains to the JBoss Test Harness is applicable to the TCK as
well.</para>
- <para>System properties and/or the resource
META-INF/jboss-test-harness.properties, a Java properties file, are used to configure the
JBoss Test Harness. The bootstrap configuration builder looks to the property
<literal>org.jboss.testharness.api.ConfigurationBuilder</literal>, the first
property listed in table X.X, for the fully qualified class name of a concreate
configuration builder implementation. This implementation loads the remaining
configuration settings and produces a JBoss Test Harness configuration.</para>
- <para>For you convenience, a default configuration builder implementation is
provided,
<literal>org.jboss.testharness.impl.PropertiesBasedConfigurationBuilder</literal>,
which retrieves all the JBoss Test Harness configuration settings from Java properties. It
does so by aggregating the system properties and the properties defined in the
META-INF/jboss-test-harness.properties resource in any classpath entry under a single
properties map, allowing you to segment the configuration settings as
needed.</para>
- <para>A complete list of configuration properties for the JBoss Test Harness is
itemized in table X.X, along with the default value (if any) and a description for each
property.</para>
+ <para>System properties and/or the resource
META-INF/jboss-test-harness.properties, a Java properties file, are used to configure the
JBoss Test Harness. The bootstrap configuration builder looks to the property
<literal>org.jboss.testharness.api.ConfigurationBuilder</literal>, the first
property listed in table 2.1.1, for the fully qualified class name (FQCN) of a concreate
configuration builder implementation to get started. This implementation loads the
remaining configuration settings and produces a JBoss Test Harness
configuration.</para>
+ <para>For you convenience, the default configuration builder implementation
<literal>org.jboss.testharness.impl.PropertiesBasedConfigurationBuilder</literal>
is provided, which collects all the JBoss Test Harness configuration settings from Java
properties. It does so by aggregating the system properties with the properties defined in
the META-INF/jboss-test-harness.properties resource in any classpath entry under a single
properties map, allowing you to partition the configuration settings as
needed.</para>
+ <para>A complete list of configuration properties for the JBoss Test Harness
has been itemized in table 2.1.1, accompanied by the default value (if any) and a
description for each property.</para>
<table frame="all">
<title/>
<tgroup cols="2">
@@ -123,7 +123,7 @@
</tbody>
</tgroup>
</table>
- <para>The general TCK porting package is also configured using the Java
properties file META-INF/jboss-test-harness.properties or system properties. Each
implementation of the Porting Package SPI should be specified using the fully-qualified
domain name (FQDN) of the interface as the property value. The properties which must be
satisified are listed in table X.XX.</para>
+ <para>The TCK also relies on implementations of the interfaces in the porting
package. These implementations are also specified using system properties or the classpath
resource META-INF/jboss-test-harness.properties. The implementation of each porting
package SPI must be specified using the fully-qualified domain name (FQDN) of the
interface mapped to a Java property. The properties that correspond to the interface which
must be implemented are listed in table 2.1.2.</para>
<table frame="all">
<title/>
<tgroup cols="2">
@@ -164,4 +164,143 @@
</tgroup>
</table>
</section>
+ <section>
+ <title>Setting up the TCK runner project</title>
+ <para>The TCK runner project is the magic that makes everything come together
and allows you to execute the TCK against a JSR-299 implementation. If you fully
understand how the JBoss Test Harness functions, and have a good grasp on Maven 2, then
it's not to difficult to understand how the TCK runner project works. Regardless
of your background, this guide covers what you need to know to get up and running by
studying the TCK runner that tests the JSR-299 RI.</para>
+ <para>The TCK runner for the JSR-299 RI can be found in the jboss-tck-runner
directory in the Web Beans distribution. The dependencies of the TCK runner project for
the JSR-299 RI are listed in table 2.2.3.</para>
+ <table frame="all">
+ <title/>
+ <tgroup cols="3">
+ <colspec colname="c1"/>
+ <colspec colname="c2"/>
+ <colspec colname="c3"/>
+ <thead>
+ <row>
+ <entry>Group ID</entry>
+ <entry>Artifact ID</entry>
+ <entry>Version</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>org.jboss.webbeans</entry>
+ <entry>jsr299-api</entry>
+ <entry>1.0.0-SNAPSHOT</entry>
+ </row>
+ <row>
+ <entry>org.jboss.jsr299.tck</entry>
+ <entry>jsr299-tck-api</entry>
+ <entry>1.0.0-SNAPSHOT</entry>
+ </row>
+ <row>
+ <entry>org.jboss.jsr299.tck</entry>
+ <entry>jsr299-tck-impl</entry>
+ <entry>1.0.0-SNAPSHOT</entry>
+ </row>
+ <row>
+ <entry>org.jboss.webbeans</entry>
+ <entry>webbeans-core</entry>
+ <entry>1.0.0-SNAPSHOT</entry>
+ </row>
+ <row>
+ <entry>org.jboss.webbeans</entry>
+ <entry>webbeans-porting-package</entry>
+ <entry>1.0.0-SNAPSHOT</entry>
+ </row>
+ <row>
+ <entry>org.testng</entry>
+ <entry>testng (classifier: jdk15)</entry>
+ <entry>5.8</entry>
+ </row>
+ <row>
+ <entry>org.jboss.test-harness</entry>
+ <entry>jboss-test-harness-jboss-as-51</entry>
+ <entry>1.0.0.BETA3</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>You can install these dependencies manually into your local Maven
respository using the following command template:</para>
+ <programlisting>mvn install:install-file \
+-Dfile=jsr299-tck-api.jar \
+-DgroupId=org.jboss.jsr299.tck \
+-DartifactId=jsr29-tck-api \
+-Dversion=1.0.0-SNAPSHOT \
+-Dpackaging=jar</programlisting>
+ <para>You should substituate the webbeans-core and webbeans-porting-package
artifacts from table 2.2.3 if you are running the TCK against your JSR-299 implementation.
You'll also need to replace the jboss-test-harness-jboss-as-51 artifact if you
are not testing your implementation on JBoss AS 5.1. The jboss-test-harness-jboss-as-51
artifact contains implementations of the <literal>Containers</literal> SPI for
the JBoss Test Harness.</para>
+ <note>
+ <para>When running the TCK in the in-container mode, the tests will run
against the JSR-299 implementation installed in the container. The version of the
implementation declared as a Maven dependency is only used when running the TCK in
standalone mode.</para>
+ </note>
+ <para>The TestNG test suite for the TCK is also retrieved from the local Maven
repository (groupId=org.jboss.jsr299.tck, artifactId=jsr299-tck-impl, classifier=suite,
type=xml, version=1.0.0-SNAPSHOT), but it's not declared as a regular Maven
dependency. That's because the test suite must be available to both the client
JVM and the container JVM. The maven-dependency-plugin is used to copy it to the
target/dependencies/lib directory. Any JARs in this folder are added to any test artifact
that is generated. The Maven plugin execution is defined in the TCK runner project as
follows:</para>
+ <programlisting><plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>copy</id>
+ <phase>process-resources</phase>
+ <goals>
+ <goal>copy</goal>
+ </goals>
+ <configuration>
+ <stripVersion>true</stripVersion>
+ <artifactItems>
+ <artifactItem>
+ <groupId>org.jboss.jsr299.tck</groupId>
+ <artifactId>jsr299-tck-impl</artifactId>
+ <type>xml</type>
+ <classifier>suite</classifier>
+ <overWrite>true</overWrite>
+ </artifactItem>
+ <artifactItem>
+ <groupId>org.jboss.webbeans</groupId>
+ <artifactId>
+ webbeans-porting-package
+ </artifactId>
+ <overWrite>true</overWrite>
+ <outputDirectory>
+ ${project.build.directory}/dependency/lib
+ </outputDirectory>
+ </artifactItem>
+ <artifactItem>
+ <groupId>org.jboss.webbeans</groupId>
+ <artifactId>webbeans-core-test</artifactId>
+ <overWrite>true</overWrite>
+ <outputDirectory>
+ ${project.build.directory}/dependency/lib
+ </outputDirectory>
+ </artifactItem>
+ <artifactItem>
+ <groupId>javax.el</groupId>
+ <artifactId>el-ri</artifactId>
+ <overWrite>true</overWrite>
+ <outputDirectory>
+ ${project.build.directory}/dependency/lib
+ </outputDirectory>
+ </artifactItem>
+ </artifactItems>
+ </configuration>
+ </execution>
+ </executions>
+</plugin></programlisting>
+ <para>The target folder is declared as the JBoss Test Harness library directory
so that the JARs are added to the test artifact using the following property
assignment:</para>
+
<programlisting>org.jboss.testharness.libraryDirectory=target/dependency/lib</programlisting>
+ <para>The TCK is executed using the Maven TestNG plugin. Maven 2 profiles are
used to control the properties that are set at the time of the execution. For instance,
the <literal>incontainer</literal> profile enables integration tests and
disables standalone mode, changing the default settings.</para>
+ <para>The jboss-tck-runner project also defines the JBoss Test Harness extra
configuration directory using the following property:</para>
+
<programlisting>org.jboss.testharness.container.extraConfigurationDir=../jboss-as</programlisting>
+ <para>The JBoss Test Harness looks in this directory for either a
build.properties or local.build.properties file that declare additional configuration
properties. In particular, the JBoss AS Containers implementation looks here to find the
<literal>jboss.home</literal> property for starting and stopping JBoss
AS.</para>
+ </section>
+ <section>
+ <title>Negotiating the execution of an in-container test</title>
+ <para>The basic procedure of an in-container test is as follows. The JBoss Test
Harness produces a deployable artifact from an <literal>@Artifact</literal>
test class and any declared dependent classes, descriptors or other resources. Then it
deploys the artifact to the container using the <literal>Containers</literal>
SPI, negotiates with the container to execute the test and return the result and, lastly,
undeploys the artifact. TestNG collects the results of all the tests run in the typical
way and produces a report.</para>
+ <graphic fileref="images/in-container-execution.png"
align="center"/>
+ <para>The question is, how does the JBoss Test Harness negotiate with the
container to execute the test when TestNG is being invoked locally? Technially the
mechanism is pluggable, but JBoss Test Harness provides a default implementation that uses
HTTP communication that you will likely use. Here's how the default
implementation works works.</para>
+ <para>The artifact generator bundles and registers (in the web.xml descriptor)
an <literal>HttpServlet</literal>,
<literal>org.jboss.testharness.impl.runner.servlet.ServletTestRunner</literal>,
that responds to test execution GET requests. TestNG running on the client side delegates
to a test launcher (more on that in a moment) which originates these text execution
requests to transfer control to the container JVM. The name of the test method to be
executed is specified in a request parameter named
<literal>methodName</literal>.</para>
+ <para>When the test execution request is received, the servlet delegates to an
instance of <literal>org.jboss.testharness.impl.runner.TestRunner</literal>,
passing it the name of the test method. <literal>TestRunner</literal> reads
the name of the test class from the resource META-INF/jboss-test-harness.properties, which
is bundled in the artifact by the artifact generator. It then combines the class name with
the method name to produce a TestNG test suite and runs the suite (in the context of the
container).</para>
+ <para>TestNG returns the results of the run as an
<literal>ITestResult</literal> object.
<literal>ServletTestRunner</literal> translates this object into a
<literal>org.jboss.testharness.api.TestResult</literal> and passes it back to
the test launcher on the client side by encoding the translated object into the response.
The object gets encoded as either html or a serialized object, depending on the value of
the <literal>outputMode</literal> request parameter that was passed to the
servlet. Once the result has been transfered to the client-side TestNG, TestNG wraps up
the run of the test as though it had been executed in the same JVM.</para>
+ <para>There's one piece missing. How does TestNG on the client side
know to submit a request to the <literal>ServletTestRunner</literal> servlet
to get TestNG to execute the test in the container JVM? That's the role of the
test launcher.</para>
+ <para>The test launcher is the API that allows test suite to launch the test in
a pluggable fashion. <literal>AbstractTest</literal>, the super class of
<literal>AbtractJSR299Test</literal>, implements
<literal>IHookable</literal>, a TestNG interface which allows the execution of
the test method to be intercepted. Using that mechanism, AbstractTest delegates execution
of the test method (a method annotated with <literal>@Test</literal> in an
<literal>@Artifact</literal> class) to an implementation of
<literal>org.jboss.testharness.api.TestLauncher</literal> if the tests are
being executed in-container. As you might anticipate, the implementation is specified
using a property with the same name as the interface in a
META-INF/jboss-test-launcher.properties resource. The JBoss Test Harness provides a
default implementation,
<literal>org.jboss.testharness.impl.runner.servlet.ServletTestLauncher</literal>,
that hooks into the HTTP communication infrastructure described above!
. It invokes the <literal>ServletTestRunner</literal> servlet for each method
annotated with <literal>@Test</literal> in the
<literal>@Artifact</literal> that is not otherwise disabled.</para>
+ <para>If you wish to implement the runner yourself, you must return a
<literal>TestResult</literal> as a result of executing the method in the
container. You must also ensure that any exception which occurs during deployment is
wrapped as a <literal>org.jboss.testharness.api.DeploymentException</literal>,
and that any communication problem is rethrown as an
<literal>IOException</literal>. The deployment exception may be transformed by
an implementation of the
<literal>org.jboss.testharness.api.DeploymentExceptionTransformer</literal>
interface, which is specified using the
<literal>org.jboss.testharness.container.deploymentExceptionTransformer</literal>
property. The default implementation passes on the original exception
unchanged.</para>
+ <para>So in short, JBoss Test Harness takes care of all the interfaces you need
to execute tests in-container except for the implementation of the
<literal>Containers</literal> SPI. That is, unless you are deploying to one of
the containers supported by the JBoss Test Harness.</para>
+ </section>
</chapter>
Added: tck/trunk/doc/reference/en-US/eclipse-debugging.xml
===================================================================
--- tck/trunk/doc/reference/en-US/eclipse-debugging.xml (rev 0)
+++ tck/trunk/doc/reference/en-US/eclipse-debugging.xml 2009-07-15 04:20:28 UTC (rev
3052)
@@ -0,0 +1,55 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<chapter id="eclipse-debugging">
+ <title>Debugging Tests in Eclipse</title>
+ <para>This chapter explains how to debug standalone tests and integration tests
from the TCK test suite in Eclipse. You should be able to use the lessons learned here to
debug tests in an alternate IDE.</para>
+ <section>
+ <title>Debugging a standalone test</title>
+ <para>There is almost no difference in how you debug a standalone test from how
you run it. With the test class open in the Eclipse editor, simply right click in the
editor view and select TestNG > Debug as test. Eclipse will stop at any breakpoints
you set just like it would with any other local debug process.</para>
+ <para>If you plan to step into a class in a JSR-299 implementation (or any
other dependent library), you must ensure that the source is properly associated with the
library. Below are the steps to follow to associate the source of the JSR-299 RI with the
TestNG debug configuration: </para>
+ <orderedlist>
+ <listitem>
+ <para>Select the Run > Debug Configurations... menu from the main
menubar</para>
+ </listitem>
+ <listitem>
+ <para>Select the name of the test class in the TestNG
category</para>
+ </listitem>
+ <listitem>
+ <para>Select the Source tab</para>
+ </listitem>
+ <listitem>
+ <para>Click the Add... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Select Java Project</para>
+ </listitem>
+ <listitem>
+ <para>Check the project the contains the class you want to debug (e.g.,
webbeans-core)</para>
+ </listitem>
+ <listitem>
+ <para>Click OK on the Project Selection window</para>
+ </listitem>
+ <listitem>
+ <para>Click Close on the Debug Configurations window</para>
+ </listitem>
+ </orderedlist>
+ <para>You'll have to complete those steps for any test class you are
debugging, though you only have to do it once (the debug configuration hangs around
indefinitely).</para>
+ <para>Again, running a test in standalone isn't enough to pass the TCK
and cannot be used to run or debug an integration test. Let's look at how to
debug a test running in the context of the container.</para>
+ </section>
+ <section>
+ <title>Debugging an integration test</title>
+ <para>In order to debug an integration test, or any test run in in-container
mode, the test must be configured to run in-container, as described in section 6.4, and
you must attach the IDE debugger to the container. That puts the debugger on both sides
of the fence, so to speak.</para>
+ <para>Since setting up a test to run in-container has already been covered,
we'll look at how to attach the IDE debugger to the container, and then move on
launching the test in debug mode.</para>
+ <section>
+ <title>Attaching the IDE debugger to the container</title>
+ <para>There are two ways to attach the IDE debugger to the container. You can
either start the container in debug mode from within the IDE, or you can attach the
debugger over a socket connection to a standalone container running with JPDA
enabled.</para>
+ <para>The Eclipse Server Tools, a subproject of the Eclipse Web Tools Project
(WTP), has support for launching most major application servers, including JBoss AS 5.
However, if you are using JBoss AS, you should consider using JBoss Tools instead, which
offers tighter integration with JBoss technologies. See either the <ulink
url="http://www.eclipse.org/webtools/server/server.php">Server Tools
documentation</ulink> or the <ulink
url="http://docs.jboss.org/tools/3.0.1.GA/en/as/html/index.html"... Tools
documentation</ulink> for how to setup a container and start it in debug
mode.</para>
+ <para>See <ulink
url="http://maverikpro.wordpress.com/2007/11/26/remote-debug-a-web-a...
blog entry</ulink> to learn how to start JBoss with JPDA enabled and how to get the
Eclipse debugger to connect to the remote process.</para>
+ </section>
+ <section>
+ <title>Launching the test in the debugger</title>
+ <para>Once Eclipse is debugging the container, you can set a breakpoint in
the test and debug it just like a standalone test. Open a test annotated with
<literal>@IntegrationTest</literal> in the Eclipse editor, right click in the
editor view, and select TestNG > Debug as test. The only difference is that when
the IDE hits the breakpoint this time, it halts the JVM thread of the container rather
than the thread that launched the test.</para>
+ <para>Remember that if you need to debug into dependent libraries, the source
code for those libraries needs to be registered with the TestNG debug configuration as
described in the first section in this chapter.</para>
+ </section>
+ </section>
+</chapter>
Added: tck/trunk/doc/reference/en-US/eclipse-running.xml
===================================================================
--- tck/trunk/doc/reference/en-US/eclipse-running.xml (rev 0)
+++ tck/trunk/doc/reference/en-US/eclipse-running.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -0,0 +1,154 @@
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<chapter id="eclipse-running">
+ <title>Running Tests in Eclipse</title>
+ <para>This chapter explains how to run individual tests using the Eclipse TestNG
plugin. It covers running non-integration tests in standalone mode and integration tests
(as well as non-integration tests) in in-container mode. You should be able to use the
lessons learned here to debug tests in an alternate IDE.</para>
+ <section>
+ <title>Leveraging Eclipse's plugin ecosystem</title>
+ <para>The primary motivation for building the test harness on top of an
existing testing framework is to allow the tests to be executed and debugged in an
Integrated Development Environment (IDE) using availalbe plugins. It's also the
easiest way to execute a test class in isolation.</para>
+ <para>The TCK can be executed in any IDE for which there is a TestNG plugin
available. Running a test in Eclipse is almost as simple as running the test with the
Eclipse TestNG plugin. You can also use the plugin to debug a test, which is described in
the next chapter.</para>
+ <para>Before running a test from the TCK test suite in Eclipse, you must have
the Eclipse <ulink url="http://testng.org">TestNG plugin</ulink> and
the m2eclipse plugin installed. Refer to section 2.2.2 for more information on these
plugins.</para>
+ <para>With the m2eclipse plugin installed, Eclipse should recognize the JSR-299
TCK projects as valid Eclipse projects (or any Web Beans project for that matter). Import
them into the Eclipse workspace at this time. You should also import the JSR-299 RI
projects if you want to debug into that code, which is covered later.</para>
+ </section>
+ <section>
+ <title>Readying the Eclipse workspace</title>
+ <para>When setting up your Ecilpse workspace, I recommend creating three
workings sets: one for the JSR-299 RI (Web Beans), one for the JSR-299 TCK and one for the
JBoss TCK Runner. The dependencies between the projects will be established automatically
by the m2eclipse plugin based on the dependency information in the pom.xml files. Your
workspace should appear as follows:</para>
+ <programlisting>JSR-299 RI
+ jsr299-api
+ webbeans-api
+ webbeans-core
+ webbeans-core-test
+ webbeans-logging
+ webbeans-parent
+ webbeans-spi
+ webbeans-version-matrix
+JSR-299 TCK
+ jsr299-tck-api
+ jsr299-tck-impl
+ parent
+Web Beans JBoss TCK Runner
+ webbeans-jboss-tck-runner
+ webbeans-porting-package</programlisting>
+ <para>The tests in the TCK test suite are located in the jsr299-tck-impl
project. You'll be working within this project in Eclipse when you are developing
tests. However, you learned earlier, there are no references to a JSR-299 implementation
in the TCK. So how can you execute an individual test in Eclipse? The secret is that you
need to establish a link in Eclipse (not in Maven) between the jsr299-tck-impl project and
your TCK runner project, which in this case is webbeans-jboss-tck-runner. Here are the
steps to establish the link:</para>
+ <orderedlist>
+ <listitem>
+ <para>Right click on the jsr299-tck-impl project</para>
+ </listitem>
+ <listitem>
+ <para>Select Build Path > Configure Build Path...</para>
+ </listitem>
+ <listitem>
+ <para>Click on the Projects tab</para>
+ </listitem>
+ <listitem>
+ <para>Click the Add... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Check the TCK runner project (e.g.,
webbeans-jboss-tck-runner)</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Required Project Selection dialog
window</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Java Build Path window</para>
+ </listitem>
+ </orderedlist>
+ <para>The TCK runner project should pull in the JSR-299 implementation, the TCK
porting package and any additional properties that must be defined to execute the TCK test
suite.</para>
+ </section>
+ <section>
+ <title>Running a test in standalone mode</title>
+ <para>Your now ready to execute an individual test class (a class which extends
AbstractJSR299Test and is annotated with @Artifact). Select a test class that is
<emphasis role="italic">not</emphasis> annotated with
<literal>@IntegrationTest</literal> and open it in the Eclipse editor. Right
click in the editor view and select TestNG > Run as test. The TestNG view should
pop out and you should see all the tests pass (hopefully).</para>
+ <note>
+ <para>If the TCK complains that there is a property missing, close all the
projects, open them again, and rebuild. The m2eclipse plugin can be finicky getting
everything built correctly the first time.</para>
+ </note>
+ <para>So far you have executed a test in standalone mode. That's not
sufficient to pass the TCK. The test must be executed in in-container mode. Using
in-container mode also the only way to execute a test annotated with
<literal>@IntegrationTest</literal> as it requires container resources. So
let's see what has to be done to execute an integration test. This will result in
the artifact being deployed to the container, which is JBoss AS 5.1 if you are using the
JBoss TCK runner.</para>
+ </section>
+ <section>
+ <title>Running integration tests</title>
+ <para>As you have learned, the JBoss test harness determines how to behave
based on the values of numerous system properties or properties defined in
META-INF/jboss-test-harness.properties classpath resources. If the property named
<literal>org.jboss.testharness.standalone</literal> is not defined, the
harness assumes that the test is to be run in standalone mode. In order to run the tests
in the container, you need to add a properties file to the classpath that sets the
standalone property to false and provides values for other properties required to run an
in-container test.</para>
+ <para>The JBoss TCK runner project conveniently provides the properties file
src/test/debug-resources/META-INF/jboss-test-harness.properties that contains all of the
necessary properties. You may have to tune the
<literal>org.jboss.testharness.container.extraConfigurationDir</literal> and
<literal>org.jboss.testharness.libraryDirectory</literal> properties to point
to the relative location of the related projects. The properties should be defined as
follows:</para>
+ <itemizedlist>
+ <listitem>
+
<para><literal>org.jboss.testharness.container.extraConfigurationDir</literal>
- the relative path from the jboss-tck-impl project to a directory that contains a
build.properties or local.build.properties file defining the location of a JBoss AS 5.1
installation in the <literal>jboss.home</literal> property</para>
+ </listitem>
+ <listitem>
+ <para><literal>org.jboss.testharness.libraryDirectory</literal>
- the relative path from the jboss-tck-impl project to the target/dependency/lib directory
in the TCK runner project.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The other properties in that file are defined as follows:</para>
+ <programlisting>org.jboss.testharness.standalone=false
+orjboss.testharness.container.forceRestart=false
+orjboss.testharness.runIntegrationTests=true</programlisting>
+ <para>You're now ready to execute an integration test. Select an
integration test (a class that extends <literal>AbstractJSR299Test</literal>
and is annotated with both <literal>@Artifact</literal> and
<literal>@IntegrationTest</literal>) and open it in your Eclipse editor.
Follow these steps to execute the class with the TestNG plugin:</para>
+ <orderedlist>
+ <listitem>
+ <para>Right click in the editor view and select TestNG > Run as
test</para>
+ </listitem>
+ <listitem>
+ <para>Observe the test fail because of missing dependencies</para>
+ </listitem>
+ <listitem>
+ <para>Select the Run > Run Configurations... menu from the main
menubar</para>
+ </listitem>
+ <listitem>
+ <para>Select the name of the test class under the TestNG
category</para>
+ </listitem>
+ <listitem>
+ <para>Select the Classpath tab</para>
+ </listitem>
+ <listitem>
+ <para>Select User Entries in the tree</para>
+ </listitem>
+ <listitem>
+ <para>Click the Advanced... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Select Add Folders and click the OK button</para>
+ </listitem>
+ <listitem>
+ <para>Select the webbeans-jboss-tck-runner/src/test/debug-resources
folder</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Folder Selection dialog
window</para>
+ </listitem>
+ <listitem>
+ <para>Click on the webbeans-jboss-tck-runner entry</para>
+ </listitem>
+ <listitem>
+ <para>Move the webbeans-jboss-tck-runner to the first entry using the Up
button</para>
+ </listitem>
+ <listitem>
+ <para>Click the Run button on the Run Configurations dialog
window</para>
+ </listitem>
+ </orderedlist>
+ <para>When you run the test this time, it should pass. If you get a failure
that the container (e.g., JBoss AS 5.1) must be run with assertions enabled, you need to
stop the container and start it with the -ea flag (or just leave it stopped and the test
will start it appropriately). </para>
+ <para>You can simply right click and select TestNG > Run as test for all
subsequent runs for the reason cited earlier, the run configuration for a class is
retained indefinitely.</para>
+ <para>Alternatively, you can configure TestNG to execute all tests in-container
by default by adding the properties file in the debug-resources folder to the
project's classpath as follows:</para>
+ <orderedlist>
+ <listitem>
+ <para>Right click on the jsr299-tck-impl project</para>
+ </listitem>
+ <listitem>
+ <para>Select Build Path > Configure Build Path...</para>
+ </listitem>
+ <listitem>
+ <para>Click on the Libraries tab</para>
+ </listitem>
+ <listitem>
+ <para>Click the Add Class Folder... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Check the webbeans-jboss-tck-runner/src/test/debug-resources
folder</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Class Folder Selection dialog
window</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Java Build Path window</para>
+ </listitem>
+ </orderedlist>
+ <para>Now you don't have to do any special configuration for each test
class.</para>
+ <para>You can stop the individual tests from running in-container by reversing
the steps above to remove the debug-resources folder from the Eclipse classpath.
</para>
+ <para>You have now mastered running the JSR-299 TCK against the JSR-299 RI
using both Maven 2 and within Eclipse. Now you're likely interested in how to
debug a test so that you can efficiently investigate test failures.</para>
+ </section>
+</chapter>
Modified: tck/trunk/doc/reference/en-US/executing.xml
===================================================================
--- tck/trunk/doc/reference/en-US/executing.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/executing.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,41 +1,194 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<chapter id="executing">
- <title>Executing Tests</title>
- <para>This chapter explains how to execute the TCK against the JSR-299 RI as well
as your own implementation. The JSR-299 TCK uses the Maven 2 TestNG plugin and the JBoss
Test Harness to execute the tests in the test suite. For detailed instructions that
explain how to use the JBoss Test Harness, see the JBoss Test Harness
documentation.</para>
+ <title>Executing the Test Suite</title>
+ <para>This chapter explains how to run the TCK on the JSR-299 RI as well as your
own implementation. The JSR-299 TCK uses the Maven 2 TestNG plugin and the JBoss Test
Harness to execute the test suite. Learning to execute the test suite from Maven 2 is
prerequisite knowlege for running the tests in an IDE, such as Eclipse.</para>
<section>
- <title>Launching the Test Suite</title>
- <para>Each test class is treated as an individual artifact (hence the
<literal>@Artifact</literal> annotation on the class). All test methods (i.e.,
methods annotated with <literal>@Test</literal>) in the same class are run in
a single environment, meaning bean discovery occurs exactly once per artifact and the same
BeanManager is used by each test method in the class.</para>
- <para>The test suite is executed by the TestNG plugin for Maven 2 during the
test phase of the Maven 2 life cycle. The execution happens within a TCK runner project
(as opposed to the TCK project itself). Web Beans includes a TCK runner project that
executes the JSR-299 TCK against the JSR-299 RI (Web Beans) on JBoss AS 5.1. To execute
the JSR-299 TCK against your own JSR-299 implementation, you must modify the TCK runner
project included with Web Beans to use your JSR-299 implementation as described in
section XX.X.</para>
- <section>
- <title>Running the Tests In Standalone Mode</title>
- <para>To execute the TCK test suite against the JSR-299 RI, first change to
the jboss-tck-runner directory in the extracted Web Beans distribution:</para>
- <programlisting>cd
<webbeans_install_dir>/jboss-tck-runner</programlisting>
- <para>Then execute the Maven 2 life cycle through the test
phase:</para>
- <programlisting>mvn test</programlisting>
- <para>Without any command-line flags, the test suite is run in standalone
mode, which means that any test class with the
<literal>(a)org.jboss.testharness.impl.packaging.IntegrationTest</literal>
annotation is skipped. This mode uses the
<literal>StandaloneContainers</literal> SPI to invoke the test artifact within
a mock Java EE life cycle and capture the results of the test. However, passing the suite
in this mode is not sufficient to pass the TCK as a whole. The suite must be passed while
executing using in-container mode.</para>
- </section>
- <section>
- <title>Running the Tests In In-Container Mode</title>
- <para>To execute the test suite using in-container mode, you first have to
set the property <literal>jboss.home</literal> to the location of a JBoss AS
5.1 installation in the following Java properties file in the extracted Web Beans
distribution:</para>
-
<programlisting><webbeans_install_dir>/jboss-as/local.build.properties</programlisting>
- <para>Then add the <literal>incontainer</literal> property to the
command that launches the Maven 2 life cycle:</para>
- <programlisting>mvn test -Dincontainer</programlisting>
- <para>The presence of the <literal>incontainer</literal> property
activates a Maven 2 profile that assigns the
<literal>org.jboss.testharness.standalone</literal> system property to
<literal>false</literal> and the
<literal>org.jboss.testharness.runIntegrationTests</literal> system property
to <literal>true</literal>, hence activing the in-container test
mode.</para>
- <para>When the Maven 2 life cycle is run with the
<literal>incontainer</literal> property present, all the test artifacts in the
test suite are executed. The in-container mode uses the
<literal>Containers</literal> SPI to deploy the test artifact to the container
and execute the test in a true Java EE life cycle.</para>
- <para>Since in-container tests are executed in a remote JVM, the results of
the test must be communicated back to the runner over a container-supported protocol. The
TCK provides servlet-based communication over HTTP.</para>
- </section>
- <section>
- <title>Running a Subset of Tests</title>
- <para/>
- </section>
- <section>
- <title>Dumping a Test Artifact</title>
- <para/>
- </section>
- <section>
- <title>Running a Test in Eclipse</title>
- <para/>
- </section>
+ <title>The Test Suite Runner</title>
+ <para>Each test class is treated as an individual artifact (hence the
<literal>@Artifact</literal> annotation on the class). All test methods (i.e.,
methods annotated with <literal>@Test</literal>) in the test class are run in
the same JSR-299 root context, meaning bean discovery occurs exactly once per artifact and
the same BeanManager is used by each test method in the class.</para>
+ <para>The test suite is executed by the Maven 2 TestNG plugin during the test
phase of the Maven 2 life cycle. The execution happens within a TCK runner project (as
opposed to the TCK project itself). Web Beans includes a TCK runner project that executes
the JSR-299 TCK on the JSR-299 RI (Web Beans) running inside JBoss AS 5.1. To execute the
JSR-299 TCK on your own JSR-299 implementation, you must modify the TCK runner project
included with Web Beans to use your JSR-299 implementation as described in section
4.2.</para>
</section>
+ <section>
+ <title>Running the Tests In Standalone Mode</title>
+ <para>To execute the TCK test suite against the JSR-299 RI, first switch to the
jboss-tck-runner directory in the extracted Web Beans distribution:</para>
+ <programlisting>cd
<webbeans_install_dir>/jboss-tck-runner</programlisting>
+ <para>Then execute the Maven 2 life cycle through the test phase:</para>
+ <programlisting>mvn test</programlisting>
+ <para>Without any command-line flags, the test suite is run in standalone mode,
which means that any test class with the
<literal>(a)org.jboss.testharness.impl.packaging.IntegrationTest</literal>
annotation is skipped. This mode uses the
<literal>StandaloneContainers</literal> SPI to invoke the test artifact within
a mock Java EE life cycle and capture the results of the test. However, passing the suite
in this mode is not sufficient to pass the TCK as a whole. The suite must be passed while
executing in in-container mode.</para>
+ </section>
+ <section>
+ <title>Running the Tests In the Container</title>
+ <para>To execute the test suite using in-container mode with the JBoss TCK
runner, you first have to set the property <literal>jboss.home</literal> to
the location of a JBoss AS 5.1 installation. This property is set in the following Java
properties file within the extracted Web Beans distribution:</para>
+
<programlisting><webbeans_install_dir>/jboss-as/local.build.properties</programlisting>
+ <para>Then, add the <literal>incontainer</literal> property to the
command that launches the Maven 2 life cycle:</para>
+ <programlisting>mvn test -Dincontainer</programlisting>
+ <para>The presence of the <literal>incontainer</literal> property
activates a Maven 2 profile that assigns the
<literal>org.jboss.testharness.standalone</literal> system property to
<literal>false</literal> and the
<literal>org.jboss.testharness.runIntegrationTests</literal> system property
to <literal>true</literal>, hence activing the in-container test
mode.</para>
+ <para>When the Maven 2 life cycle is run with the
<literal>incontainer</literal> property present, all the test artifacts in the
test suite are executed. The in-container mode uses the
<literal>Containers</literal> SPI to deploy the test artifact to the container
and execute the test in a true Java EE life cycle. The JBoss TCK runner has a dependency
on the library that provides an implementation of this interface for JBoss AS
5.1.</para>
+ <para>Since in-container tests are executed in a remote JVM, the results of the
test must be communicated back to the runner over a container-supported protocol. The
JBoss Test Harness provides servlet-based communication over HTTP as described in section
3.3.</para>
+ </section>
+ <section>
+ <title>Running a Subset of Tests</title>
+ <para>The TCK test suite is controlled by a TestNG descriptor. The TestNG
descriptor tck-tests.xml, located in the src/main/resources directory of the
jsr299-tck-impl project, defines the TCK test suite. The main configuration in this file
is the packages filter, shown below, which instructs TestNG to look in the
<literal>org.jboss.jsr299.tck.tests</literal> package to find the test
classes.</para>
+ <programlisting><packages>
+ <package name="org.jboss.jsr299.tck.tests"/>
+</packages></programlisting>
+ <para>The descriptor also includes configuration of a method selector
implementation, shown below, that allows integration tests to be skipped when the test
suite is executed in standalone mode.</para>
+ <programlisting><method-selectors>
+ <method-selector>
+ <selector-class name="org.jboss.testharness.impl.
+testng.DisableIntegrationTestsMethodSelector" />
+ </method-selector>
+</method-selectors></programlisting>
+ <para>You may also notice other filters in this class, which are used to
disable broken tests while the JSR-299 RI and the TCK are being developed. When both are
final, you can expect these filters to be removed. However, you may want to use similar
filters to disable tests while you are working on an implementation. Alternatively, you
can explicity list the classes that you want to have executed if you are focusing on a
specific area of the TCK. See the <ulink
url="http://testng.org/doc/documentation-main.html">TestNG reference
guide</ulink> for more information about how you can control which classes are
selected to be run when the test suite is executed.</para>
+ </section>
+ <section>
+ <title>Dumping the Test Artifacts</title>
+ <para>As you have learned, when the test suite is executing using in-container
mode, each test class is packaged as a deployable artifact and deployed to the container.
The test is then executed within the context of the deployed application. This leaves room
for errors in packaging. When investingating a test failure, it's helpful to be
able to inspect the artifact after it is generated. The TCK can accomodate this type of
inspection by "dumping" the generated artifact to disk.</para>
+ <para>If the <literal>dumpArtifacts</literal> is defined as a
system property or defined in the classpath resource
META-INF/jboss-test-harness.properties and has a value of
<literal>true</literal>, the JBoss Test Harness will write the artifact to an
output directory prior to deploying it to the server. This behavior is activated in the
jboss-tck-runner project by appending the <literal>dumpArtifacts</literal>
command line property to the end of the command that invokes the Maven test
phase.</para>
+ <programlisting>mvn test -Dincontainer -DdumpArtifacts</programlisting>
+ <para>If you only want to write the artifacts to disk, and avoid executing the
test suite, you can simply execute the main method of the class
<literal>org.jboss.testharness.api.TCK</literal>. This execution is configured
as a Maven profile that is activated when the <literal>dumpArtifacts</literal>
command line property is defined:</para>
+ <programlisting>mvn test-compile -DdumpArtifacts</programlisting>
+ <para>The output directory where the artifacts are written is defined by the
property <literal>org.jboss.testharness.outputDirectory</literal>. The
jboss-tck-runner project is configured to dump the artifacts to the
target/jsr299-artifacts directory.</para>
+ <para>Once the artifact is written to disk, you have to option of manually
deploying it to the container. You can execute the tests in the artfact by requesting the
context path of the application in the browser. If you want to execute an individual test
method, specify the method name in the <literal>methodName</literal> request
parameter (e.g., ?methodName=testMethodName).</para>
+ </section>
+ <section>
+ <title>Running a Test in Eclipse</title>
+ <para>The primary motivation for building the test harness on top of an
existing testing framework is to allow the tests to be executed and debugged in an
Integrated Development Environment (IDE) using availalbe plugins. It's also the
easiest way to execute a test class in isolation.</para>
+ <para>The TCK can be executed in any IDE for which there is a TestNG plugin
available. Running a test in Eclipse is almost as simple as running the test with the
Eclipse TestNG plugin. You can also use the TestNG plugin to debug a test, which is
described in the next chapter.</para>
+ <para>Before running a test from the TCK test suite in Eclipse, you must have
the Eclipse <ulink url="http://testng.org">TestNG plugin</ulink>
installed. Instructions for using the TestNG update site to add the TestNG plugin to
Eclipse are provided on the TestNG <ulink
url="http://testng.org/doc/download.html">download page</ulink>. You
can find a tutorial that explains how to use the TestNG plugin on the TestNG <ulink
url="http://testng.org/doc/eclipse.html">Eclipse
page</ulink>.</para>
+ <para>You should also have the <ulink
url="http://m2eclipse.codehaus.org">m2eclipse plugin</ulink> installed.
This plugin absolutely essential for working with Maven 2 projects, which both the JSR-299
RI and the TCK are. Instructions for using the m2eclipse update site to add the m2eclipse
plugin to Eclipse are provided on the m2eclipse home page. Sonatype, the company that
maintains the m2eclipse plugin and is a strong supporter of Maven, publishes an entire
<ulink
url="http://www.sonatype.com/books/m2eclipse-book/reference">...
guide</ulink> dedicated to the plugin on their website.</para>
+ <para>Once you have the m2eclipse plugin installed, import the JSR-299 TCK
projects. You should also import the JSR-299 RI projects if you want to debug into that
code.</para>
+ <para>When setting up your Ecilpse workspace, I recommend creating three
workings sets: one for the JSR-299 RI (Web Beans), one for the JSR-299 TCK and one for the
JBoss TCK Runner. The dependencies between the projects will be established automatically
by the m2eclipse plugin based on the dependency information in the pom.xml files. Your
workspace should appear as follows:</para>
+ <programlisting>JSR-299 RI
+ jsr299-api
+ webbeans-api
+ webbeans-core
+ webbeans-core-test
+ webbeans-logging
+ webbeans-parent
+ webbeans-spi
+ webbeans-version-matrix
+JSR-299 TCK
+ jsr299-tck-api
+ jsr299-tck-impl
+ parent
+Web Beans JBoss TCK Runner
+ webbeans-jboss-tck-runner
+ webbeans-porting-package</programlisting>
+ <para>The tests in the TCK test suite are located in the jsr299-tck-impl
project. You'll be working within this project in Eclipse when you are developing
tests. However, you learned earlier, there are no references to a JSR-299 implementation
in the TCK. So how can you execute an individual test in Eclipse? The secret is that you
need to establish a link in Eclipse (not in Maven) between the jsr299-tck-impl project and
your TCK runner project, which in this case is webbeans-jboss-tck-runner. Here are the
steps to establish the link:</para>
+ <orderedlist>
+ <listitem>
+ <para>Right click on the jsr299-tck-impl project</para>
+ </listitem>
+ <listitem>
+ <para>Select Build Path > Configure Build Path...</para>
+ </listitem>
+ <listitem>
+ <para>Click on the Projects tab</para>
+ </listitem>
+ <listitem>
+ <para>Click the Add... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Check the TCK runner project (e.g.,
webbeans-jboss-tck-runner)</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Required Project Selection dialog
window</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Java Build Path window</para>
+ </listitem>
+ </orderedlist>
+ <para>The TCK runner project should pull in the JSR-299 implementation, the TCK
porting package and any additional properties that must be defined to execute the TCK test
suite.</para>
+ <para>Your now ready to execute an individual test class (a class which extends
AbstractJSR299Test and is annotated with @Artifact). Select a test class that is
<emphasis role="italic">not</emphasis> annotated with
<literal>@IntegrationTest</literal> and open it in the Eclipse editor. Right
click in the editor view and select TestNG > Run as test. The TestNG view should
pop out and you should see all the tests pass (hopefully).</para>
+ <note>
+ <para>If the TCK complains that there is a property missing, close all the
projects, open them again, and rebuild. The m2eclipse plugin can be finicky getting
everything built correctly the first time.</para>
+ </note>
+ <para>So far you have executed a test in standalone mode. That's not
sufficient to pass the TCK. The test must be executed in in-container mode. Using
in-container mode also the only way to execute a test annotated with
<literal>@IntegrationTest</literal> as it requires container resources. So
let's see what has to be done to execute an integration test. This will result in
the artifact being deployed to the container, which is JBoss AS 5.1 if you are using the
JBoss TCK runner.</para>
+ <para>As you have learned, the JBoss test harness determines how to behave
based on the values of numerous system properties or properties defined in
META-INF/jboss-test-harness.properties classpath resources. If the property named
<literal>org.jboss.testharness.standalone</literal> is not defined, the
harness assumes that the test is to be run in standalone mode. In order to run the tests
in the container, you need to add a properties file to the classpath that sets the
standalone property to false and provides values for other properties required to run an
in-container test.</para>
+ <para>The JBoss TCK runner project conveniently provides the properties file
src/test/debug-resources/META-INF/jboss-test-harness.properties that contains all of the
necessary properties. You may have to tune the
<literal>org.jboss.testharness.container.extraConfigurationDir</literal> and
<literal>org.jboss.testharness.libraryDirectory</literal> properties to point
to the relative location of the related projects. The properties should be defined as
follows:</para>
+ <itemizedlist>
+ <listitem>
+
<para><literal>org.jboss.testharness.container.extraConfigurationDir</literal>
- the relative path from the jboss-tck-impl project to a directory that contains a
build.properties or local.build.properties file defining the location of a JBoss AS 5.1
installation in the <literal>jboss.home</literal> property</para>
+ </listitem>
+ <listitem>
+ <para><literal>org.jboss.testharness.libraryDirectory</literal>
- the relative path from the jboss-tck-impl project to the target/dependency/lib directory
in the TCK runner project.</para>
+ </listitem>
+ </itemizedlist>
+ <para>The other properties in that file are defined as follows:</para>
+ <programlisting>org.jboss.testharness.standalone=false
+org.oss.testharness.container.forceRestart=false
+org.oss.testharness.runIntegrationTests=true</programlisting>
+ <para>You're now ready to execute an integration test. Select an
integration test (a class that extends <literal>AbstractJSR299Test</literal>
and is annotated with both <literal>@Artifact</literal> and
<literal>@IntegrationTest</literal>) and open it in your Eclipse editor.
Follow these steps to execute the class with the TestNG plugin:</para>
+ <orderedlist>
+ <listitem>
+ <para>Right click in the editor view and select TestNG > Run as
test</para>
+ </listitem>
+ <listitem>
+ <para>Observe the test fail because of missing dependencies</para>
+ </listitem>
+ <listitem>
+ <para>Select the Run > Run Configurations... menu from the main
menubar</para>
+ </listitem>
+ <listitem>
+ <para>Select the name of the test class under the TestNG
category</para>
+ </listitem>
+ <listitem>
+ <para>Select the Classpath tab</para>
+ </listitem>
+ <listitem>
+ <para>Select User Entries in the tree</para>
+ </listitem>
+ <listitem>
+ <para>Click the Advanced... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Select Add Folders and click the OK button</para>
+ </listitem>
+ <listitem>
+ <para>Select the webbeans-jboss-tck-runner/src/test/debug-resources
folder</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Folder Selection dialog
window</para>
+ </listitem>
+ <listitem>
+ <para>Click on the webbeans-jboss-tck-runner entry</para>
+ </listitem>
+ <listitem>
+ <para>Move the webbeans-jboss-tck-runner to the first entry using the Up
button</para>
+ </listitem>
+ <listitem>
+ <para>Click the Run button on the Run Configurations dialog
window</para>
+ </listitem>
+ </orderedlist>
+ <para>When you run the test this time, it should pass. If you get a failure
that the container (e.g., JBoss AS 5.1) must be run with assertions enabled, you need to
stop the container and start it with the -ea flag (or just leave it stopped and the test
will start it appropriately). </para>
+ <para>You can simply right click and select TestNG > Run as test for all
subsequent runs for the reason cited earlier, the run configuration for a class is
retained indefinitely.</para>
+ <para>Alternatively, you can configure TestNG to execute all tests in-container
by default by adding the properties file in the debug-resources folder to the
project's classpath as follows:</para>
+ <orderedlist>
+ <listitem>
+ <para>Right click on the jsr299-tck-impl project</para>
+ </listitem>
+ <listitem>
+ <para>Select Build Path > Configure Build Path...</para>
+ </listitem>
+ <listitem>
+ <para>Click on the Libraries tab</para>
+ </listitem>
+ <listitem>
+ <para>Click the Add Class Folder... button on the right</para>
+ </listitem>
+ <listitem>
+ <para>Check the webbeans-jboss-tck-runner/src/test/debug-resources
folder</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Class Folder Selection dialog
window</para>
+ </listitem>
+ <listitem>
+ <para>Click the OK button on the Java Build Path window</para>
+ </listitem>
+ </orderedlist>
+ <para>Now you don't have to do any special configuration for each test
class.</para>
+ <para>You can stop the individual tests from running in-container by reversing
the steps above to remove the debug-resources folder from the Eclipse classpath.
</para>
+ <para>You have now mastered running the JSR-299 TCK against the JSR-299 RI
using both Maven 2 and within Eclipse. Now you're likely interested in how to
debug a test so that you can efficiently investigate test failures.</para>
+ </section>
</chapter>
Added: tck/trunk/doc/reference/en-US/images/in-container-execution.png
===================================================================
(Binary files differ)
Property changes on: tck/trunk/doc/reference/en-US/images/in-container-execution.png
___________________________________________________________________
Name: svn:mime-type
+ application/octet-stream
Modified: tck/trunk/doc/reference/en-US/installation.xml
===================================================================
--- tck/trunk/doc/reference/en-US/installation.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/installation.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<chapter id="installation">
<title>Installation</title>
<para>This chapter explains how to obtain the TCK and supporting software and
provides recommendations for how to install/extract it on your system.</para>
@@ -7,11 +7,11 @@
<title>Obtaining the Software</title>
<para>You can obtain the JSR-299 TCK project from the <ulink
url="http://anonsvn.jboss.org/repos/webbeans/tck/trunk">JBoss SVN
repository</ulink> or you can download a release from the <ulink
url="http://seamframework.org/Download">download page</ulink> on Seam
Framework website. The JSR-299 TCK is distributed as a ZIP file, which contains a
multi-module Maven 2 project, the test suite, the test suite descriptor, the audit
document and documentation. At the time of writing there is no official release of the
JSR-299 TCK available, so you need to check out the TCK from the JBoss SVN
repository.</para>
<para>The TCK project downloads additional required libraries from the JBoss
Maven 2 repository automatically, including the JBoss Test Harness and the JSR-299 API.
You may follow this approach when assembling a TCK runner for your JSR-299
implementation.</para>
- <para>The JSR-299: Contexts and Dependency Injection for Java EE 1.0 reference
implementation (RI) is Web Beans. You can obtain the latest Web Beans release from the
<ulink
url="http://seamframework.org/Download">download page</ulink>
on Seam Framework website. Web Beans includes a TCK runner that executes the TCK using the
RI by deploying the test artifacts to JBoss AS 5.</para>
+ <para>The JSR-299: Contexts and Dependency Injection for Java EE 1.0 reference
implementation (RI) is Web Beans. You can obtain the latest Web Beans release from the
<ulink
url="http://seamframework.org/Download">download page</ulink>
on Seam Framework website. Web Beans includes a TCK runner that executes the TCK on the
JSR-299 RI by deploying the test artifacts to JBoss AS 5.1.</para>
<note>
<para>The JSR-299 RI (Web Beans) is not required for running the JSR-299 TCK,
but it can be useful as a reference for familiarizing yourself with the TCK before testing
your own JSR-299 implementation.</para>
</note>
- <para>Executing the TCK requires a Java EE 5 or better runtime environment
(i.e., application server), to which the test artifacts are deployed. The TCK does not
depend on any particular implementation, only that it is compliant. However, if you
decide to use JBoss AS 5 as the target container, you can use the JBoss AS 5 connector
provided with the JBoss Test Harness, alleviating the requirement of implementing the
<literal>org.jboss.jsr299.tck.spi.Containers</literal> interface from the TCK
Porting Package. You can download JBoss AS 5 from the JBoss AS <ulink
url="http://jboss.org/jbossas/downloads">project
page</ulink>.</para>
+ <para>Executing the TCK requires a Java EE 5 or better runtime environment
(i.e., application server), to which the test artifacts are deployed and invoked. The TCK
does not depend on any particular Java EE implementation, only that it is compliant.
However, if you decide to use JBoss AS 5.1 as the target container, you can use the JBoss
AS 5.1 connector provided with the JBoss Test Harness, alleviating the requirement of
implementing the <literal>org.jboss.jsr299.tck.spi.Containers</literal> SPI
from the TCK porting package. You can download JBoss AS 5.1 from the JBoss AS <ulink
url="http://jboss.org/jbossas/downloads">project
page</ulink>.</para>
<para>Naturally, to execute Java programs, you must have a Java SE runtime
environment. The TCK requires Java SE 1.5 or better, which you can obtain from the
<ulink url="http://java.sun.com">Java Software</ulink>
website.</para>
</section>
<section>
@@ -23,7 +23,7 @@
<para>Java SE 5.0 or better</para>
</listitem>
<listitem>
- <para>Java EE 5 or better (e.g., JBoss AS 5 or GlassFish V3)</para>
+ <para>Java EE 5 or better (e.g., JBoss AS 5.x or GlassFish
V3)</para>
</listitem>
</itemizedlist>
<para>You can download Java SE from the <ulink
url="http://java.sun.com/products">Java Software</ulink>
@@ -31,9 +31,48 @@
Refer to the instructions that accompany
the software for how to install it on your system.
You should be sure that the <literal>JAVA_HOME</literal> environment variable
is assigned to the location of the Java SE software before you consider the installation
complete.</para>
- <para>Which Java EE runtime environment to use is your choice. Keep in mind,
though, that you must provide a custom connector if the application server you are using
is not supported by the JBoss Test Harness. At the time of writing, JBoss AS 5 is the only
supported application server. Hence, JBoss AS 5 is the recommend Java EE runtime
environment.</para>
- <para>JBoss AS 5 can be downloaded from the JBoss AS project page. Refer to the
instructions that accompany the software for how to install it on your system. Although
not required, it's recommended that you set the
<literal>JBOSS_HOME</literal> environment variable to the location of the
JBoss AS software.</para>
- <para>The remaining components required to setup and execute the TCK are merely
extracted. It's recommended that you first create a workspace directory named
"jsr299" to host the JSR-299 implementation and the TCK. Within that
directory you should extract the TCK software into a folder named
"tck".</para>
- <para>...</para>
+ <para>Which Java EE runtime environment to use is your choice. Keep in mind,
though, that you must provide a custom connector if the application server you are using
is not supported by the JBoss Test Harness. At the time of writing, JBoss AS 5.1 is the
only supported application server (table showing supported versions?) and is therefore the
recommend Java EE runtime environment.</para>
+ <para>JBoss AS 5.1 can be downloaded from the JBoss AS project page. Refer to
the instructions that accompany the software to learn how to install it on your system.
Although not required, it's recommended that you set the
<literal>JBOSS_HOME</literal> environment variable to the location of the
JBoss AS software.</para>
+ <para>The rest of the TCK software can simply be extracted. It's
recommended that you create a folder named jsr299 to hold all of the jsr299-related
projects. Then, extract the TCK distribution into a subfolder named tck. If you have
downloaded the Web Beans distribution, extract it into a sibling folder named webbeans.
The resulting folder structure is shown here:</para>
+ <programlisting>jsr299/
+ webbeans/
+ tck/</programlisting>
+ <para>This arrangement becomes important later on when executing tests in
Eclipse.</para>
+ <section>
+ <title>Web Beans deployer</title>
+ <para>When the TCK test suite is run (using in-container mode), it expects to
test the JSR-299 implementation provided by the application server. Therefore, you need to
install the JSR-299 implementation in the application server.</para>
+ <para>The JSR-299 RI (Web Beans) includes a JBoss AS integration project that
installs a special deployer on JBoss AS 5.x that activates the JSR-299 RI per application
when the application is deployed. The Web Beans deployer is installed in JBoss AS 5.x from
the jboss-as directory in the Web Beans distribution.</para>
+ <para>To install the web beans deployer, first make sure the
<literal>jboss.home</literal> property in the local.build.properties file in
the jboss-as directory references a JBoss AS 5.1 installation:</para>
+ <programlisting>jboss.home=/path/to/jboss-as-5.1</programlisting>
+ <para>Then, run Ant from the jboss-as directory to install the
deployer:</para>
+ <programlisting>ant update</programlisting>
+ <para>The libraries needed by the deployer are fetched from the Maven 2
repository on demand. The versions of the libraries fetched are defined in the
build.properties files in that directory.</para>
+ </section>
+ <section>
+ <title>Maven 2 and Maven 2 artifacts</title>
+ <para>As mentioned earlier, because the JSR-299 RI and TCK are built with
Maven 2, it's essential to have Maven 2 installed on the system. You can find
documention on how to install Maven 2 in the <ulink
url="http://www.sonatype.com/books/maven-book/reference/installation...:
The Definitive Guide</ulink> book published by Sonatype. It merely entails
extracting the distribution and putting the bin directory in the user's PATH
environment variable.</para>
+ <programlisting>export
PATH="<maven2_install_dir>/bin:$PATH"</programlisting>
+ <para>The TCK runner, introduced in section 4.2, is organized as a Maven 2
project (herein referred to as a Maven project). Therefore, it expects to retrieve all
dependent artifacts (JAR files) from the local Maven repository. If the artifact is
missing from the local repository, it will be fetched remotely from the JBoss Maven
repository and cached in the local repository.</para>
+ <para>One option for executing the TCK the first time is to allow Maven fetch
all required dependencies. If you want to use your own implementation of the TCK porting
package, or if you are running the TCK against your own JSR-299 implementation, you need
to install the cooresponding artifacts into your local Maven repository, at the very
least. If you don't want to use Maven at all, you'll need to implement a
project the executes the TCK runner from scratch. This guide assumes the use of the Maven
project structure.</para>
+ <para>If your JSR-299 implementation uses a Maven project structure, you can
have Maven install the artifact into your local Maven repository in the normal
way:</para>
+ <programlisting>mvn install</programlisting>
+ <para>If you are not using a Maven project structure, you can install each
artifact into your local Maven respository using the install goal:</para>
+ <programlisting>mvn install:install-file \
+-Dfile=jsr299-impl.jar \
+-DgroupId=com.company.jsr299 \
+-DartifactId=jsf299-impl \
+-Dversion=1.0 \
+-Dpackaging=jar</programlisting>
+ <para>You can use this command template for installing any JAR file you need
into your local Maven respository.</para>
+ <note>
+ <para>The JSR-299 implementation doesn't have to be on the
classpath of the TCK runner when executing the TCK in in-container mode. The JSR-299
implemention is expected to be provided by a compliant Java EE container. However, the
implementation does have to be on the classpath when executing the test suite in
standalone mode.</para>
+ </note>
+ </section>
+ <section>
+ <title>Eclipse plugins</title>
+ <para>Eclipse, or any other IDE, is not required to execute or pass the TCK.
However, executing and debugging tests in the IDE is essential for a licensee attempting
to get a JSR-299 implementation to pass the tests in the TCK test suite. This section
introduces two essential Eclipse plugins and points you to resources explaining how to
install them.</para>
+ <para>The TCK is built on the JBoss Test Harness, which is in turn executed
by TestNG. Therefore, having the TestNG plugin installed in Eclipse is essential.
Instructions for using the TestNG update site to add the TestNG plugin to Eclipse are
provided on the TestNG <ulink
url="http://testng.org/doc/download.html">download page</ulink>. You
can find a tutorial that explains how to use the TestNG plugin on the TestNG <ulink
url="http://testng.org/doc/eclipse.html">Eclipse
page</ulink>.</para>
+ <para>Another essential plugin is m2eclipse. Both the TCK project and the TCK
runner project (at least the one that ships with the JSR-299 RI) are built with Maven 2.
Therefore, to work with these projects in Eclipse, you need to have support for Maven 2
project, which the m2eclipse plugin provided. Instructions for using the m2eclipse update
site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page.
Sonatype, the company that maintains the m2eclipse plugin and is a strong supporter of
Maven, publishes an entire <ulink
url="http://www.sonatype.com/books/m2eclipse-book/reference">...
guide</ulink> dedicated to the plugin on their website.</para>
+ </section>
</section>
</chapter>
Modified: tck/trunk/doc/reference/en-US/introduction.xml
===================================================================
--- tck/trunk/doc/reference/en-US/introduction.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/introduction.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<chapter id="introduction">
<title>Introduction</title>
<para>This chapter explains the purpose of a TCK and identifies the foundation
elements of the JSR-299 TCK.</para>
@@ -7,7 +7,7 @@
<title>TCK Primer</title>
<para>A TCK, or Technology Compatibility Kit, is one of the three required
pieces for any JSR (the other two being the specification document and the reference
implementation). The TCK is a set of tools and tests to verify that a licensee's
implementation of the Sun technology conforms to the specification. The tests are the
primary component, but the tools serve an equally critical role of providing a framework
and/or set of SPIs for executing the tests.</para>
<para>The tests in the TCK are derived from assertions in the written
specification document. The assertions materialize as a suite of automated tests that
collectively validate whether an implementation complies with the aforementioned
assertions, and in turn the specification. For a particular implementation to be certified,
all of the required tests must pass (the provided test suite must be run
unmodified).</para>
- <para>A TCK is entirely implementation agnostic. Ideally, it should validate
assertions by consulting the specficiation's public API. However, when the
information returned by the public API is not low-level enough to validate the assertion,
the implementation must be consulted directly. In this case, the TCK provides an
independent API as part of a porting package which must also be implemented by the
licensee. Section 1.3.4 introduces the porting package and Section X.XX covers the
requirements for implementing it.</para>
+ <para>A TCK is entirely implementation agnostic. Ideally, it should validate
assertions by consulting the specficiation's public API. However, when the
information returned by the public API is not low-level enough to validate the assertion,
the implementation must be consulted directly. In this case, the TCK provides an
independent API as part of a porting package which must also be implemented by the
licensee. Section 1.3.4 introduces the porting package and section 4.1 covers the
requirements for implementing it.</para>
</section>
<section>
<title>Compatibility Testing</title>
@@ -57,7 +57,7 @@
<para>This section lists the applicable requirements and specifications for
the JSR-299 TCK.</para>
<itemizedlist>
<listitem>
- <para><emphasis role="bold">Specification
requirements</emphasis> - Software requirements for a JSR-299 implementation are
itermized in Section 1.2 of Chapter 1, "Relationship to other
specifications" in the JSR-299 specification, with details provided throughout
the specification.</para>
+ <para><emphasis role="bold">Specification
requirements</emphasis> - Software requirements for a JSR-299 implementation are
itemized in section 1.2, "Relationship to other specifications" in the
JSR-299 specification, with details provided throughout the specification.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Contexts and Dependency
Injection for Java EE 1.0 API</emphasis> - The Java API defined in the JSR-299
specification and provided by the reference implementation.</para>
@@ -77,6 +77,9 @@
See details at Java EE 5
(<ulink
url="http://java.sun.com/javaee/5/docs/api/">http://java.sun...
</listitem>
+ <listitem>
+ <para><emphasis role="bold">Maven 2</emphasis> -
Although licensees are free to execute the TCK however they decide, the recommended
approach is to use Maven 2. Both the JSR-299 RI and the TCK are build using Maven 2.
Furthermore, the TCK runner used to validate the RI, a resource which can be leveraged by
licensee to test their own implementations, is also Maven 2 project. Therefore,
it's highly recommended to have Maven 2 installed on the system.</para>
+ </listitem>
</itemizedlist>
</section>
<section>
@@ -97,7 +100,7 @@
automatic running of tests through the JBoss Test harness.</para>
</listitem>
<listitem>
- <para><emphasis role="bold">JBoss TCK
Runner</emphasis> - An implementation of hte JBoss Test Harness deployment APIs for
deploying artifacts to JBoss AS 5</para>
+ <para><emphasis role="bold">JBoss TCK
Runner</emphasis> - An implementation of hte JBoss Test Harness deployment APIs for
deploying artifacts to JBoss AS 5.1</para>
</listitem>
<listitem>
<para><emphasis role="bold">TCK
documentation</emphasis> accompanied by release notes identifying updates between
versions.</para>
@@ -113,7 +116,7 @@
<para> Java Platform, Enterprise Edition, Version 5 reference
implementation (Java EE 5 RI)</para>
</listitem>
<listitem>
- <para>JBoss AS 5?</para>
+ <para>JBoss AS 5.1?</para>
</listitem>
</itemizedlist>
<para>The JSR-299 TCK tests run on the following platforms:</para>
@@ -176,8 +179,8 @@
</section>
<section>
<title>The Porting Package</title>
- <para>The JSR-299 TCK relies on an implemnetation of the Porting Package to
function. The Porting Package can be divided into two parts. The first part is comprised
of extensions to the JSR-299 SPIs to allow testing of a container. The second part must
contain implementations of the JBoss Test Harness deployment APIs for deploying test
artifacts to a given container.</para>
- <para>As mentioned earlier, there are times when the tests need to tap
directly into the JSR-299 implementation to manipulate behavior or verify results. The
Porting Package includes a set of SPIs that provide the TCK this level of access without
tying the tests to a given implementation.</para>
+ <para>The JSR-299 TCK relies on an implemnetation of the porting package to
function. The porting package can be divided into two parts. The first part is comprised
of extensions to the JSR-299 SPIs to allow testing of a container. The second part must
contain implementations of the JBoss Test Harness deployment APIs for deploying test
artifacts to a given container.</para>
+ <para>As mentioned earlier, there are times when the tests need to tap
directly into the JSR-299 implementation to manipulate behavior or verify results. The
porting package includes a set of SPIs that provide the TCK this level of access without
tying the tests to a given implementation.</para>
<para>The four SPI classes in the JSR-299 TCK are as follows:</para>
<itemizedlist>
<listitem>
@@ -193,8 +196,8 @@
<para><literal>org.jboss.jsr299.tck.spi.Managers</literal></para>
</listitem>
</itemizedlist>
- <para>To run the full TCK you must additionally implement
<literal>org.jboss.testharness.spi.Containers</literal>, which handles
deploying the test artifact to the container. If you wish to run the TCK in standalone
mode, you must also implement
<literal>org.jboss.testharness.spi.StandaloneContainers</literal>.
Implementations of these APIs are already available for JBoss AS 5. Therefore, you only
need to implement this part of the Porting Package if you wish to use a container other
than JBoss AS 5, for instance GlassFish V3.</para>
- <para>The default configuration for the TCK is property-based. Therefore, you
specify the implementation class for all of these SPIs in a properties file. There are
additional properties for controlling whether the tests are run in standalone or
in-container mode. Optionally, you can use system properties to configure the TCK. Details
are provided in Section X.XX.</para>
+ <para>To run the full TCK you must additionally implement
<literal>org.jboss.testharness.spi.Containers</literal>, which handles
deploying the test artifact to the container. If you wish to run the TCK in standalone
mode, you must also implement
<literal>org.jboss.testharness.spi.StandaloneContainers</literal>.
Implementations of these APIs are already available for JBoss AS 5.1. Therefore, you only
need to implement this part of the porting package if you wish to use a container other
than JBoss AS 5.1, for instance GlassFish V3.</para>
+ <para>The default configuration for the TCK is property-based. Therefore, you
specify the implementation class for all of these SPIs in a properties file. There are
additional properties for controlling whether the tests are run in standalone or
in-container mode. Optionally, you can use system properties to configure the TCK. Details
are provided in section 4.1.</para>
</section>
<section>
<title>TCK Audit Tool</title>
Modified: tck/trunk/doc/reference/en-US/part1-background.xml
===================================================================
--- tck/trunk/doc/reference/en-US/part1-background.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/part1-background.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<part>
<title>Getting Acquainted with the TCK</title>
<partintro>
Modified: tck/trunk/doc/reference/en-US/part2-setup.xml
===================================================================
--- tck/trunk/doc/reference/en-US/part2-setup.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/part2-setup.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,5 +1,5 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<part>
<title>Installation and Setup</title>
<partintro>
Modified: tck/trunk/doc/reference/en-US/part3-execution.xml
===================================================================
--- tck/trunk/doc/reference/en-US/part3-execution.xml 2009-07-14 18:32:29 UTC (rev 3051)
+++ tck/trunk/doc/reference/en-US/part3-execution.xml 2009-07-15 04:20:28 UTC (rev 3052)
@@ -1,9 +1,11 @@
<?xml version='1.0' encoding='UTF-8'?>
-<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
+<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]>
<part>
<title>Executing and Debugging Tests</title>
<partintro>
- <para>In this part you learn how to execute the JSR-299 TCK. First, you are
taken through the steps necessary to execute the test suite against the JSR-299 RI (Web
Beans). Then you discover how to modify the TCK runner to execute the test suite against
your own implementation. Finally, you learn how to debug individual tests in the test
suite.</para>
+ <para>In this part you learn how to execute the JSR-299 TCK on a given JSR-299
implementation. First, you are walked through the steps necessary to execute the test
suite on the JSR-299 RI (Web Beans). Then you discover how to modify the TCK runner to
execute the test suite on your own implementation. Finally, you learn how to debug tests
from the test suite in Eclipse.</para>
</partintro>
<xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="executing.xml"/>
+ <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="eclipse-running.xml"/>
+ <xi:include
xmlns:xi="http://www.w3.org/2001/XInclude"
href="eclipse-debugging.xml"/>
</part>