[webbeans-commits] Webbeans SVN: r3197 - tck/trunk/doc/reference/en-US.

Author: pete.muir(a)jboss.org Date: 2009-07-24 11:16:31 -0400 (Fri, 24 Jul 2009) New Revision: 3197 Modified: tck/trunk/doc/reference/en-US/configuration.xml Log: ws Modified: tck/trunk/doc/reference/en-US/configuration.xml =================================================================== --- tck/trunk/doc/reference/en-US/configuration.xml 2009-07-24 14:42:19 UTC (rev 3196) +++ tck/trunk/doc/reference/en-US/configuration.xml 2009-07-24 15:16:31 UTC (rev 3197) @@ -1,306 +1,596 @@ <?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="configuration"> - <title>Configuration</title> - <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 3.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"> - <colspec colnum="1" colname="property" colwidth="5*"/> - <colspec colnum="2" colname="description" colwidth="2*"/> - <thead> - <row> - <entry>Property = Default Value</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <literal>org.jboss.testharness.api.ConfigurationBuilder=</literal> - <literal>o.j.t.impl.PropertiesBasedConfigurationBuilder</literal> - </entry> - <entry>The configuration bootstrap class for the JBoss Test Harness.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.testPackage=</literal> - </entry> - <entry>The top-level Java package containing the classes to be tested.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.libraryDirectory=</literal> - </entry> - <entry>Directory containing extra JARs.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.standalone=true</literal> - </entry> - <entry>Tests are run using standalone mode if true or using in-container mode if false.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.runIntegrationTests=false</literal> - </entry> - <entry>If true, integration tests are run. In-container mode must be activated.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.spi.Containers=</literal> - </entry> - <entry>The container implementation for deploying and executing in-container tests.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.host=localhost:8080</literal> - </entry> - <entry>The host and port on which the container is running.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.connectDelay=5000</literal> - </entry> - <entry>The timeout (ms) when attempting to connect to the container.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.connectRetries=2</literal> - </entry> - <entry>The number of connection retries used when connecting the the container.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.api.TestLauncher=</literal> - </entry> - <entry>The in-container test launcher.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.container.\</literal> - <literal>deploymentExceptionTransformer=</literal> - </entry> - <entry>A class which maps deployment exceptions to expected exceptions declared in test case. Returns original exception by default.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.container.forceRestart=false</literal> - </entry> - <entry>Whether the container should be restarted before the tests are executed.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.container.extraConfigurationDir=</literal> - </entry> - <entry>A directory containing a build.properties or local.build.properties files that define additional properties.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.spi.StandaloneContainers=</literal> - </entry> - <entry>The container implementation for executing standalone tests.</entry> - </row> - <row> - <entry> - <literal>dumpArtifacts=false</literal> - </entry> - <entry>Whether the test artifacts should be written to disk for inspection.</entry> - </row> - <row> - <entry> - <literal>org.jboss.testharness.outputDirectory=</literal> - <literal>%java.io.tmpdir%/jsr-299-tck/</literal> - </entry> - <entry>Directory where test artifacts will be written to disk, if <literal>dumpArtifacts</literal> is true.</entry> - </row> - </tbody> - </tgroup> - </table> - <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 3.2.</para> - <table frame="all"> - <title/> - <tgroup cols="2"> - <colspec colname="property"/> - <colspec colname="description"/> - <thead> - <row> - <entry>Property</entry> - <entry>Description</entry> - </row> - </thead> - <tbody> - <row> - <entry> - <literal>org.jboss.jsr299.tck.spi.Managers</literal> - </entry> - <entry>Operations pertaining to the BeanManager.</entry> - </row> - <row> - <entry> - <literal>org.jboss.jsr299.tck.spi.Beans</literal> - </entry> - <entry>Operations pertaining to bean types.</entry> - </row> - <row> - <entry> - <literal>org.jboss.jsr299.tck.spi.Contexts</literal> - </entry> - <entry>Operations pertaining to Java EE contexts.</entry> - </row> - <row> - <entry> - <literal>org.jboss.jsr299.tck.spi.EL</literal> - </entry> - <entry>Operations pertaining to the Unified EL.</entry> - </row> - </tbody> - </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&apos;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 \ + <title>Configuration</title> + <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 + <code>META-INF/jboss-test-harness.properties</code> + , 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 3.1, for the fully qualified class + name (FQCN) of a concrete 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"> + <colspec colnum="1" colname="property" colwidth="5*" /> + <colspec colnum="2" colname="description" colwidth="2*" /> + <thead> + <row> + <entry>Property = Default Value</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>org.jboss.testharness.api.ConfigurationBuilder= + </literal> + <literal>o.j.t.impl.PropertiesBasedConfigurationBuilder + </literal> + </entry> + <entry> + The configuration bootstrap class for the JBoss Test + Harness. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.testPackage=</literal> + </entry> + <entry> + The top-level Java package containing the classes to be + tested. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.libraryDirectory=</literal> + </entry> + <entry> + Directory containing extra JARs. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.standalone=true</literal> + </entry> + <entry> + Tests are run using standalone mode if true or using + in-container mode if false. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.runIntegrationTests=false + </literal> + </entry> + <entry> + If true, integration tests are run. In-container mode + must be activated. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.spi.Containers=</literal> + </entry> + <entry> + The container implementation for deploying and + executing in-container tests. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.host=localhost:8080 + </literal> + </entry> + <entry> + The host and port on which the container is running. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.connectDelay=5000</literal> + </entry> + <entry> + The timeout (ms) when attempting to connect to the + container. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.connectRetries=2</literal> + </entry> + <entry> + The number of connection retries used when connecting + the the container. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.api.TestLauncher=</literal> + </entry> + <entry> + The in-container test launcher. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.container.\</literal> + <literal>deploymentExceptionTransformer=</literal> + </entry> + <entry> + A class which maps deployment exceptions to expected + exceptions declared in test case. Returns original + exception by default. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.container.forceRestart=false + </literal> + </entry> + <entry> + Whether the container should be restarted before the + tests are executed. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.container.extraConfigurationDir= + </literal> + </entry> + <entry> + A directory containing a build.properties or + local.build.properties files that define additional + properties. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.spi.StandaloneContainers= + </literal> + </entry> + <entry> + The container implementation for executing standalone + tests. + </entry> + </row> + <row> + <entry> + <literal>dumpArtifacts=false</literal> + </entry> + <entry> + Whether the test artifacts should be written to disk + for inspection. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.testharness.outputDirectory=</literal> + <literal>%java.io.tmpdir%/jsr-299-tck/</literal> + </entry> + <entry> + Directory where test artifacts will be written to disk, if + <literal>dumpArtifacts</literal> + is true. + </entry> + </row> + </tbody> + </tgroup> + </table> + <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 3.2. + </para> + <table frame="all"> + <title /> + <tgroup cols="2"> + <colspec colname="property" /> + <colspec colname="description" /> + <thead> + <row> + <entry>Property</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry> + <literal>org.jboss.jsr299.tck.spi.Managers</literal> + </entry> + <entry> + Operations pertaining to the BeanManager. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.jsr299.tck.spi.Beans</literal> + </entry> + <entry> + Operations pertaining to bean types. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.jsr299.tck.spi.Contexts</literal> + </entry> + <entry> + Operations pertaining to Java EE contexts. + </entry> + </row> + <row> + <entry> + <literal>org.jboss.jsr299.tck.spi.EL</literal> + </entry> + <entry> + Operations pertaining to the Unified EL. + </entry> + </row> + </tbody> + </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&apos;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&apos;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&apos;s not declared as a regular Maven dependency. That&apos;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>&lt;plugin&gt; - &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt; - &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt; - &lt;executions&gt; - &lt;execution&gt; - &lt;id&gt;copy&lt;/id&gt; - &lt;phase&gt;process-resources&lt;/phase&gt; - &lt;goals&gt; - &lt;goal&gt;copy&lt;/goal&gt; - &lt;/goals&gt; - &lt;configuration&gt; - &lt;stripVersion&gt;true&lt;/stripVersion&gt; - &lt;artifactItems&gt; - &lt;artifactItem&gt; - &lt;groupId&gt;org.jboss.jsr299.tck&lt;/groupId&gt; - &lt;artifactId&gt;jsr299-tck-impl&lt;/artifactId&gt; - &lt;type&gt;xml&lt;/type&gt; - &lt;classifier&gt;suite&lt;/classifier&gt; - &lt;overWrite&gt;true&lt;/overWrite&gt; - &lt;/artifactItem&gt; - &lt;artifactItem&gt; - &lt;groupId&gt;org.jboss.webbeans&lt;/groupId&gt; - &lt;artifactId&gt; + <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&apos;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&apos;s not declared as a regular Maven + dependency. That&apos;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><![CDATA[<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 - &lt;/artifactId&gt; - &lt;overWrite&gt;true&lt;/overWrite&gt; - &lt;outputDirectory&gt; + </artifactId> + <overWrite>true</overWrite> + <outputDirectory> ${project.build.directory}/dependency/lib - &lt;/outputDirectory&gt; - &lt;/artifactItem&gt; - &lt;artifactItem&gt; - &lt;groupId&gt;org.jboss.webbeans&lt;/groupId&gt; - &lt;artifactId&gt;webbeans-core-test&lt;/artifactId&gt; - &lt;overWrite&gt;true&lt;/overWrite&gt; - &lt;outputDirectory&gt; + </outputDirectory> + </artifactItem> + <artifactItem> + <groupId>org.jboss.webbeans</groupId> + <artifactId>webbeans-core-test</artifactId> + <overWrite>true</overWrite> + <outputDirectory> ${project.build.directory}/dependency/lib - &lt;/outputDirectory&gt; - &lt;/artifactItem&gt; - &lt;artifactItem&gt; - &lt;groupId&gt;javax.el&lt;/groupId&gt; - &lt;artifactId&gt;el-ri&lt;/artifactId&gt; - &lt;overWrite&gt;true&lt;/overWrite&gt; - &lt;outputDirectory&gt; + </outputDirectory> + </artifactItem> + <artifactItem> + <groupId>javax.el</groupId> + <artifactId>el-ri</artifactId> + <overWrite>true</overWrite> + <outputDirectory> ${project.build.directory}/dependency/lib - &lt;/outputDirectory&gt; - &lt;/artifactItem&gt; - &lt;/artifactItems&gt; - &lt;/configuration&gt; - &lt;/execution&gt; - &lt;/executions&gt; -&lt;/plugin&gt;</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 declares 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&apos;s how the default implementation 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 query 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&apos;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&apos;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> + </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 declares + 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&apos;s how the default implementation 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 query 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&apos;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&apos;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>