Author: dan.j.allen Date: 2009-07-28 15:41:58 -0400 (Tue, 28 Jul 2009) New Revision: 3319 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 Log: minor revisions Modified: tck/trunk/doc/reference/en-US/Book_Preface.xml =================================================================== --- tck/trunk/doc/reference/en-US/Book_Preface.xml 2009-07-28 19:32:32 UTC (rev 3318) +++ tck/trunk/doc/reference/en-US/Book_Preface.xml 2009-07-28 19:41:58 UTC (rev 3319) @@ -18,8 +18,7 @@ <para> The CDI TCK is provide under the - <ulink url="http://www.apache.org/licenses/LICENSE-2.0">Apache Public License 2.0</ulink> - . + <ulink url="http://www.apache.org/licenses/LICENSE-2.0">Apache Public License 2.0</ulink>. </para> <section id="target-audience"> @@ -50,8 +49,7 @@ EE technology specification 1.0 (JSR-299). Information about the specification, including links to the specification documents, can be found on the - <ulink url="http://jcp.org/en/jsr/detail?id=299">JSR-299 JCP page</ulink> - . + <ulink url="http://jcp.org/en/jsr/detail?id=299">JSR-299 JCP page</ulink>. </para> <para> Before running the tests in the CDI TCK, read and become @@ -71,8 +69,8 @@ and <xref linkend="test-harness-introduction" /> completely for the necessary background information about the TCK and - the Test Harness purpose. Once you have reviewed that material, perform - the steps outlined in the remaining chapters. + the JBoss Test Harness, respectively. Once you have reviewed that + material, perform the steps outlined in the remaining chapters. </para> <itemizedlist> <listitem> @@ -88,9 +86,9 @@ <listitem> <para> <xref linkend="installation" /> - explains where to obtain the required software and how to install - it. It covers both the primary TCK components as well as tools - useful for troubleshooting tests. + explains where to obtain the required software for the CDI TCK + and how to install it. It covers both the primary TCK components + as well as tools useful for troubleshooting tests. </para> </listitem> <listitem> @@ -139,8 +137,8 @@ includes excerpts from the JBoss Test Harness Reference Guide. How to configure the JBoss Test Harness as it relates to the CDI TCK is presented in - <xref linkend="configuration" /> - however to aid in debugging or configuring the TCK in your + <xref linkend="configuration" />. + However, to aid in debugging or configuring the TCK in your environment, you may want to read in more detail how to use the JBoss Test Harness. </para> Modified: tck/trunk/doc/reference/en-US/configuration.xml =================================================================== --- tck/trunk/doc/reference/en-US/configuration.xml 2009-07-28 19:32:32 UTC (rev 3318) +++ tck/trunk/doc/reference/en-US/configuration.xml 2009-07-28 19:41:58 UTC (rev 3319) @@ -26,13 +26,13 @@ </para> <para> System properties and/or the resource - <code>META-INF/jboss-test-harness.properties</code> - , a Java properties file, are used to configure the JBoss Test Harness. + <code>META-INF/jboss-test-harness.properties</code>, + a Java properties file, are used to configure the JBoss Test Harness. You can read more about configuring the JBoss Test Harness in - <xref linkend="test-harness-properties" /> + <xref linkend="test-harness-properties" />. </para> <para> - You should set the following properties + You should set the following properties: </para> <table frame="all"> <title /> @@ -94,7 +94,7 @@ <entry> You should use the <literal>ServletTestLauncher</literal> - for Java EE6 and Java EE6 Web Profile. + for Java EE 6 and Java EE 6 Web Profile. </entry> </row> </tbody> @@ -102,8 +102,8 @@ </table> <para> To run the full TCK you must additionally implement - <literal>org.jboss.testharness.spi.Containers</literal> - , which handles deploying the test artifact to the container. An + <literal>org.jboss.testharness.spi.Containers</literal>, + which handles deploying the test artifact to the container. An implementations of this API is already available for JBoss AS 5.1. Therefore, you only need to implement this part of the porting package if you wish to use another container. @@ -161,8 +161,8 @@ </itemizedlist> <para> - Complete JavaDoc describing the requirements for implementation is - provided. + Please consult the JavaDoc for these interfaces for the implementation + requirements. </para> </section> @@ -170,12 +170,11 @@ <section> <title>Configuring TestNG to execute the TCK</title> <para> - The JBoss Test Harness is built on top of TestNG, and it is TestNG that - is responsible for selecting the tests to execute, the order of - execution, and reporting the results. Detailed TestNG documentation can - be found at - <ulink url="http://testng.org/doc/documentation-main.html">testng.o... - . + The JBoss Test Harness is built atop TestNG, and it's TestNG that is + responsible for selecting the tests to execute, the order of + execution, and reporting the results. Detailed TestNG documentation + can be found at <ulink + url="http://testng.org/doc/documentation-main.html">testng.o...;. </para> <para> The @@ -184,15 +183,15 @@ (described by the TestNG documenation as "with a <literal>testng.xml</literal> file") unmodified for an implementation to pass the TCK. This file also - allows test to be excluded from a run: + allows tests to be excluded from a run: </para> - <programlisting><![CDATA[<suite name="JSR-299 TCK" verbose="2" > - <test name="JSR-299 TCK" > + <programlisting><![CDATA[<suite name="JSR-299 TCK" verbose="2"> + <test name="JSR-299 TCK"> ... <classes> <class name="org.jboss.jsr299.tck.tests.context.application.ApplicationContextTest"> <methods> - <exclude name=" testApplicationScopeActiveDuringServiceMethod" /> + <exclude name="testApplicationScopeActiveDuringServiceMethod"/> </methods> </class> </classes> @@ -201,8 +200,8 @@ </suite>]]></programlisting> <para> - TestNG provides extensive reporting information; depending on the - build tool or IDE you use the reporting will take a different format. + TestNG provides extensive reporting information. Depending on the + build tool or IDE you use, the reporting will take a different format. Please consult the TestNG documentation and the tool documentation for more information. </para> @@ -211,12 +210,12 @@ <section> <title>Configuring your build environment to execute the TCK</title> <para> - It is beyond the scope of this guide to describe in how to set up your + It's beyond the scope of this guide to describe in how to set up your build environment to run the TCK. The JBoss Test Harness guide - describes how to Web Beans uses Maven 2 to execute the CDI TCK. See - <xref linkend="testsuite-runner" /> - . The TestNG provides extensive information on launching TestNG using - the Java, ant, Eclipse or IntellJ IDEA. + describes how Web Beans uses Maven 2 to execute the CDI TCK. See + <xref linkend="testsuite-runner" />. The TestNG documentation provides + extensive information on launching TestNG using the Java, Ant, Eclipse + or IntellJ IDEA. </para> </section> Modified: tck/trunk/doc/reference/en-US/executing.xml =================================================================== --- tck/trunk/doc/reference/en-US/executing.xml 2009-07-28 19:32:32 UTC (rev 3318) +++ tck/trunk/doc/reference/en-US/executing.xml 2009-07-28 19:41:58 UTC (rev 3319) @@ -56,8 +56,7 @@ <para> To execute the test suite using in-container mode with the JBoss TCK runner, you first have to setup JBoss AS as described in - <xref linkend="tck-in-jboss-as" /> - . + <xref linkend="tck-in-jboss-as" />. </para> <para> Then, execute the TCK runner: @@ -82,8 +81,7 @@ server automatically by setting the <literal>org.jboss.testharness.container.forceRestart</literal> to - <literal>true</literal> - . + <literal>true</literal>. </para> <para> The in-container mode uses the @@ -129,8 +127,7 @@ </para> <para> You can read more about this in - <xref linkend="dumping-test-artifacts" /> - . + <xref linkend="dumping-test-artifacts" />. </para> </section> </chapter> Modified: tck/trunk/doc/reference/en-US/installation.xml =================================================================== --- tck/trunk/doc/reference/en-US/installation.xml 2009-07-28 19:32:32 UTC (rev 3318) +++ tck/trunk/doc/reference/en-US/installation.xml 2009-07-28 19:41:58 UTC (rev 3319) @@ -15,28 +15,25 @@ which contains the TCK artifacts (the test suite binary and source, porting package API binary and source, the test suite descriptor, the audit source and report) in - <code>/artifacts</code> - , the TCK library dependencies in + <code>/artifacts</code>, the TCK library dependencies in <code>/lib</code> and documentation in - <code>/lib</code> - . + <code>/lib</code>. </para> <para> You can also download the currnet source code from - <ulink url="http://anonsvn.jboss.org/repos/webbeans/tck/trunk">JBoss SVN repository</ulink> - . + <ulink url="http://anonsvn.jboss.org/repos/webbeans/tck/trunk">JBoss SVN repository</ulink>. </para> <para> The TCK project is available in the JBoss Maven 2 repository as - <code>org.jboss.jsr299.tck:jsr299-tck-impl</code> - ; the POM defines all dependencies required to run the TCK. + <code>org.jboss.jsr299.tck:jsr299-tck-impl</code>; the POM defines all + dependencies required to run the TCK. </para> <para> Executing the TCK requires a Java EE 5 or better runtime environment (i.e., application server), to which the test artifacts are deployed - and invoked. The TCK does not depend on any particular Java EE - implementation. + and the individual tests are invoked. The TCK does not depend on any + particular Java EE implementation. </para> <para> The JSR-299: Contexts and Dependency Injection for Java EE 1.0 @@ -106,8 +103,8 @@ <literal>@Artifact</literal> annotation on the class). All test methods (i.e., methods annotated with - <literal>@Test</literal> - ) in the test class are run in the application, meaning bean discovery + <literal>@Test</literal>) + in the test class are run in the application, meaning bean discovery occurs exactly once per artifact and the same BeanManager is used by each test method in the class. </para> @@ -134,8 +131,7 @@ <listitem> <para> First, you should download JBoss AS 5.1 from the JBoss AS - <ulink url="http://jboss.org/jbossas/downloads">project page</ulink> - . + <ulink url="http://jboss.org/jbossas/downloads">project page</ulink>. </para> </listitem> <listitem> @@ -203,8 +199,7 @@ TestNG will report, via Maven, the outcome of the run, and report any failures on the console. Details can be found in - <code>target/surefire-reports/TestSuite.txt</code> - . + <code>target/surefire-reports/TestSuite.txt</code>. </para> </listitem> </itemizedlist> @@ -212,34 +207,56 @@ </tip> </section> <section id="eclipse-plugins"> - <title>Eclipse plugins</title> + <title>Eclipse Plugins</title> <para> - Eclipse, or any other IDE, is not required to execute or pass the - TCK. However an implementor may wish to execute tests in an IDE to aid + Eclipse, or any other IDE, is not required to execute or pass the TCK. + However an implementor may wish to execute tests in an IDE to aid debugging the tests. This section introduces two essential Eclipse - plugins and points you to resources explaining how to install them. + plugins, TestNG and Maven 2, and points you to resources explaining + how to install them. </para> + <section id="eclipse-testng-plugin"> + <title>TestNG Plugin</title> + <para> + The TCK is built on the JBoss Test Harness, which is in turn built on + TestNG. Therefore, having the TestNG plugin installed in Eclipse is + essential. Instructions for using the TestNG update site to add the + TestNG plugin to Eclipse are provided on the TestNG + <ulink url="http://testng.org/doc/download.html">download page</ulink>. + You can find a tutorial that explains how to use the TestNG plugin on + the TestNG + <ulink url="http://testng.org/doc/eclipse.html">Eclipse page</ulink>. + </para> + </section> + <section id="m2eclipse-plugin"> + <title>Maven 2 Plugin (m2eclipse)</title> + <para> + Another useful plugin is m2eclipse. Both the TCK project and Web Beans + are use Maven 2. Therefore, to work with these projects in Eclipse, you + may wish to have native support for Maven 2 projects, which the m2eclipse + plugin provides. Instructions for using the m2eclipse update site to + add the m2eclipse plugin to Eclipse are provided on the m2eclipse home + page. For more, read the m2eclipse + <ulink url="http://www.sonatype.com/books/m2eclipse-book/reference">... guide</ulink>. + </para> + <para> + m2eclipse is still a rather young project dealing with a complex + domain and you may run into problems using it. If that is the case, + you can alternatively use the Eclipse plugin for Maven 2 to + generate native Eclipse projects from Maven 2 projects. + </para> + <para> + If you have Maven 2 installed, you have everything you need. Just + execute the following command from any Maven 2 project to produce + the Eclipse project files. + </para> + <programlisting>mvn eclipse:eclipse</programlisting> + </section> <para> - The TCK is built on the JBoss Test Harness, which is in turn built on - TestNG. Therefore, having the TestNG plugin installed in Eclipse is - essential. Instructions for using the TestNG update site to add the - TestNG plugin to Eclipse are provided on the TestNG - <ulink url="http://testng.org/doc/download.html">download page</ulink> - . - You can find a tutorial that explains how to use the TestNG plugin on - the TestNG - <ulink url="http://testng.org/doc/eclipse.html">Eclipse page</ulink> - . + Again, the Eclipse plugins are not required to execute the TCK, but + can be very helpful when validating an implementation against the TCK + test suite and especially when using the modules from the Web Beans + project. </para> - <para> - Another useful plugin is m2eclipse. Both the TCK project and Web Beans - are use Maven 2. Therefore, to work with these projects in Eclipse, you - may wish to have support for Maven 2 project, which the m2eclipse - plugin provides. Instructions for using the m2eclipse update site to - add the m2eclipse plugin to Eclipse are provided on the m2eclipse home - page. For more, read the m2eclipse - <ulink url="http://www.sonatype.com/books/m2eclipse-book/reference">... guide</ulink> - . - </para> </section> </chapter> Modified: tck/trunk/doc/reference/en-US/introduction.xml =================================================================== --- tck/trunk/doc/reference/en-US/introduction.xml 2009-07-28 19:32:32 UTC (rev 3318) +++ tck/trunk/doc/reference/en-US/introduction.xml 2009-07-28 19:41:58 UTC (rev 3319) @@ -1,7 +1,7 @@ <?xml version='1.0' encoding='UTF-8'?> <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> <chapter id="introduction"> - <title>Introduction</title> + <title>Introduction (CDI TCK)</title> <para> This chapter explains the purpose of a TCK and identifies the @@ -20,23 +20,31 @@ </para> <para> The tests in the TCK are derived from assertions in the written - specification document. The assertions materialize as a suite of - automated tests that collectively validate whether an implementation - complies with the aforementioned assertions, and in turn the - specification. For a particular implementation to be certified, all of - the required tests must pass (the provided test suite must be run - unmodified). + specification document. The assertions are itemized in an XML + document, where they each get assigned a unique identifier, and + materialize as a suite of automated tests that collectively validate + whether an implementation complies with the aforementioned assertions, + and in turn the specification. For a particular implementation to be + certified, all of the required tests must pass (i.e., the provided + test suite must be run unmodified). </para> <para> - A TCK is entirely implementation agnostic. Ideally, it should - validate assertions by consulting the specficiation's public API. - However, when the information returned by the public API is not - low-level enough to validate the assertion, the implementation must be - consulted directly. In this case, the TCK provides an independent API - as part of a porting package which must also be implemented. Section - 1.3.4 introduces the porting package and section 4.1 covers the - requirements for implementing it. + A TCK is entirely implementation agnostic. Ideally, it should validate + assertions by consulting the specficiation's public API. However, when + the information returned by the public API is not low-level enough to + validate the assertion, the implementation must be consulted directly. + In this case, the TCK provides an independent API as part of a porting + package that enables this transparency. The porting package must be + implemented for each CDI implementation. Section 1.3.4 introduces the + porting package and section 4.1 covers the requirements for + implementing it. </para> + <note> + <para> + Sun Microsystems, Inc. will implement the porting package for the + CDI RI and test the CDI RI on the Java EE Reference Implementation. + </para> + </note> </section> <section> <title>Compatibility Testing</title> @@ -111,12 +119,12 @@ <title>About the CDI TCK</title> <para> - The CDI TCK is designed as a portable, configurable and automated - test suite for verifying the compatibility of an implementation of the + The CDI TCK is designed as a portable, configurable and automated test + suite for verifying the compatibility of an implementation of the JSR-299: Contexts and Dependency Injection for Java EE specification. - The test suite is built on TestNG and provides a series of extensions + The test suite is built atop TestNG and provides a series of extensions that allow runtime packaging and deployment of JEE artifacts for - in-container testing. + in-container testing (JBoss Test Harness). </para> <note> <para> @@ -150,7 +158,8 @@ - Software requirements for a CDI implementation are itemized in section 1.2, "Relationship to other specifications" in the CDI specification, with details provided throughout the - specification. + specification. Generally, the CDI specification targets the + Java EE 6 platform and is aligned with its specifications. </para> </listitem> <listitem> @@ -165,10 +174,10 @@ <para> <emphasis role="bold">JBoss Test Harness</emphasis> - The CDI TCK requires version 1.0.0 of the JBoss Test - Harness. The Harness is based on TestNG 5.x. You can read more - about the harness in - <xref linkend="test-harness" /> - . + Harness. The Harness is based on TestNG 5.x + (<ulink url="http://testng.org">http://testng.org</ulink>). + You can read more about the harness in + <xref linkend="test-harness" />. </para> </listitem> <listitem> @@ -176,7 +185,7 @@ <emphasis role="bold">Porting Package</emphasis> - An implementation of SPIs that are required for the test suite to run the in-container tests and at times extend the - CDI 1.0 API to provide extra information to the TCK + CDI 1.0 API to provide extra information to the TCK. </para> </listitem> <listitem> @@ -194,10 +203,7 @@ of the CDI specification is the Sun Java Platform, Enterprise Edition (Java EE) 6 reference implementation (RI). See details at Java EE 6 - ( - <ulink url="http://java.sun.com/javaee/6/docs/api/">http://java.sun... - </ulink> - ). + (<ulink url="http://java.sun.com/javaee/6/docs/api/">http://java.sun...>). </para> </listitem> </itemizedlist> @@ -215,10 +221,10 @@ </listitem> <listitem> <para> - <emphasis role="bold">TestNG 5.9</emphasis> - , the testing framework on which the JBoss Test Harness is - based and which provides the extension points for selecting an - executing the tests in the test suite. + <emphasis role="bold">TestNG 5.9</emphasis>, the testing + framework on which the JBoss Test Harness is based and which + provides the extension points for selecting an executing the + tests in the test suite. </para> </listitem> <listitem> @@ -230,10 +236,10 @@ </listitem> <listitem> <para> - <emphasis role="bold">The test suite</emphasis> - , which is a collection of TestNG tests, the TestNG test suite - descriptor and supplemental resources that configure CDI and - other software components. + <emphasis role="bold">The test suite</emphasis>, which is a + collection of TestNG tests, the TestNG test suite descriptor + and supplemental resources that configure CDI and other + software components. </para> </listitem> <listitem> @@ -241,7 +247,7 @@ <emphasis role="bold">The TCK audit</emphasis> is used to list out the assertions identified in the CDI specification. It matches the assertions to testcases in the - test suite and produces a coverage report. + test suite by unique identifier and produces a coverage report. </para> <para> The audit document is provided along with the TCK; at least @@ -260,15 +266,16 @@ </para> </listitem> </itemizedlist> - <para> - The CDI TCK has been tested with the following: - </para> <note> <para> - Sun Microsystems Inc. will implement the porting package and - test the CDI RI on the Java EE Reference Implementation + Sun Microsystems, Inc. will implement the porting package for the + CDI RI and test the CDI RI on the Java EE Reference + Implementation. </para> </note> + <para> + The CDI TCK has been tested with the following: + </para> <itemizedlist> <listitem> <para>JBoss AS 5.1.0.GA</para>