Author: jharting Date: 2009-07-23 04:55:04 -0400 (Thu, 23 Jul 2009) New Revision: 3148 Modified: 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 Log: Fixed mistakes in reference documentation Modified: tck/trunk/doc/reference/en-US/configuration.xml =================================================================== --- tck/trunk/doc/reference/en-US/configuration.xml 2009-07-22 23:35:57 UTC (rev 3147) +++ tck/trunk/doc/reference/en-US/configuration.xml 2009-07-23 08:55:04 UTC (rev 3148) @@ -6,7 +6,7 @@ <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 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>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"> @@ -123,7 +123,7 @@ </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 2.1.2.</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 3.2.</para> <table frame="all"> <title/> <tgroup cols="2"> @@ -288,14 +288,14 @@ <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> + <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 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>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> Modified: tck/trunk/doc/reference/en-US/executing.xml =================================================================== --- tck/trunk/doc/reference/en-US/executing.xml 2009-07-22 23:35:57 UTC (rev 3147) +++ tck/trunk/doc/reference/en-US/executing.xml 2009-07-23 08:55:04 UTC (rev 3148) @@ -51,7 +51,7 @@ <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> + <para>Once the artifact is written to disk, you have an 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> Modified: tck/trunk/doc/reference/en-US/installation.xml =================================================================== --- tck/trunk/doc/reference/en-US/installation.xml 2009-07-22 23:35:57 UTC (rev 3147) +++ tck/trunk/doc/reference/en-US/installation.xml 2009-07-23 08:55:04 UTC (rev 3148) @@ -53,7 +53,7 @@ <para>As mentioned earlier, because the JSR-299 RI and TCK are built with Maven 2, it&apos;s essential to have Maven 2 installed on the system. You can find documention on how to install Maven 2 in the <ulink url="http://www.sonatype.com/books/maven-book/reference/installation...: The Definitive Guide</ulink> book published by Sonatype. It merely entails extracting the distribution and putting the bin directory in the user&apos;s PATH environment variable.</para> <programlisting>export PATH=&quot;&lt;maven2_install_dir&gt;/bin:$PATH&quot;</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&apos;t want to use Maven at all, you&apos;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>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 corresponding artifacts into your local Maven repository, at the very least. If you don&apos;t want to use Maven at all, you&apos;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> @@ -72,7 +72,7 @@ <title>Eclipse plugins</title> <para>Eclipse, or any other IDE, is not required to execute or pass the TCK. However, executing and debugging tests in the IDE is essential for a licensee attempting to get a JSR-299 implementation to pass the tests in the TCK test suite. This section introduces two essential Eclipse plugins and points you to resources explaining how to install them.</para> <para>The TCK is built on the JBoss Test Harness, which is in turn executed by TestNG. Therefore, having the TestNG plugin installed in Eclipse is essential. Instructions for using the TestNG update site to add the TestNG plugin to Eclipse are provided on the TestNG <ulink url="http://testng.org/doc/download.html">download page</ulink>. You can find a tutorial that explains how to use the TestNG plugin on the TestNG <ulink url="http://testng.org/doc/eclipse.html">Eclipse page</ulink>.</para> - <para>Another essential plugin is m2eclipse. Both the TCK project and the TCK runner project (at least the one that ships with the JSR-299 RI) are built with Maven 2. Therefore, to work with these projects in Eclipse, you need to have support for Maven 2 project, which the m2eclipse plugin provided. Instructions for using the m2eclipse update site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page. Sonatype, the company that maintains the m2eclipse plugin and is a strong supporter of Maven, publishes an entire <ulink url="http://www.sonatype.com/books/m2eclipse-book/reference">... guide</ulink> dedicated to the plugin on their website.</para> + <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 provides. Instructions for using the m2eclipse update site to add the m2eclipse plugin to Eclipse are provided on the m2eclipse home page. Sonatype, the company that maintains the m2eclipse plugin and is a strong supporter of Maven, publishes an entire <ulink url="http://www.sonatype.com/books/m2eclipse-book/reference">... guide</ulink> dedicated to the plugin on their website.</para> </section> </section> </chapter> Modified: tck/trunk/doc/reference/en-US/introduction.xml =================================================================== --- tck/trunk/doc/reference/en-US/introduction.xml 2009-07-22 23:35:57 UTC (rev 3147) +++ tck/trunk/doc/reference/en-US/introduction.xml 2009-07-23 08:55:04 UTC (rev 3148) @@ -12,8 +12,8 @@ <section> <title>Compatibility Testing</title> <para>The goal of any specification is to eliminate portability problems so long as the program which uses the implementation also conforms to the rules laid out in the specification.</para> - <para>Executing the TCK is a form of compatibility testing. It&apos;s important to understand that compatibility testing is distinctly different from product testing. The TCK is not concerned with robustness, performance or ease of use, and therefore cannot vouch for how well an implementation meets these criteria. What a TCK can do is ensure the exactness of an implementation as it relates to the specification.</para> - <para>Compatibility testing of any feature relies on both a complete specification and a complete reference implementation. The reference implementation demonstrates how each test can be passed and provides additional context to the licensee during development for the cooresponding assertion.</para> + <para>Executing the TCK is a form of compatibility testing. It&apos;s important to understand that compatibility testing is distinctly different from product testing. The TCK is not concerned with robustness, performance or ease of use, and therefore cannot vouch for how well an implementation meets these criteria. What a TCK can do is to ensure the exactness of an implementation as it relates to the specification.</para> + <para>Compatibility testing of any feature relies on both a complete specification and a complete reference implementation. The reference implementation demonstrates how each test can be passed and provides additional context to the licensee during development for the corresponding assertion.</para> <section> <title>Why Compatibility Is Important</title> <para>Java platform compatibility is important to different groups involved with Java technologies for @@ -40,7 +40,7 @@ </para> </listitem> </itemizedlist> - <para>The JSR-299 specification goes to great lengths to ensure that programs written for Java EE are compatible and the TCK is rigourous about enforcing the rules the specification lays down.</para> + <para>The JSR-299 specification goes to great lengths to ensure that programs written for Java EE are compatible and the TCK is rigorous about enforcing the rules the specification lays down.</para> </section> </section> <section> @@ -100,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.1</para> + <para><emphasis role="bold">JBoss TCK Runner</emphasis> - An implementation of the 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> @@ -136,7 +136,7 @@ <note> <para>You&apos;ll often see the term <emphasis role="italic">in-container</emphasis> used in this reference guide. This term refers to running the test suite in any of the aforementioned environments, whilst <emphasis role="italic">standalone</emphasis> refers to running the tests outside the container via a JSR-299 implementation-specific standalone bootstrap. The standalone mode only runs those tests which don&apos;t require EJB, Servlet or JSF to be present.</para> </note> - <para>The last thing Java developers want is yet another testing framework to make their life more complicated. What they do want is good integration with the their Integrated Development Environment (IDE). These days, if a tool doesn&apos;t have an IDE plugin, then it won&apos;t get the attention it deserves. That&apos;s why the JBoss Test Harness is built entirely TestNG. TestNG is one of the two prominent test frameworks for Java and TestNG plugins are available for all major IDEs (with the exception of NetBeans) and build tools (Ant and Maven 2).</para> + <para>The last thing Java developers want is yet another testing framework to make their life more complicated. What they do want is a good integration with their Integrated Development Environment (IDE). These days, if a tool doesn&apos;t have an IDE plugin, then it won&apos;t get the attention it deserves. That&apos;s why the JBoss Test Harness is built entirely upon TestNG. TestNG is one of the two prominent test frameworks for Java and TestNG plugins are available for all major IDEs (with the exception of NetBeans) and build tools (Ant and Maven 2).</para> <para>Because it leverages the existing TestNG ecosystem, there is no need for a special test launcher for the JBoss Test Harness, and in turn the JSR-299 TCK. You simply use the IDE or build tool of your choice. You also get reporting and debugging for free.</para> <para>The JBoss Test Harness supports the following features:</para> <itemizedlist> @@ -175,11 +175,11 @@ <para>The <literal>@Test</literal> annotation is provided by TestNG, the <literal>@Artifact</literal> annotation is provided by the JBoss Test Harness and the <literal>AbstractJSR299Test</literal> is part of the JSR-299 TCK. There is a one-to-one mapping between a TestNG test class and an artifact. The packaging type is defined by the <literal&gt;(a)org.jboss.testharness.impl.packaging.Packaging&lt;/literal&gt; annotation on the test class, defaulting to a WAR if not specified.</para> <para>Prior to executing the tests for a given class, the JBoss Test Harness packages the class as a deployable artifact (EAR or WAR), along with any extra resources specified, and deploys the artifact to the container. The test execution and results are negotatied via HTTP communication using a thin layer over the TestNG test launcher. The test harness can also catch and affirm expected deployment exceptions. This setup and tear down activity is provided by the super class <literal>org.jboss.jsr299.tck.AbstractJSR299Test</literal>, which all TCK test classes must extend.</para> <para>If the annotation <literal&gt;(a)org.jboss.testharness.impl.packaging.IntegrationTest&lt;/literal&gt; is not present on the test class, then it means the test class can be executed in standalone mode. In standalone mode, the deployable artifact is assembled on the local classpath and the tests execute in the same JVM as the launcher, just as though it were a regular TestNG test case. The standalone mode is provided merely for convenience and efficiency.</para> - <para>Chapter X details how to run the TCK test suite using the JBoss Test Harness.</para> + <para>Chapter 4 details how to run the TCK test suite using the JBoss Test Harness.</para> </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>The JSR-299 TCK relies on an implementation 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>