From webbeans-commits at lists.jboss.org Wed Jul 15 00:38:39 2009 Content-Type: multipart/mixed; boundary="===============0902227208105112027==" MIME-Version: 1.0 From: webbeans-commits at lists.jboss.org To: weld-commits at lists.jboss.org Subject: [webbeans-commits] Webbeans SVN: r3052 - in tck/trunk/doc/reference/en-US: images and 1 other directory. Date: Wed, 15 Jul 2009 00:20:31 -0400 Message-ID: <200907150420.n6F4KVOg024189@svn01.web.mwc.hst.phx2.redhat.com> --===============0902227208105112027== Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable 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 =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/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 @@ Preface - This guide describes how to install, configure, and run the Techno= logy Compatibility Kit (TCK) that is used to verify the compatibility of a = licensee's implementation of the JSR-299: Context and Dependency Injec= tion for Java EE specification. - The JSR-299 TCK is built atop the JBoss Test Harness, a portable = and configurable automated test suite for authoring unit and integration te= sts against Java EE artifacts. The JSR-299 TCK 1.0 uses the JBoss Test Harn= ess version 1.0.0 to execute the test suite. + 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 Inj= ection for Java EE specification. + The JSR-299 TCK is built atop the JBoss Test Harness, a portable = and configurable automated test suite for authoring unit and integration te= sts in a Java EE environment. The JSR-299 TCK 1.0.0 uses the JBoss Test Har= ness version 1.0.0.BETA3 to execute the test suite.
Who Should Use This Book This guide is for licensees of the Context and Dependency Inject= ion for Java EE 1.0 (JSR-299) technology to assist in running the test suit= e that verifies the compatibility of their implementation.
Before You Read This Book - 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 specifi= cations. A good resource for the Java EE programming model is the JCP web site. + 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 specification= s. A good resource for the Java EE programming model is the JCP web site. 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 JSR-299 JCP pa= ge. - Before running the tests in the JSR-299 TCK, read and become fam= iliar with the JBoss Test Harness Reference Guide, which describes how the = test harness functions. + Before running the tests in the JSR-299 TCK, read and become fam= iliar with the JBoss Test Harness Reference Guide (pending), which describe= s how the test harness functions.
How This Book Is Organized If you are running the JSR-299 TCK for the first time, read Chap= ter 1 and Chapter 2 completely for the necessary background information abo= ut the TCK and its purpose. Once you have reviewed that material, perform t= he steps outlined in the remaining chapters. - Chapter 1 gives an overview of the principles that apply gen= erally to all Technology Compatibility Kits (TCKs) and describes the JSR-29= 9 TCK. This chapter also includes a broad listing of the steps for starting= and running the JSR-299 TCK. + Chapter 1 gives an overview of the principles that apply gen= erally to all Technology Compatibility Kits (TCKs) and describes the JSR-29= 9 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 test= ed and verified. - Chapter 2 describes the conformance testing procedure and te= sting requirements. + Chapter 2 explains where to obtain the required software and= how to install it. It covers both the primary TCK components as well as to= ols useful for troubleshooting tests. - Chapter 3 explains... + Chapter 3 details the configuration of the JBoss Test Harnes= s, how to create a TCK runner for the TCK test suite and the mechanics of h= ow an in-container test is conducted. + + Chapter 4 documents how the TCK test suite is executed. It c= overs both modes supported by the TCK, standalone and in-container, and sho= ws how to dump the generated test artifacts to disk. + + + Chapter 5 shows how to run individual tests in Eclipse and a= dvices the best way to setup your Eclipse workspace for running the tests.<= /para> + + + Chapter 6 builds on chapter 5 by detailing how to debug indi= vidual tests in Eclipse. + + + Chapter 7 (pending) explains the test reports that are gener= ated by the TCK test suite and introduces the TCK audit report as a tool fo= r measure a licensee's progress in passing the TCK. +
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-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 @@ - + Configuration - This chapter examples... + This chapter lays out how to configure the JBoss Test Harness by s= pecifying the SPI implementation classes, defining the target container co= nnection information, and various other switches. You then learn how to set= up a TCK runner project that executes the the TCK test suite, putting thes= e settings into practice. Finally, a detailed account of how the JBoss Test= Harness negotiates the execution of the tests in the container is given.
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 X.X, for the fully qualified class name of a concreate = configuration builder implementation. This implementation loads the remaini= ng configuration settings and produces a JBoss Test Harness configuration.<= /para> - For you convenience, a default configuration builder implementat= ion is provided, org.jboss.testharness.impl.PropertiesBasedConfigu= rationBuilder, which retrieves all the JBoss Test Harness configu= ration settings from Java properties. It does so by aggregating the system = properties and the properties defined in the META-INF/jboss-test-harness.p= roperties resource in any classpath entry under a single properties map, al= lowing you to segment the configuration settings as needed. - A complete list of configuration properties for the JBoss Test H= arness is itemized in table X.X, along with the default value (if any) and = a description for each property. + 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. + 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. <tgroup cols=3D"2"> @@ -123,7 +123,7 @@ </tbody> </tgroup> </table> - <para>The general TCK porting package is also configured using the Jav= a properties file META-INF/jboss-test-harness.properties or system properti= es. Each implementation of the Porting Package SPI should be specified usin= g the fully-qualified domain name (FQDN) of the interface as the property v= alue. The properties which must be satisified are listed in table X.XX.</pa= ra> + <para>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.</para> <table frame=3D"all"> <title/> <tgroup cols=3D"2"> @@ -164,4 +164,143 @@ </tgroup> </table> </section> + <section> + <title>Setting up the TCK runner project + The TCK runner project is the magic that makes everything come t= ogether 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 g= ood 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 tha= t tests the JSR-299 RI. + 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. +
+ + <tgroup cols=3D"3"> + <colspec colname=3D"c1"/> + <colspec colname=3D"c2"/> + <colspec colname=3D"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 Mave= n respository using the following command template:</para> + <programlisting>mvn install:install-file \ +-Dfile=3Djsr299-tck-api.jar \ +-DgroupId=3Dorg.jboss.jsr299.tck \ +-DartifactId=3Djsr29-tck-api \ +-Dversion=3D1.0.0-SNAPSHOT \ +-Dpackaging=3Djar</programlisting> + <para>You should substituate the webbeans-core and webbeans-porting-pa= ckage artifacts from table 2.2.3 if you are running the TCK against your JS= R-299 implementation. You'll also need to replace the jboss-test-harne= ss-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 implementatio= ns of the <literal>Containers</literal> SPI for the JBoss Test Harness.</pa= ra> + <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 ver= sion 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 loc= al Maven repository (groupId=3Dorg.jboss.jsr299.tck, artifactId=3Djsr299-tc= k-impl, classifier=3Dsuite, type=3Dxml, version=3D1.0.0-SNAPSHOT), but it&a= pos;s not declared as a regular Maven dependency. That's because the t= est suite must be available to both the client JVM and the container JVM. T= he maven-dependency-plugin is used to copy it to the target/dependencies/li= b 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 followi= ng property assignment:</para> + <programlisting>org.jboss.testharness.libraryDirectory=3Dtarget/depend= ency/lib</programlisting> + <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> + </section> + <section> + <title>Negotiating the execution of an in-container test + The 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. + 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. + The test launcher is the API that allows test suite to launch th= e test in a pluggable fashion. AbstractTest, the super c= lass of AbtractJSR299Test, implements IHookable= , a TestNG interface which allows the execution of the test metho= d to be intercepted. Using that mechanism, AbstractTest delegates execution= of the test method (a method annotated with @Test in an= @Artifact class) to an implementation of org.j= boss.testharness.api.TestLauncher if the tests are being executed= in-container. As you might anticipate, the implementation is specified usi= ng 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 imp= lementation, org.jboss.testharness.impl.runner.servlet.ServletTest= Launcher, that hooks into the HTTP communication infrastructure d= escribed above! . It invokes the ServletTestRunner servlet for each met= hod annotated with @Test in the @Artifact that is not otherwise disabled. + If you wish to implement the runner yourself, you must return a = TestResult as a result of executing the method in the co= ntainer. You must also ensure that any exception which occurs during deploy= ment is wrapped as a org.jboss.testharness.api.DeploymentExceptio= n, and that any communication problem is rethrown as an = IOException. The deployment exception may be transformed by an im= plementation of the org.jboss.testharness.api.DeploymentExceptionT= ransformer interface, which is specified using the org.j= boss.testharness.container.deploymentExceptionTransformer propert= y. The default implementation passes on the original exception unchanged. + So in short, JBoss Test Harness takes care of all the interfaces= you need to execute tests in-container except for the implementation of th= e Containers SPI. That is, unless you are deploying to o= ne of the containers supported by the JBoss Test Harness. + Added: tck/trunk/doc/reference/en-US/eclipse-debugging.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/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 @@ + + + + Debugging Tests in Eclipse + This chapter explains how to debug standalone tests and integratio= n tests from the TCK test suite in Eclipse. You should be able to use the l= essons learned here to debug tests in an alternate IDE. +
+ Debugging a standalone test + 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, simpl= y right click in the editor view and select TestNG > Debug as test. Ecli= pse will stop at any breakpoints you set just like it would with any other = local debug process. + 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: + + + Select the Run > Debug Configurations... menu from the ma= in menubar + + + Select the name of the test class in the TestNG category + + + Select the Source tab + + + Click the Add... button on the right + + + Select Java Project + + + Check the project the contains the class you want to debug (= e.g., webbeans-core) + + + Click OK on the Project Selection window + + + Click Close on the Debug Configurations window + + + 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). + Again, running a test in standalone isn't enough to pass th= e TCK and cannot be used to run or debug an integration test. Let's lo= ok at how to debug a test running in the context of the container. +
+
+ Debugging an integration test + In order to debug an integration test, or any test run in in-con= tainer 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. Th= at puts the debugger on both sides of the fence, so to speak. + Since setting up a test to run in-container has already been cov= ered, we'll look at how to attach the IDE debugger to the container, a= nd then move on launching the test in debug mode. +
+ Attaching the IDE debugger to the container + 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 contai= ner running with JPDA enabled. + The Eclipse Server Tools, a subproject of the Eclipse Web Tool= s Project (WTP), has support for launching most major application servers, = including JBoss AS 5. However, if you are using JBoss AS, you should consid= er using JBoss Tools instead, which offers tighter integration with JBoss t= echnologies. See either the Server Tools documentation or the JBoss Tools docu= mentation for how to setup a container and start it in debug mode.<= /para> + See this blog entry to lea= rn how to start JBoss with JPDA enabled and how to get the Eclipse debugger= to connect to the remote process. +
+
+ Launching the test in the debugger + Once Eclipse is debugging the container, you can set a breakpo= int in the test and debug it just like a standalone test. Open a test annot= ated with @IntegrationTest in the Eclipse editor, right = click in the editor view, and select TestNG > Debug as test. The only d= ifference 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> + Remember that if you need to debug into dependent libraries, t= he source code for those libraries needs to be registered with the TestNG d= ebug configuration as described in the first section in this chapter. +
+
+ Added: tck/trunk/doc/reference/en-US/eclipse-running.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/eclipse-running.xml = (rev 0) +++ tck/trunk/doc/reference/en-US/eclipse-running.xml 2009-07-15 04:20:28 U= TC (rev 3052) @@ -0,0 +1,154 @@ + + + + Running Tests in Eclipse + This chapter explains how to run individual tests using the Eclips= e TestNG plugin. It covers running non-integration tests in standalone mode= and integration tests (as well as non-integration tests) in in-container m= ode. You should be able to use the lessons learned here to debug tests in a= n alternate IDE. +
+ Leveraging Eclipse's plugin ecosystem + The primary motivation for building the test harness on top of a= n existing testing framework is to allow the tests to be executed and debug= ged in an Integrated Development Environment (IDE) using availalbe plugins.= It's also the easiest way to execute a test class in isolation. + The TCK can be executed in any IDE for which there is a TestNG p= lugin available. Running a test in Eclipse is almost as simple as running t= he test with the Eclipse TestNG plugin. You can also use the plugin to debu= g a test, which is described in the next chapter. + Before running a test from the TCK test suite in Eclipse, you mu= st have the Eclipse TestNG plugin = and the m2eclipse plugin installed. Refer to section 2.2.2 for more informa= tion on these plugins. + With the m2eclipse plugin installed, Eclipse should recognize th= e 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 c= ode, which is covered later. +
+
+ Readying the Eclipse workspace + When setting up your Ecilpse workspace, I recommend creating thr= ee workings sets: one for the JSR-299 RI (Web Beans), one for the JSR-299 T= CK and one for the JBoss TCK Runner. The dependencies between the projects = will be established automatically by the m2eclipse plugin based on the depe= ndency information in the pom.xml files. Your workspace should appear as fo= llows: + 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 + The tests in the TCK test suite are located in the jsr299-tck-im= pl 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 individu= al test in Eclipse? The secret is that you need to establish a link in Ecli= pse (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 step= s to establish the link: + + + Right click on the jsr299-tck-impl project + + + Select Build Path > Configure Build Path... + + + Click on the Projects tab + + + Click the Add... button on the right + + + Check the TCK runner project (e.g., webbeans-jboss-tck-runne= r) + + + Click the OK button on the Required Project Selection dialog= window + + + Click the OK button on the Java Build Path window + + + The TCK runner project should pull in the JSR-299 implementation= , the TCK porting package and any additional properties that must be define= d to execute the TCK test suite. +
+
+ Running a test in standalone mode + Your now ready to execute an individual test class (a class whic= h extends AbstractJSR299Test and is annotated with @Artifact). Select a tes= t class that is not annotated with @IntegrationTest and open it in the Eclipse editor. Right c= lick 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). + + If the TCK complains that there is a property missing, close a= ll the projects, open them again, and rebuild. The m2eclipse plugin can be = finicky getting everything built correctly the first time. + + 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 m= ode. Using in-container mode also the only way to execute a test annotated = with @IntegrationTest as it requires container resources= . So let's see what has to be done to execute an integration test. Thi= s will result in the artifact being deployed to the container, which is JBo= ss AS 5.1 if you are using the JBoss TCK runner. +
+
+ Running integration tests + As you have learned, the JBoss test harness determines how to be= have based on the values of numerous system properties or properties define= d in META-INF/jboss-test-harness.properties classpath resources. If the pro= perty named org.jboss.testharness.standalone is not defi= ned, 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 va= lues for other properties required to run an in-container test. + The JBoss TCK runner project conveniently provides the properti= es file src/test/debug-resources/META-INF/jboss-test-harness.properties tha= t contains all of the necessary properties. You may have to tune the org.jboss.testharness.container.extraConfigurationDir and org.jboss.testharness.libraryDirectory properties to point t= o the relative location of the related projects. The properties should be d= efined as follows: + + + org.jboss.testharness.container.extraConfigurationD= ir - the relative path from the jboss-tck-impl project to a dir= ectory that contains a build.properties or local.build.properties file defi= ning the location of a JBoss AS 5.1 installation in the jboss.home= property + + + org.jboss.testharness.libraryDirectory - = the relative path from the jboss-tck-impl project to the target/dependency/= lib directory in the TCK runner project. + + + The other properties in that file are defined as follows: + org.jboss.testharness.standalone=3Dfalse +orjboss.testharness.container.forceRestart=3Dfalse +orjboss.testharness.runIntegrationTests=3Dtrue + You're now ready to execute an integration test. Select an = integration test (a class that extends AbstractJSR299Test and is annotated with both @Artifact and @I= ntegrationTest) and open it in your Eclipse editor. Follow these = steps to execute the class with the TestNG plugin: + + + Right click in the editor view and select TestNG > Run as= test + + + Observe the test fail because of missing dependencies + + + Select the Run > Run Configurations... menu from the main= menubar + + + Select the name of the test class under the TestNG category<= /para> + + + Select the Classpath tab + + + Select User Entries in the tree + + + Click the Advanced... button on the right + + + Select Add Folders and click the OK button + + + Select the webbeans-jboss-tck-runner/src/test/debug-resource= s folder + + + Click the OK button on the Folder Selection dialog window + + + Click on the webbeans-jboss-tck-runner entry + + + Move the webbeans-jboss-tck-runner to the first entry using = the Up button + + + Click the Run button on the Run Configurations dialog window= + + + When you run the test this time, it should pass. If you get a fa= ilure that the container (e.g., JBoss AS 5.1) must be run with assertions e= nabled, you need to stop the container and start it with the -ea flag (or j= ust leave it stopped and the test will start it appropriately). + You can simply right click and select TestNG > Run as test fo= r all subsequent runs for the reason cited earlier, the run configuration f= or a class is retained indefinitely. + Alternatively, you can configure TestNG to execute all tests in-= container by default by adding the properties file in the debug-resources f= older to the project's classpath as follows: + + + Right click on the jsr299-tck-impl project + + + Select Build Path > Configure Build Path... + + + Click on the Libraries tab + + + Click the Add Class Folder... button on the right + + + Check the webbeans-jboss-tck-runner/src/test/debug-resources= folder + + + Click the OK button on the Class Folder Selection dialog win= dow + + + Click the OK button on the Java Build Path window + + + Now you don't have to do any special configuration for each= test class. + You can stop the individual tests from running in-container by r= eversing the steps above to remove the debug-resources folder from the Ecli= pse classpath. + You have now mastered running the JSR-299 TCK against the JSR-2= 99 RI using both Maven 2 and within Eclipse. Now you're likely interes= ted in how to debug a test so that you can efficiently investigate test fai= lures. +
+ 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-14 18:32:29 UTC (re= v 3051) +++ tck/trunk/doc/reference/en-US/executing.xml 2009-07-15 04:20:28 UTC (re= v 3052) @@ -1,41 +1,194 @@ - + - Executing Tests - This chapter explains how to execute the TCK against the JSR-299 R= I as well as your own implementation. The JSR-299 TCK uses the Maven 2 Test= NG 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. + Executing the Test Suite + 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.
- Launching the Test Suite - Each test class is treated as an individual artifact (hence the = @Artifact annotation on the class). All test methods (i.= e., methods annotated with @Test) 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= . - The test suite is executed by the TestNG plugin for Maven 2 duri= ng 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 inclu= des 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 w= ith Web Beans to use your JSR-299 implementation as described in section X= X.X. -
- Running the Tests In Standalone Mode - To execute the TCK test suite against the JSR-299 RI, first ch= ange to the jboss-tck-runner directory in the extracted Web Beans distribut= ion: - cd <webbeans_install_dir>/jboss-tck-runner - Then execute the Maven 2 life cycle through the test phase: - mvn test - Without any command-line flags, the test suite is run in stand= alone mode, which means that any test class with the @org.jboss.te= stharness.impl.packaging.IntegrationTest annotation is skipped. T= his mode uses the StandaloneContainers 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-cont= ainer mode. -
-
- Running the Tests In In-Container Mode - To execute the test suite using in-container mode, you first h= ave to set the property jboss.home to the location of a = JBoss AS 5.1 installation in the following Java properties file in the extr= acted Web Beans distribution: - <webbeans_install_dir>/jboss-as/local.build.pr= operties - Then add the incontainer property to the co= mmand that launches the Maven 2 life cycle: - mvn test -Dincontainer - The presence of the incontainer property ac= tivates a Maven 2 profile that assigns the org.jboss.testharness.= standalone system property to false and the org.jboss.testharness.runIntegrationTests system property = to true, hence activing the in-container test mode. - When the Maven 2 life cycle is run with the incontain= er property present, all the test artifacts in the test suite are= executed. The in-container mode uses the Containers SPI= to deploy the test artifact to the container and execute the test in a tru= e Java EE life cycle. - Since in-container tests are executed in a remote JVM, the res= ults of the test must be communicated back to the runner over a container-s= upported protocol. The TCK provides servlet-based communication over HTTP.<= /para> -
-
- Running a Subset of Tests - -
-
- Dumping a Test Artifact - -
-
- Running a Test in Eclipse - -
+ The Test Suite Runner + Each test class is treated as an individual artifact (hence the = @Artifact annotation on the class). All test methods (i.= e., methods annotated with @Test) 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. + The test suite is executed by the Maven 2 TestNG plugin during t= he 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 B= eans) running inside JBoss AS 5.1. To execute the JSR-299 TCK on your own J= SR-299 implementation, you must modify the TCK runner project included wit= h Web Beans to use your JSR-299 implementation as described in section 4.2= .
+
+ Running the Tests In Standalone Mode + To execute the TCK test suite against the JSR-299 RI, first swit= ch to the jboss-tck-runner directory in the extracted Web Beans distributio= n: + cd <webbeans_install_dir>/jboss-tck-runner + Then execute the Maven 2 life cycle through the test phase: + mvn test + Without any command-line flags, the test suite is run in standal= one mode, which means that any test class with the @org.jboss.test= harness.impl.packaging.IntegrationTest annotation is skipped. Thi= s mode uses the StandaloneContainers SPI to invoke the t= est artifact within a mock Java EE life cycle and capture the results of th= e test. However, passing the suite in this mode is not sufficient to pass t= he TCK as a whole. The suite must be passed while executing in in-container= mode. +
+
+ Running the Tests In the Container + To execute the test suite using in-container mode with the JBoss= TCK runner, you first have to set the property jboss.home 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 distribut= ion: + <webbeans_install_dir>/jboss-as/local.build.prop= erties + Then, add the incontainer property to the com= mand that launches the Maven 2 life cycle: + mvn test -Dincontainer + The presence of the incontainer property acti= vates a Maven 2 profile that assigns the org.jboss.testharness.st= andalone system property to false and the org.jboss.testharness.runIntegrationTests system property to= true, hence activing the in-container test mode. + When the Maven 2 life cycle is run with the incontainer= property present, all the test artifacts in the test suite are e= xecuted. The in-container mode uses the Containers SPI t= o 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 th= at provides an implementation of this interface for JBoss AS 5.1. + Since in-container tests are executed in a remote JVM, the resul= ts of the test must be communicated back to the runner over a container-sup= ported protocol. The JBoss Test Harness provides servlet-based communicatio= n over HTTP as described in section 3.3. +
+
+ Running a Subset of Tests + The TCK test suite is controlled by a TestNG descriptor. The Tes= tNG descriptor tck-tests.xml, located in the src/main/resources directory o= f the jsr299-tck-impl project, defines the TCK test suite. The main config= uration in this file is the packages filter, shown below, which instructs T= estNG to look in the org.jboss.jsr299.tck.tests package = to find the test classes. + <packages> + <package name=3D"org.jboss.jsr299.tck.tests"/> +</packages> + The descriptor also includes configuration of a method selector = implementation, shown below, that allows integration tests to be skipped wh= en the test suite is executed in standalone mode. + <method-selectors> + <method-selector> + <selector-class name=3D"org.jboss.testharness.impl. +testng.DisableIntegrationTestsMethodSelector" /> + </method-selector> +</method-selectors> + 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 develope= d. 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 workin= g on an implementation. Alternatively, you can explicity list the classes t= hat you want to have executed if you are focusing on a specific area of th= e TCK. See the TestNG reference guide for more information about how you can cont= rol which classes are selected to be run when the test suite is executed. +
+
+ Dumping the Test Artifacts + As you have learned, when the test suite is executing using in-c= ontainer mode, each test class is packaged as a deployable artifact and dep= loyed to the container. The test is then executed within the context of the= deployed application. This leaves room for errors in packaging. When inves= tingating a test failure, it's helpful to be able to inspect the artif= act after it is generated. The TCK can accomodate this type of inspection b= y "dumping" the generated artifact to disk. + If the dumpArtifacts is defined as a system p= roperty or defined in the classpath resource META-INF/jboss-test-harness.pr= operties and has a value of true, the JBoss Test Harnes= s will write the artifact to an output directory prior to deploying it to t= he server. This behavior is activated in the jboss-tck-runner project by ap= pending the dumpArtifacts command line property to the e= nd of the command that invokes the Maven test phase. + mvn test -Dincontainer -DdumpArtifacts + 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). +
+
+ Running a Test in Eclipse + The primary motivation for building the test harness on top of a= n existing testing framework is to allow the tests to be executed and debug= ged in an Integrated Development Environment (IDE) using availalbe plugins.= It's also the easiest way to execute a test class in isolation. + The TCK can be executed in any IDE for which there is a TestNG p= lugin available. Running a test in Eclipse is almost as simple as running t= he test with the Eclipse TestNG plugin. You can also use the TestNG plugin = to debug a test, which is described in the next chapter. + Before running a test from the TCK test suite in Eclipse, you mu= st have the Eclipse TestNG plugin = installed. Instructions for using the TestNG update site to add the TestNG = plugin to Eclipse are provided on the TestNG download page. You can find a tutorial that ex= plains how to use the TestNG plugin on the TestNG Eclipse page. + You should also have the m2eclipse plugin installed. This plugin absolutely essential = for working with Maven 2 projects, which both the JSR-299 RI and the TCK ar= e. Instructions for using the m2eclipse update site to add the m2eclipse pl= ugin to Eclipse are provided on the m2eclipse home page. Sonatype, the comp= any that maintains the m2eclipse plugin and is a strong supporter of Maven,= publishes an entire reference guide dedicated to the plugin on their w= ebsite. + 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 t= o debug into that code. + When setting up your Ecilpse workspace, I recommend creating thr= ee workings sets: one for the JSR-299 RI (Web Beans), one for the JSR-299 T= CK and one for the JBoss TCK Runner. The dependencies between the projects = will be established automatically by the m2eclipse plugin based on the depe= ndency information in the pom.xml files. Your workspace should appear as fo= llows: + 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 + The tests in the TCK test suite are located in the jsr299-tck-im= pl 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 individu= al test in Eclipse? The secret is that you need to establish a link in Ecli= pse (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 step= s to establish the link: + + + Right click on the jsr299-tck-impl project + + + Select Build Path > Configure Build Path... + + + Click on the Projects tab + + + Click the Add... button on the right + + + Check the TCK runner project (e.g., webbeans-jboss-tck-runne= r) + + + Click the OK button on the Required Project Selection dialog= window + + + Click the OK button on the Java Build Path window + + + The TCK runner project should pull in the JSR-299 implementation= , the TCK porting package and any additional properties that must be define= d to execute the TCK test suite. + Your now ready to execute an individual test class (a class whic= h extends AbstractJSR299Test and is annotated with @Artifact). Select a tes= t class that is not annotated with @IntegrationTest and open it in the Eclipse editor. Right c= lick 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). + + If the TCK complains that there is a property missing, close a= ll the projects, open them again, and rebuild. The m2eclipse plugin can be = finicky getting everything built correctly the first time. + + 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 m= ode. Using in-container mode also the only way to execute a test annotated = with @IntegrationTest as it requires container resources= . So let's see what has to be done to execute an integration test. Thi= s will result in the artifact being deployed to the container, which is JBo= ss AS 5.1 if you are using the JBoss TCK runner. + As you have learned, the JBoss test harness determines how to be= have based on the values of numerous system properties or properties define= d in META-INF/jboss-test-harness.properties classpath resources. If the pro= perty named org.jboss.testharness.standalone is not defi= ned, 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 va= lues for other properties required to run an in-container test. + The JBoss TCK runner project conveniently provides the properti= es file src/test/debug-resources/META-INF/jboss-test-harness.properties tha= t contains all of the necessary properties. You may have to tune the org.jboss.testharness.container.extraConfigurationDir and org.jboss.testharness.libraryDirectory properties to point t= o the relative location of the related projects. The properties should be d= efined as follows: + + + org.jboss.testharness.container.extraConfigurationD= ir - the relative path from the jboss-tck-impl project to a dir= ectory that contains a build.properties or local.build.properties file defi= ning the location of a JBoss AS 5.1 installation in the jboss.home= property + + + org.jboss.testharness.libraryDirectory - = the relative path from the jboss-tck-impl project to the target/dependency/= lib directory in the TCK runner project. + + + The other properties in that file are defined as follows: + org.jboss.testharness.standalone=3Dfalse +org.oss.testharness.container.forceRestart=3Dfalse +org.oss.testharness.runIntegrationTests=3Dtrue + You're now ready to execute an integration test. Select an = integration test (a class that extends AbstractJSR299Test and is annotated with both @Artifact and @I= ntegrationTest) and open it in your Eclipse editor. Follow these = steps to execute the class with the TestNG plugin: + + + Right click in the editor view and select TestNG > Run as= test + + + Observe the test fail because of missing dependencies + + + Select the Run > Run Configurations... menu from the main= menubar + + + Select the name of the test class under the TestNG category<= /para> + + + Select the Classpath tab + + + Select User Entries in the tree + + + Click the Advanced... button on the right + + + Select Add Folders and click the OK button + + + Select the webbeans-jboss-tck-runner/src/test/debug-resource= s folder + + + Click the OK button on the Folder Selection dialog window + + + Click on the webbeans-jboss-tck-runner entry + + + Move the webbeans-jboss-tck-runner to the first entry using = the Up button + + + Click the Run button on the Run Configurations dialog window= + + + When you run the test this time, it should pass. If you get a fa= ilure that the container (e.g., JBoss AS 5.1) must be run with assertions e= nabled, you need to stop the container and start it with the -ea flag (or j= ust leave it stopped and the test will start it appropriately). + You can simply right click and select TestNG > Run as test fo= r all subsequent runs for the reason cited earlier, the run configuration f= or a class is retained indefinitely. + Alternatively, you can configure TestNG to execute all tests in-= container by default by adding the properties file in the debug-resources f= older to the project's classpath as follows: + + + Right click on the jsr299-tck-impl project + + + Select Build Path > Configure Build Path... + + + Click on the Libraries tab + + + Click the Add Class Folder... button on the right + + + Check the webbeans-jboss-tck-runner/src/test/debug-resources= folder + + + Click the OK button on the Class Folder Selection dialog win= dow + + + Click the OK button on the Java Build Path window + + + Now you don't have to do any special configuration for each= test class. + You can stop the individual tests from running in-container by r= eversing the steps above to remove the debug-resources folder from the Ecli= pse classpath. + You have now mastered running the JSR-299 TCK against the JSR-2= 99 RI using both Maven 2 and within Eclipse. Now you're likely interes= ted in how to debug a test so that you can efficiently investigate test fai= lures. +
Added: tck/trunk/doc/reference/en-US/images/in-container-execution.png =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 (Binary files differ) Property changes on: tck/trunk/doc/reference/en-US/images/in-container-exec= ution.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream 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-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 @@ - + Installation This chapter explains how to obtain the TCK and supporting softwar= e and provides recommendations for how to install/extract it on your system= . @@ -7,11 +7,11 @@ Obtaining the Software You can obtain the JSR-299 TCK project from the JBoss SVN repository or you can download a release from the download page on Seam Framework website. The JSR-2= 99 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 J= SR-299 TCK available, so you need to check out the TCK from the JBoss SVN = repository. The TCK project downloads additional required libraries from th= e JBoss Maven 2 repository automatically, including the JBoss Test Harness = and the JSR-299 API. You may follow this approach when assembling a TCK run= ner for your JSR-299 implementation. - The JSR-299: Contexts and Dependency Injection for Java EE 1.0 r= eference implementation (RI) is Web Beans. You can obtain the latest Web Be= ans release from the downl= oad page on Seam Framework website. Web Beans includes a TCK runner= that executes the TCK using the RI by deploying the test artifacts to JBo= ss AS 5. + The JSR-299: Contexts and Dependency Injection for Java EE 1.0 r= eference implementation (RI) is Web Beans. You can obtain the latest Web Be= ans release from the downl= oad page on Seam Framework website. Web Beans includes a TCK runner= that executes the TCK on the JSR-299 RI by deploying the test artifacts t= o JBoss AS 5.1. 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 wi= th the TCK before testing your own JSR-299 implementation. - Executing the TCK requires a Java EE 5 or better runtime environ= ment (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 org.jboss.jsr299= .tck.spi.Containers interface from the TCK Porting Package. You c= an download JBoss AS 5 from the JBoss AS project page. + Executing the TCK requires a Java EE 5 or better runtime environ= ment (i.e., application server), to which the test artifacts are deployed a= nd invoked. The TCK does not depend on any particular Java EE implementatio= n, only that it is compliant. However, if you decide to use JBoss AS 5.1 a= s the target container, you can use the JBoss AS 5.1 connector provided wit= h the JBoss Test Harness, alleviating the requirement of implementing the <= literal>org.jboss.jsr299.tck.spi.Containers SPI from the TCK port= ing package. You can download JBoss AS 5.1 from the JBoss AS project page. Naturally, to execute Java programs, you must have a Java SE run= time environment. The TCK requires Java SE 1.5 or better, which you can obt= ain from the Java Software webs= ite.
@@ -23,7 +23,7 @@ Java SE 5.0 or better - Java EE 5 or better (e.g., JBoss AS 5 or GlassFish V3) + Java EE 5 or better (e.g., JBoss AS 5.x or GlassFish V3) You can download Java SE from the Java Software @@ -31,9 +31,48 @@ Refer to the instructions that ac= company the software for how to install it on your system. You should be sure that the JAVA_HOME environment varia= ble is assigned to the location of the Java SE software before you consider= the installation complete. - 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 tim= e of writing, JBoss AS 5 is the only supported application server. Hence, J= Boss AS 5 is the recommend Java EE runtime environment. - JBoss AS 5 can be downloaded from the JBoss AS project page. Ref= er 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= JBOSS_HOME environment variable to the location of the = JBoss AS software. - The remaining components required to setup and execute the TCK a= re merely extracted. It's recommended that you first create a workspac= e 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". - ... + 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 tim= e 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. + JBoss AS 5.1 can be downloaded from the JBoss AS project page. R= efer to the instructions that accompany the software to learn how to instal= l it on your system. Although not required, it's recommended that you = set the JBOSS_HOME environment variable to the location = of the JBoss AS software. + 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 name= d tck. If you have downloaded the Web Beans distribution, extract it into a= sibling folder named webbeans. The resulting folder structure is shown her= e: + jsr299/ + webbeans/ + tck/ + This arrangement becomes important later on when executing tests= in Eclipse. +
+ Web Beans deployer + When the TCK test suite is run (using in-container mode), it e= xpects to test the JSR-299 implementation provided by the application serve= r. Therefore, you need to install the JSR-299 implementation in the applica= tion server. + The JSR-299 RI (Web Beans) includes a JBoss AS integration pro= ject that installs a special deployer on JBoss AS 5.x that activates the JS= R-299 RI per application when the application is deployed. The Web Beans de= ployer is installed in JBoss AS 5.x from the jboss-as directory in the Web = Beans distribution. + To install the web beans deployer, first make sure the jboss.home property in the local.build.properties file in the j= boss-as directory references a JBoss AS 5.1 installation: + jboss.home=3D/path/to/jboss-as-5.1 + Then, run Ant from the jboss-as directory to install the deplo= yer: + ant update + The libraries needed by the deployer are fetched from the Mave= n 2 repository on demand. The versions of the libraries fetched are define= d in the build.properties files in that directory. +
+
+ Maven 2 and Maven 2 artifacts + 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. + 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: + mvn install:install-file \ +-Dfile=3Djsr299-impl.jar \ +-DgroupId=3Dcom.company.jsr299 \ +-DartifactId=3Djsf299-impl \ +-Dversion=3D1.0 \ +-Dpackaging=3Djar + You can use this command template for installing any JAR file = you need into your local Maven respository. + + The JSR-299 implementation doesn't have to be on the cl= asspath 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 cont= ainer. However, the implementation does have to be on the classpath when ex= ecuting the test suite in standalone mode. + +
+
+ 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. +
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-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 @@ - + Introduction This chapter explains the purpose of a TCK and identifies the foun= dation elements of the JSR-299 TCK. @@ -7,7 +7,7 @@ TCK Primer A TCK, or Technology Compatibility Kit, is one of the three requ= ired 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 veri= fy 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 e= xecuting the tests. 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 t= he aforementioned assertions, and in turn the specification. For a particul= ar implementation to be certi=EF=AC=81ed, all of the required tests must pa= ss (the provided test suite must be run unmodified). - A TCK is entirely implementation agnostic. Ideally, it should va= lidate assertions by consulting the specficiation's public API. Howeve= r, when the information returned by the public API is not low-level enough = to validate the assertion, the implementation must be consulted directly. I= n this case, the TCK provides an independent API as part of a porting packa= ge which must also be implemented by the licensee. Section 1.3.4 introduces= the porting package and Section X.XX covers the requirements for implemen= ting it. + A TCK is entirely implementation agnostic. Ideally, it should va= lidate assertions by consulting the specficiation's public API. Howeve= r, when the information returned by the public API is not low-level enough = to validate the assertion, the implementation must be consulted directly. I= n this case, the TCK provides an independent API as part of a porting packa= ge which must also be implemented by the licensee. Section 1.3.4 introduces= the porting package and section 4.1 covers the requirements for implemen= ting it.
Compatibility Testing @@ -57,7 +57,7 @@ This section lists the applicable requirements and specificati= ons for the JSR-299 TCK. - Speci=EF=AC=81cation requirements<= /emphasis> - Software requirements for a JSR-299 implementation are itermiz= ed in Section 1.2 of Chapter 1, "Relationship to other specifications&= quot; in the JSR-299 specification, with details provided throughout the sp= ecification. + Speci=EF=AC=81cation requirements<= /emphasis> - Software requirements for a JSR-299 implementation are itemize= d in section 1.2, "Relationship to other specifications" in the J= SR-299 specification, with details provided throughout the specification. Contexts and Dependency Injection = for Java EE 1.0 API - The Java API defined in the JSR-299 specif= ication and provided by the reference implementation. @@ -77,6 +77,9 @@ See details at Java EE 5 (http://java.sun.c= om/javaee/5/docs/api/). + + Maven 2 - Although lice= nsees are free to execute the TCK however they decide, the recommended appr= oach is to use Maven 2. Both the JSR-299 RI and the TCK are build using Mav= en 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 Ma= ven 2 project. Therefore, it's highly recommended to have Maven 2 inst= alled on the system. +
@@ -97,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 + JBoss TCK Runner - An i= mplementation of hte 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. @@ -113,7 +116,7 @@ Java Platform, Enterprise Edition, Version 5 reference i= mplementation (Java EE 5 RI) - JBoss AS 5? + JBoss AS 5.1? The JSR-299 TCK tests run on the following platforms: @@ -176,8 +179,8 @@
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. - 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 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. + 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: @@ -193,8 +196,8 @@ org.jboss.jsr299.tck.spi.Managers - To run the full TCK you must additionally implement o= rg.jboss.testharness.spi.Containers, which handles deploying the = test artifact to the container. If you wish to run the TCK in standalone mo= de, you must also implement org.jboss.testharness.spi.StandaloneCo= ntainers. 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. - The default configuration for the TCK is property-based. There= fore, you specify the implementation class for all of these SPIs in a prope= rties file. There are additional properties for controlling whether the tes= ts are run in standalone or in-container mode. Optionally, you can use syst= em properties to configure the TCK. Details are provided in Section X.XX. + To run the full TCK you must additionally implement o= rg.jboss.testharness.spi.Containers, which handles deploying the = test artifact to the container. If you wish to run the TCK in standalone mo= de, you must also implement org.jboss.testharness.spi.StandaloneCo= ntainers. Implementations of these APIs are already available for= JBoss AS 5.1. Therefore, you only need to implement this part of the porti= ng package if you wish to use a container other than JBoss AS 5.1, for inst= ance GlassFish V3. + The default configuration for the TCK is property-based. There= fore, you specify the implementation class for all of these SPIs in a prope= rties file. There are additional properties for controlling whether the tes= ts are run in standalone or in-container mode. Optionally, you can use syst= em properties to configure the TCK. Details are provided in section 4.1.
TCK Audit Tool Modified: tck/trunk/doc/reference/en-US/part1-background.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/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 @@ - + Getting Acquainted with the TCK Modified: tck/trunk/doc/reference/en-US/part2-setup.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/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 @@ - + Installation and Setup Modified: tck/trunk/doc/reference/en-US/part3-execution.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/part3-execution.xml 2009-07-14 18:32:29 U= TC (rev 3051) +++ tck/trunk/doc/reference/en-US/part3-execution.xml 2009-07-15 04:20:28 U= TC (rev 3052) @@ -1,9 +1,11 @@ - + Executing and Debugging Tests - In this part you learn how to execute the JSR-299 TCK. First, yo= u are taken through the steps necessary to execute the test suite against t= he JSR-299 RI (Web Beans). Then you discover how to modify the TCK runner t= o execute the test suite against your own implementation. Finally, you lear= n how to debug individual tests in the test suite. + 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 implemen= tation. Finally, you learn how to debug tests from the test suite in Eclips= e. + + --===============0902227208105112027==--