From webbeans-commits at lists.jboss.org Thu Jul 23 11:46:19 2009 Content-Type: multipart/mixed; boundary="===============7835543446893158032==" MIME-Version: 1.0 From: webbeans-commits at lists.jboss.org To: weld-commits at lists.jboss.org Subject: [webbeans-commits] Webbeans SVN: r3148 - tck/trunk/doc/reference/en-US. Date: Thu, 23 Jul 2009 04:55:04 -0400 Message-ID: <200907230855.n6N8t4IR027184@svn01.web.mwc.hst.phx2.redhat.com> --===============7835543446893158032== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@
JBoss Test Harness Properties 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 mu= st be configured by specifying implementations of the test launcher and con= tainer APIs. All the required configuration that pertains to the JBoss Test= Harness is applicable to the TCK as well. - System properties and/or the resource META-INF/jboss-test-harnes= s.properties, a Java properties file, are used to configure the JBoss Test = Harness. The bootstrap configuration builder looks to the property org.jboss.testharness.api.ConfigurationBuilder, the first proper= ty listed in table 2.1.1, for the fully qualified class name (FQCN) of a c= oncreate configuration builder implementation to get started. This implemen= tation loads the remaining configuration settings and produces a JBoss Test= Harness configuration. + System properties and/or the resource META-INF/jboss-test-harnes= s.properties, a Java properties file, are used to configure the JBoss Test = Harness. The bootstrap configuration builder looks to the property org.jboss.testharness.api.ConfigurationBuilder, the first proper= ty listed in table 3.1, for the fully qualified class name (FQCN) of a con= create configuration builder implementation to get started. This implementa= tion loads the remaining configuration settings and produces a JBoss Test H= arness configuration. For you convenience, the default configuration builder implement= ation org.jboss.testharness.impl.PropertiesBasedConfigurationBuild= er is provided, which collects all the JBoss Test Harness configu= ration 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, a= llowing you to partition the configuration settings as needed. A complete list of configuration properties for the JBoss Test H= arness has been itemized in table 2.1.1, accompanied by the default value (= if any) and a description for each property. @@ -123,7 +123,7 @@
- The TCK also relies on implementations of the interfaces in the = porting package. These implementations are also specified using system prop= erties or the classpath resource META-INF/jboss-test-harness.properties. Th= e implementation of each porting package SPI must be specified using the fu= lly-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. + The TCK also relies on implementations of the interfaces in the = porting package. These implementations are also specified using system prop= erties or the classpath resource META-INF/jboss-test-harness.properties. Th= e implementation of each porting package SPI must be specified using the fu= lly-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. <tgroup cols=3D"2"> @@ -288,14 +288,14 @@ <para>The TCK is executed using the Maven TestNG plugin. Maven 2 profi= les are used to control the properties that are set at the time of the exec= ution. For instance, the <literal>incontainer</literal> profile enables int= egration 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= =3D../jboss-as</programlisting> - <para>The JBoss Test Harness looks in this directory for either a buil= d.properties or local.build.properties file that declare additional configu= ration properties. In particular, the JBoss AS Containers implementation lo= oks here to find the <literal>jboss.home</literal> property for starting an= d stopping JBoss AS.</para> + <para>The JBoss Test Harness looks in this directory for either a buil= d.properties or local.build.properties file that declares additional config= uration properties. In particular, the JBoss AS Containers implementation l= ooks here to find the <literal>jboss.home</literal> property for starting a= nd stopping JBoss AS.</para> </section> <section> <title>Negotiating the execution of an in-container testThe basic procedure of an in-container test is as follows. The J= Boss Test Harness produces a deployable artifact from an @Artifact= test class and any declared dependent classes, descriptors or ot= her resources. Then it deploys the artifact to the container using the Containers SPI, negotiates with the container to execute the= test and return the result and, lastly, undeploys the artifact. TestNG col= lects the results of all the tests run in the typical way and produces a re= port. - The question is, how does the JBoss Test Harness negotiate with = the container to execute the test when TestNG is being invoked locally? Tec= hnially the mechanism is pluggable, but JBoss Test Harness provides a defau= lt implementation that uses HTTP communication that you will likely use. He= re's how the default implementation works works. - The artifact generator bundles and registers (in the web.xml des= criptor) an HttpServlet, org.jboss.testharness.= impl.runner.servlet.ServletTestRunner, that responds to test exec= ution GET requests. TestNG running on the client side delegates to a test l= auncher (more on that in a moment) which originates these text execution re= quests to transfer control to the container JVM. The name of the test metho= d to be executed is specified in a request parameter named methodN= ame. + The question is, how does the JBoss Test Harness negotiate with = the container to execute the test when TestNG is being invoked locally? Tec= hnially the mechanism is pluggable, but JBoss Test Harness provides a defau= lt implementation that uses HTTP communication that you will likely use. He= re's how the default implementation works. + The artifact generator bundles and registers (in the web.xml des= criptor) an HttpServlet, org.jboss.testharness.= impl.runner.servlet.ServletTestRunner, that responds to test exec= ution GET requests. TestNG running on the client side delegates to a test l= auncher (more on that in a moment) which originates these text execution re= quests to transfer control to the container JVM. The name of the test metho= d to be executed is specified in a request query parameter named m= ethodName. When the test execution request is received, the servlet delegat= es to an instance of org.jboss.testharness.impl.runner.TestRunner<= /literal>, passing it the name of the test method. TestRunner reads the name of the test class from the resource META-INF/jboss-tes= t-harness.properties, which is bundled in the artifact by the artifact gene= rator. It then combines the class name with the method name to produce a Te= stNG test suite and runs the suite (in the context of the container). TestNG returns the results of the run as an ITestResult= object. ServletTestRunner translates this obj= ect into a org.jboss.testharness.api.TestResult and pass= es it back to the test launcher on the client side by encoding the translat= ed object into the response. The object gets encoded as either html or a se= rialized object, depending on the value of the outputMode request parameter that was passed to the servlet. Once the result has bee= n transfered to the client-side TestNG, TestNG wraps up the run of the test= as though it had been executed in the same JVM. There's one piece missing. How does TestNG on the client si= de know to submit a request to the ServletTestRunner ser= vlet to get TestNG to execute the test in the container JVM? That's th= e role of the test launcher. Modified: tck/trunk/doc/reference/en-US/executing.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- tck/trunk/doc/reference/en-US/executing.xml 2009-07-22 23:35:57 UTC (re= v 3147) +++ tck/trunk/doc/reference/en-US/executing.xml 2009-07-23 08:55:04 UTC (re= v 3148) @@ -51,7 +51,7 @@ If you only want to write the artifacts to disk, and avoid execu= ting the test suite, you can simply execute the main method of the class <= literal>org.jboss.testharness.api.TCK. This execution is configur= ed as a Maven profile that is activated when the dumpArtifacts command line property is defined: mvn test-compile -DdumpArtifacts The output directory where the artifacts are written is defined = by the property org.jboss.testharness.outputDirectory. T= he jboss-tck-runner project is configured to dump the artifacts to the targ= et/jsr299-artifacts directory. - Once the artifact is written to disk, you have to option of manu= ally deploying it to the container. You can execute the tests in the artfac= t 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 request parameter (e.g., ?methodName=3DtestMet= hodName). + Once the artifact is written to disk, you have an option of manu= ally deploying it to the container. You can execute the tests in the artfac= t 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 request parameter (e.g., ?methodName=3DtestMet= hodName).
Running a Test in Eclipse Modified: tck/trunk/doc/reference/en-US/installation.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@ 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 Maven: The Definitive Guide book published by Sonatype.= It merely entails extracting the distribution and putting the bin director= y in the user's PATH environment variable. export PATH=3D"<maven2_install_dir>/bin:$= PATH" The TCK runner, introduced in section 4.2, is organized as a M= aven 2 project (herein referred to as a Maven project). Therefore, it expec= ts to retrieve all dependent artifacts (JAR files) from the local Maven rep= ository. If the artifact is missing from the local repository, it will be f= etched remotely from the JBoss Maven repository and cached in the local rep= ository. - One option for executing the TCK the first time is to allow Ma= ven fetch all required dependencies. If you want to use your own implementa= tion of the TCK porting package, or if you are running the TCK against your= own JSR-299 implementation, you need to install the cooresponding artifact= s into your local Maven repository, at the very least. If you don't wa= nt to use Maven at all, you'll need to implement a project the execute= s the TCK runner from scratch. This guide assumes the use of the Maven proj= ect structure. + One option for executing the TCK the first time is to allow Ma= ven fetch all required dependencies. If you want to use your own implementa= tion of the TCK porting package, or if you are running the TCK against your= own JSR-299 implementation, you need to install the corresponding artifact= s into your local Maven repository, at the very least. If you don't wa= nt to use Maven at all, you'll need to implement a project the execute= s the TCK runner from scratch. This guide assumes the use of the Maven proj= ect structure. If your JSR-299 implementation uses a Maven project structure,= you can have Maven install the artifact into your local Maven repository i= n the normal way: mvn install If you are not using a Maven project structure, you can instal= l each artifact into your local Maven respository using the install goal: @@ -72,7 +72,7 @@ Eclipse plugins 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. The TCK is built on the JBoss Test Harness, which is in turn e= xecuted by TestNG. Therefore, having the TestNG plugin installed in Eclipse= is essential. Instructions for using the TestNG update site to add the Tes= tNG plugin to Eclipse are provided on the TestNG download page. You can find a tutorial tha= t explains how to use the TestNG plugin on the TestNG Eclipse page. - Another essential plugin is m2eclipse. Both the TCK project an= d 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 pr= ovided. Instructions for using the m2eclipse update site to add the m2eclip= se plugin to Eclipse are provided on the m2eclipse home page. Sonatype, the= company that maintains the m2eclipse plugin and is a strong supporter of M= aven, publishes an entire reference guide dedicated to the plugin on the= ir website. + Another essential plugin is m2eclipse. Both the TCK project an= d 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 pr= ovides. Instructions for using the m2eclipse update site to add the m2eclip= se plugin to Eclipse are provided on the m2eclipse home page. Sonatype, the= company that maintains the m2eclipse plugin and is a strong supporter of M= aven, publishes an entire reference guide dedicated to the plugin on the= ir website.
Modified: tck/trunk/doc/reference/en-US/introduction.xml =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D --- 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 @@
Compatibility Testing The goal of any specification is to eliminate portability proble= ms so long as the program which uses the implementation also conforms to th= e rules laid out in the specification. - Executing the TCK is a form of compatibility testing. It's= important to understand that compatibility testing is distinctly different= from product testing. The TCK is not concerned with robustness, performanc= e 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 impl= ementation as it relates to the specification. - Compatibility testing of any feature relies on both a complete s= pecification and a complete reference implementation. The reference impleme= ntation demonstrates how each test can be passed and provides additional co= ntext to the licensee during development for the cooresponding assertion. + Executing the TCK is a form of compatibility testing. It's= important to understand that compatibility testing is distinctly different= from product testing. The TCK is not concerned with robustness, performanc= e 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 i= mplementation as it relates to the specification. + Compatibility testing of any feature relies on both a complete s= pecification and a complete reference implementation. The reference impleme= ntation demonstrates how each test can be passed and provides additional co= ntext to the licensee during development for the corresponding assertion.
Why Compatibility Is Important Java platform compatibility is important to different groups i= nvolved with Java technologies for @@ -40,7 +40,7 @@ - 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. + 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.
@@ -100,7 +100,7 @@ automatic running of tests through the JBoss Test harness. - JBoss TCK Runner - An i= mplementation of hte JBoss Test Harness deployment APIs for deploying artif= acts to JBoss AS 5.1 + JBoss TCK Runner - An i= mplementation of the JBoss Test Harness deployment APIs for deploying artif= acts to JBoss AS 5.1 TCK documentation accom= panied by release notes identifying updates between versions. @@ -136,7 +136,7 @@ You'll often see the term in-= container used in this reference guide. This term refers to runn= ing the test suite in any of the aforementioned environments, whilst standalone refers to running the tests outs= ide the container via a JSR-299 implementation-specific standalone bootstr= ap. The standalone mode only runs those tests which don't require EJB,= Servlet or JSF to be present. - The last thing Java developers want is yet another testing fra= mework to make their life more complicated. What they do want is good integ= ration with the their Integrated Development Environment (IDE). These days,= if a tool doesn't have an IDE plugin, then it won't get the atte= ntion it deserves. That's why the JBoss Test Harness is built entirely= TestNG. TestNG is one of the two prominent test frameworks for Java and Te= stNG plugins are available for all major IDEs (with the exception of NetBea= ns) and build tools (Ant and Maven 2). + The last thing Java developers want is yet another testing fra= mework to make their life more complicated. What they do want is a good int= egration with their Integrated Development Environment (IDE). These days, i= f a tool doesn't have an IDE plugin, then it won't get the attent= ion it deserves. That's why the JBoss Test Harness is built entirely u= pon 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 Net= Beans) and build tools (Ant and Maven 2). Because it leverages the existing TestNG ecosystem, there is n= o 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 a= lso get reporting and debugging for free. The JBoss Test Harness supports the following features: @@ -175,11 +175,11 @@ The @Test annotation is provided by TestNG= , the @Artifact annotation is provided by the JBoss Test= Harness and the AbstractJSR299Test is part of the JSR-2= 99 TCK. There is a one-to-one mapping between a TestNG test class and an ar= tifact. The packaging type is defined by the @org.jboss.testharnes= s.impl.packaging.Packaging annotation on the test class, defaulti= ng to a WAR if not specified. Prior to executing the tests for a given class, the JBoss Test= Harness packages the class as a deployable artifact (EAR or WAR), along wi= th any extra resources specified, and deploys the artifact to the container= . The test execution and results are negotatied via HTTP communication usin= g a thin layer over the TestNG test launcher. The test harness can also cat= ch and affirm expected deployment exceptions. This setup and tear down acti= vity is provided by the super class org.jboss.jsr299.tck.AbstractJ= SR299Test, which all TCK test classes must extend. If the annotation @org.jboss.testharness.impl.packagi= ng.IntegrationTest is not present on the test class, then it mean= s the test class can be executed in standalone mode. In standalone mode, t= he deployable artifact is assembled on the local classpath and the tests ex= ecute in the same JVM as the launcher, just as though it were a regular Tes= tNG test case. The standalone mode is provided merely for convenience and e= fficiency. - Chapter X details how to run the TCK test suite using the JBos= s Test Harness. + Chapter 4 details how to run the TCK test suite using the JBos= s Test Harness.
The Porting Package - The JSR-299 TCK relies on an implemnetation of the porting pac= kage to function. The porting package can be divided into two parts. The fi= rst 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 contai= ner. + The JSR-299 TCK relies on an implementation of the porting pac= kage to function. The porting package can be divided into two parts. The fi= rst 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 contai= ner. As mentioned earlier, there are times when the tests need to t= ap directly into the JSR-299 implementation to manipulate behavior or verif= y 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. The four SPI classes in the JSR-299 TCK are as follows: --===============7835543446893158032==--