[webbeans-commits] Webbeans SVN: r3052 - in tck/trunk/doc/reference/en-US: images and 1 other directory.
webbeans-commits at lists.jboss.org
webbeans-commits at lists.jboss.org
Wed Jul 15 00:20:31 EDT 2009
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">JBoss 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-application-using-eclipse">this 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>@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>@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">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-sect-maven-install.html">Maven: 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">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.com/javaee/5/docs/api/</ulink>).</para>
</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>
More information about the weld-commits
mailing list