Author: pete.muir(a)jboss.org Date: 2009-07-24 12:24:33 -0400 (Fri, 24 Jul 2009) New Revision: 3199 Added: tck/trunk/doc/reference/en-US/part-background.xml tck/trunk/doc/reference/en-US/part-execution.xml tck/trunk/doc/reference/en-US/part-setup.xml tck/trunk/doc/reference/en-US/part-test-harness.xml Removed: 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 Modified: tck/trunk/doc/reference/ tck/trunk/doc/reference/en-US/configuration.xml tck/trunk/doc/reference/en-US/introduction.xml tck/trunk/doc/reference/en-US/master.xml Log: Some renames, split the Test Harness intro out Property changes on: tck/trunk/doc/reference ___________________________________________________________________ Name: svn:externals + harness https://svn.jboss.org/repos/test-utils/jboss-test-harness/trunk/doc/refer... Modified: tck/trunk/doc/reference/en-US/configuration.xml =================================================================== --- tck/trunk/doc/reference/en-US/configuration.xml 2009-07-24 15:37:02 UTC (rev 3198) +++ tck/trunk/doc/reference/en-US/configuration.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -11,7 +11,7 @@ Test Harness negotiates the execution of the tests in the container is given. </para> - <section> + <section id="test-harness-properties"> <title>JBoss Test Harness Properties</title> <para> The JBoss Test Harness allows the test suite to be launched in a @@ -275,6 +275,86 @@ </table> </section> <section> + <title>The Porting Package</title> + <para> + The CDI TCK relies on an implementation of the porting package to + function. The porting package can be divided into two parts. The first + part is comprised of extensions to the JSR-299 SPIs to allow testing of + a container. The second part must implement the JBoss Test Harness + artifact deployment APIs for deploying artifacts to the Java EE + container. + </para> + <para> + As mentioned earlier, there are times when the tests need to tap + directly into the CDI implementation to manipulate behavior or verify + results. The porting package includes a set of SPIs that provide the + TCK this level of access without tying the tests to a given + implementation. + </para> + <para> + The four SPI classes in the JSR-299 TCK are as follows: + </para> + <itemizedlist> + <listitem> + <para> + <literal>org.jboss.jsr299.tck.spi.Beans</literal> + </para> + </listitem> + <listitem> + <para> + <literal>org.jboss.jsr299.tck.spi.Contexts</literal> + </para> + </listitem> + <listitem> + <para> + <literal>org.jboss.jsr299.tck.spi.EL</literal> + </para> + </listitem> + <listitem> + <para> + <literal>org.jboss.jsr299.tck.spi.Managers</literal> + </para> + </listitem> + </itemizedlist> + + <para> + Complete JavaDoc describing the requirements for implementation is + provided. + </para> + + <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 + 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. + </para> + <note> + <para> + Red Hat Middleware LLC encourages CDI implementators to + contribute JBoss Test Harness Deployment API implementations for + other containers under the ASL license. Please contact the CDI TCK + lead. + </para> + </note> + <para> + If you wish to run the TCK in standalone mode, a CDI implementation + must provide an implementation of + <literal>org.jboss.testharness.spi.StandaloneContainers</literal> + . The CDI RI provides an implementation of this API; see the RI + reference guide. + </para> + <para> + The default configuration for the TCK uses Java properties files. The + implementation class for all of these SPIs is placed in this properties + file. Optionally, you can use system properties to configure the TCK. + Details are provided in + <xref linkend="test-harness-properties" /> + . + </para> + </section> + <section> <title>Setting up the TCK runner project</title> <para> The TCK runner project is the magic that makes everything come Modified: tck/trunk/doc/reference/en-US/introduction.xml =================================================================== --- tck/trunk/doc/reference/en-US/introduction.xml 2009-07-24 15:37:02 UTC (rev 3198) +++ tck/trunk/doc/reference/en-US/introduction.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -165,7 +165,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. + Harness. The Harness is based on TestNG 5.x. You can read more + about the harness in + <xref linkend="test-harness" /> + . </para> </listitem> <listitem> @@ -235,6 +238,22 @@ </listitem> <listitem> <para> + <emphasis role="bold">The TCK audit</emphasis> + is used to list out the assertions identified in the JSR-299 + specification. It matches the assertions to testcases in the + test suite and produces a coverage report. + </para> + <para> + The audit document is provided along with the TCK; at least + 75% of assertions are tested. Each assertion is defined with a + reference to a chapter, section and paragraph from the + specification document, making it easy for the implementor to + locate the language in the specification document that + supports the feature being tested. + </para> + </listitem> + <listitem> + <para> <emphasis role="bold">TCK documentation</emphasis> accompanied by release notes identifying updates between versions. @@ -261,256 +280,13 @@ <para>Red Hat Enterprise Linux 5.2</para> </listitem> </itemizedlist> - </section> - <section> - <title>The JBoss Test Harness</title> <para> - The CDI TCK leverages the JBoss Test Harness. The JBoss Test - Harness is a testing framework based on TestNG that provides a - series of extensions that allow runtime packaging and deployment of - Java EE artifacts (EAR or WAR) for in-container testing. It's - important to note that the JBoss Test Harness has no relation with, - or dependency on the JBoss Application Server (JBoss AS). - </para> - <para> CDI supports Java EE 5, Java EE 6, Java EE 6 Web Profile and the Embeddable EJB 3.1. The TCK will run on any of these runtimes, but is only part of the CTS for Java EE 6, Java EE 6 Web Profile and Embeddable EJB 3.1 (SUN: Please confirm these are the CTS the CDI TCK will run in). </para> - <note> - <para> - You'll often see the term - <emphasis role="italic">in-container</emphasis> - used in this reference guide. This term refers to running the - test suite in any of the aforementioned environments, whilst - <emphasis role="italic">standalone</emphasis> - refers to running the tests outside the container via a CDI - implementation-specific standalone bootstrap. The standalone mode - only runs those tests which the CDI RI can run without deployment - in a Java EE container. - </para> - </note> - <para> - The last thing Java developers want is yet another testing - framework to make their life more complicated. What they do want is - a good integration with their Integrated Development Environment - (IDE). These days, if a tool doesn&apos;t have an IDE plugin, then - it won&apos;t get the attention it deserves. That&apos;s why the - JBoss Test Harness is built entirely upon TestNG. TestNG is one of - the two prominent test frameworks for Java and TestNG plugins are - available for all major IDEs (with the exception of NetBeans) and - build tools (Ant and Maven 2). - </para> - <para> - Because it leverages the existing TestNG ecosystem, there is no - need for a special test launcher for the JBoss Test Harness, and in - turn the JSR-299 TCK. You simply use the IDE or build tool of your - choice. You also get reporting and debugging for free. - </para> - <para> - The JBoss Test Harness supports the following features: - </para> - <itemizedlist> - <listitem> - <para> - Test activation via any method supported by the TestNG - configuration descriptor (package, group, class) - </para> - </listitem> - <listitem> - <para> - Exclusion of in-container tests in standalone mode - </para> - </listitem> - <listitem> - <para> - Exclusion of individual tests labeled as under - investigation - </para> - </listitem> - <listitem> - <para> - Integration with any TestNG plugin (Eclipse, IntelliJ, - NetBeans, Ant, Maven) - </para> - </listitem> - <listitem> - <para> - Automated reporting capability as provided by TestNG - </para> - </listitem> - <listitem> - <para> - Standalone and in-container test mode - </para> - </listitem> - <listitem> - <para> - Container pluggability - </para> - </listitem> - <listitem> - <para> - Declarative packaging of additional resources and classes - in artifact - </para> - </listitem> - <listitem> - <para> - Declarative deployment exception trapping - </para> - </listitem> - <listitem> - <para> - Artifact dumping for failure and packaging analysis - </para> - </listitem> - </itemizedlist> - <para> - A test is designated by a method annotated with - <literal&gt;(a)org.testng.annotations.Test&lt;/literal&gt; - in a class which extends - <literal>org.jboss.jsr299.tck.AbstractJSR299Test</literal> - and is annotated with - <literal&gt;(a)org.jboss.testharness.impl.packaging.Artifact&lt;/literal&gt; - . - </para> - <para> - The - <literal>@Test</literal> - annotation is provided by TestNG, the - <literal>@Artifact</literal> - annotation is provided by the JBoss Test Harness and the - <literal>AbstractJSR299Test</literal> - is part of the JSR-299 TCK. There is a one-to-one mapping between a - TestNG test class and an artifact. The packaging type is defined by - the - <literal&gt;(a)org.jboss.testharness.impl.packaging.Packaging&lt;/literal&gt; - annotation on the test class, defaulting to a WAR if not specified. - </para> - <para> - Prior to executing the tests for a given class, the JBoss Test - Harness packages the class as a deployable artifact (EAR or WAR), - along with any extra resources specified, and deploys the artifact - to the container. The test execution and results are negotatied via - HTTP communication using a thin layer over the TestNG test launcher. - The test harness can also catch and affirm expected deployment - exceptions. This setup and tear down activity is provided by the - super class - <literal>org.jboss.jsr299.tck.AbstractJSR299Test</literal> - , which all TCK test classes must extend. - </para> - <para> - If the annotation - <literal&gt;(a)org.jboss.testharness.impl.packaging.IntegrationTest - </literal> - is not present on the test class, then it means the test class can - be executed in standalone mode. In standalone mode, the deployable - artifact is assembled on the local classpath and the tests execute - in the same JVM as the launcher, just as though it were a regular - TestNG test case. The standalone mode is provided merely for - convenience and efficiency. - </para> - <para> - Chapter 4 details how to run the TCK test suite using the JBoss - Test Harness. - </para> </section> - <section> - <title>The Porting Package</title> - <para> - The CDI TCK relies on an implementation of the porting package to - function. The porting package can be divided into two parts. The - first part is comprised of extensions to the JSR-299 SPIs to allow - testing of a container. The second part must implement he JBoss Test - Harness artifact deployment APIs for deploying artifacts to the Java - EE container. - </para> - <para> - As mentioned earlier, there are times when the tests need to tap - directly into the CDI implementation to manipulate behavior or - verify results. The porting package includes a set of SPIs that - provide the TCK this level of access without tying the tests to a - given implementation. - </para> - <para> - The four SPI classes in the JSR-299 TCK are as follows: - </para> - <itemizedlist> - <listitem> - <para> - <literal>org.jboss.jsr299.tck.spi.Beans</literal> - </para> - </listitem> - <listitem> - <para> - <literal>org.jboss.jsr299.tck.spi.Contexts</literal> - </para> - </listitem> - <listitem> - <para> - <literal>org.jboss.jsr299.tck.spi.EL</literal> - </para> - </listitem> - <listitem> - <para> - <literal>org.jboss.jsr299.tck.spi.Managers</literal> - </para> - </listitem> - </itemizedlist> - - <para> - Complete JavaDoc describing the requirements for implementation - is provided. - </para> - - <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 - 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. - </para> - <note> - <para> - Red Hat Middleware LLC encourages CDI implementators to - contribute JBoss Test Harness Deployment API implementations for - other containers under the ASL license. Please contact the CDI - TCK lead. - </para> - </note> - <para> - If you wish to run the TCK in standalone mode, a CDI implementation - must provide an implementation of - <literal>org.jboss.testharness.spi.StandaloneContainers</literal> - . The CDI RI provides an implementation of this API; see the RI - reference guide. - </para> - <para> - The default configuration for the TCK uses Java properties files. - The implementation class for all of these SPIs is placed in this - properties file. Optionally, you can use system properties to - configure the TCK. Details are provided in section 4.1. - </para> - </section> - <section> - <title>TCK Audit Tool</title> - <para> - The TCK audit is used to list out the assertions identified in - the JSR-299 specification. It uses Java annotation processing to - match the assertions to testcases in the test suite and produce a - coverage report. - </para> - <para> - The audit document is provided along with the TCK; at least 75% - of assertions are tested. Each assertion is defined with a reference - to a chapter, section and paragraph from the specification document, - making it easy for the implementor to locate the language in the - specification document that supports the feature being tested. - </para> - </section> </section> </chapter> Modified: tck/trunk/doc/reference/en-US/master.xml =================================================================== --- tck/trunk/doc/reference/en-US/master.xml 2009-07-24 15:37:02 UTC (rev 3198) +++ tck/trunk/doc/reference/en-US/master.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -3,7 +3,8 @@ <book lang="en"> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Info.xml"/> <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Book_Preface.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part1-background.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part2-setup.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part3-execution.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part-background.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part-test-harness.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part-setup.xml"/> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="part-execution.xml"/> </book> Copied: tck/trunk/doc/reference/en-US/part-background.xml (from rev 3198, tck/trunk/doc/reference/en-US/part1-background.xml) =================================================================== --- tck/trunk/doc/reference/en-US/part-background.xml (rev 0) +++ tck/trunk/doc/reference/en-US/part-background.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -0,0 +1,15 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> +<part> + <title>Getting Acquainted with the TCK</title> + + <partintro> + <para> + The CDI TCK must be used to ensure that your implementation + conforms to the CDI specification. This part introduces the TCK, + gives some background about its purpose and states the requirements for + passing the TCK. + </para> + </partintro> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml" /> +</part> Copied: tck/trunk/doc/reference/en-US/part-execution.xml (from rev 3198, tck/trunk/doc/reference/en-US/part3-execution.xml) =================================================================== --- tck/trunk/doc/reference/en-US/part-execution.xml (rev 0) +++ tck/trunk/doc/reference/en-US/part-execution.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -0,0 +1,18 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> +<part> + <title>Executing and Debugging Tests</title> + <partintro> + <para> + 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 implementation. Finally, you learn how to debug tests from the + test suite in Eclipse. + </para> + </partintro> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="executing.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eclipse-running.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eclipse-debugging.xml" /> +</part> Copied: tck/trunk/doc/reference/en-US/part-setup.xml (from rev 3198, tck/trunk/doc/reference/en-US/part2-setup.xml) =================================================================== --- tck/trunk/doc/reference/en-US/part-setup.xml (rev 0) +++ tck/trunk/doc/reference/en-US/part-setup.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -0,0 +1,14 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> +<part> + <title>Installation and Setup</title> + <partintro> + <para> + In this part you learn where to obtain the JSR-299 TCK and supporting software. + You are then presented with recommendations of how to organize and + configure the software so that you are ready to execute the TCK. + </para> + </partintro> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml" /> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="configuration.xml" /> +</part> Added: tck/trunk/doc/reference/en-US/part-test-harness.xml =================================================================== --- tck/trunk/doc/reference/en-US/part-test-harness.xml (rev 0) +++ tck/trunk/doc/reference/en-US/part-test-harness.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -0,0 +1,12 @@ +<?xml version='1.0' encoding='UTF-8'?> +<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> +<part id="test-harness"> + <title>JBoss Test Harness</title> + <partintro> + <para> + In this part you learn about the JBoss Test Harness. You can view the + entire JBoss Test Harness Reference Guide at <ulink url="">TODO</ulink>. + </para> + </partintro> + <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="harness/introduction.xml" /> +</part> Property changes on: tck/trunk/doc/reference/en-US/part-test-harness.xml ___________________________________________________________________ Name: svn:mime-type + text/plain Deleted: tck/trunk/doc/reference/en-US/part1-background.xml =================================================================== --- tck/trunk/doc/reference/en-US/part1-background.xml 2009-07-24 15:37:02 UTC (rev 3198) +++ tck/trunk/doc/reference/en-US/part1-background.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -1,15 +0,0 @@ -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<part> - <title>Getting Acquainted with the TCK</title> - - <partintro> - <para> - The CDI TCK must be used to ensure that your implementation - conforms to the CDI specification. This part introduces the TCK, - gives some background about its purpose and states the requirements for - passing the TCK. - </para> - </partintro> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="introduction.xml" /> -</part> Deleted: tck/trunk/doc/reference/en-US/part2-setup.xml =================================================================== --- tck/trunk/doc/reference/en-US/part2-setup.xml 2009-07-24 15:37:02 UTC (rev 3198) +++ tck/trunk/doc/reference/en-US/part2-setup.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -1,14 +0,0 @@ -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<part> - <title>Installation and Setup</title> - <partintro> - <para> - In this part you learn where to obtain the JSR-299 TCK and supporting software. - You are then presented with recommendations of how to organize and - configure the software so that you are ready to execute the TCK. - </para> - </partintro> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="installation.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="configuration.xml" /> -</part> Deleted: tck/trunk/doc/reference/en-US/part3-execution.xml =================================================================== --- tck/trunk/doc/reference/en-US/part3-execution.xml 2009-07-24 15:37:02 UTC (rev 3198) +++ tck/trunk/doc/reference/en-US/part3-execution.xml 2009-07-24 16:24:33 UTC (rev 3199) @@ -1,18 +0,0 @@ -<?xml version='1.0' encoding='UTF-8'?> -<!DOCTYPE part PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ ]> -<part> - <title>Executing and Debugging Tests</title> - <partintro> - <para> - 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 implementation. Finally, you learn how to debug tests from the - test suite in Eclipse. - </para> - </partintro> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="executing.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eclipse-running.xml" /> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="eclipse-debugging.xml" /> -</part>