From portal-commits at lists.jboss.org Fri Oct 19 08:28:58 2007
Content-Type: multipart/mixed; boundary="===============9102132251543558372=="
MIME-Version: 1.0
From: portal-commits at lists.jboss.org
To: portal-commits at lists.jboss.org
Subject: [portal-commits] JBoss Portal SVN: r8715 - in modules/test/trunk:
 unit/src/main/org/jboss/unit/api/pojo/annotations and 1 other directories.
Date: Fri, 19 Oct 2007 08:28:58 -0400
Message-ID: <E1IiqyI-0008KC-Fg@committer01.frg.pub.inap.atl.jboss.com>

--===============9102132251543558372==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

Author: julien(a)jboss.com
Date: 2007-10-19 08:28:58 -0400 (Fri, 19 Oct 2007)
New Revision: 8715

Modified:
   modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml
   modules/test/trunk/unit/src/main/org/jboss/unit/api/pojo/annotations/Des=
cription.java
   modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProviderSup=
port.java
Log:
more documentation

Modified: modules/test/trunk/docs/user-guide/en/modules/pojotesting.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
--- modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml	2007-10-1=
9 10:42:51 UTC (rev 8714)
+++ modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml	2007-10-1=
9 12:28:58 UTC (rev 8715)
@@ -413,18 +413,237 @@
 =

       <sect2>
          <title><interfacename>@Description</interfacename></title>
-         <para></para>
+         <para>The <interfacename>@Description</interfacename> annotation =
can be used to annotate a test class, a test
+         case of a test parameter and provide a description</para>
+
+         <example>
+         <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Parameter;
+import org.jboss.unit.api.pojo.annotations.Description;
+import org.jboss.unit.api.pojo.annotations.Test;
+
+(a)Description("A test suite")
+public class MyTest
+{
+
+   private String foo;
+
+   @Parameter
+   @Description("A test parameter")
+   public void setFoo(String foo)
+   {
+      this.foo =3D foo;
+   }
+
+   @Test
+   @Description("A test case")
+   public void test()
+   {
+   }
+}
+]]></programlisting>
+            <caption>
+               <para>A test described</para>
+            </caption>
+         </example>
+
       </sect2>
 =

       <sect2>
          <title><interfacename>@Tag</interfacename></title>
-         <para></para>
+         <para>The <interfacename>@Tag</interfacename> annotation allow to=
 tag a tested item with keywords. The main usage
+         of keywords is at runtime in order to provide filtering of tests.=
 It is very useful whenever you just want
+         to execute a subset of the tests based on a set of keywords.</par=
a>
+
+         <example>
+         <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Keyword;
+import org.jboss.unit.api.pojo.annotations.Test;
+
+(a)Tag({"foo", "bar"})
+public class MyTest
+{
+   @Test
+   @Tag({"foo"})
+   public void test()
+   {
+   }
+}
+]]></programlisting>
+            <caption>
+               <para>A test annotated with keywords</para>
+            </caption>
+         </example>
+
       </sect2>
 =

    </sect1>
 =

    <sect1>
       <title>Integration with JBoss Microcontainer</title>
+
+      <para>The JBoss Microcontainer provides a lighweight container for m=
anaging POJOs, their deployment and
+      configuration. The integration within JBoss Unit provides a powerful=
 way to setup complex assembly of
+      POJOs that will be part of unit tests.</para>
+      <para>This section will provide the general syntax and an example of=
 usage, for further details concerning
+      JBoss Microcontainer you should look at its documentation.</para>
+
+      <sect2>
+         <title>Triggering a microcontainer boostrap with the <interfacena=
me>@Bootstrap</interfacename> annotation</title>
+         <para>The main usage of JBoss Microcontainer is done through the =
<interfacename>@Bootstrap</interfacename> annotation.
+         It has a <parameter>resourceName</parameter> parameter which indi=
cates the resource name of the microcontainer
+         bootstrap file.</para>
+         <para>The current POJO being tested will be inserted in the micro=
container kernel and it is possible to reference it
+            in the bootstrap file under the special <literal>TestCase</lit=
eral> name. It is possible to override the name
+            using the <parameter>beanName</parameter> parameter of the <in=
terfacename>@Bootstrap</interfacename> annotation. There
+            are several ways to leverage this:
+            <itemizedlist>
+               <listitem>Inject the test case in a bean</listitem>
+               <listitem>Inject a property of the test case in a bean such=
 as a parameter of the test case</listitem>
+               <listitem>Inject a bean in the test case POJO using JBoss M=
icrocontainer annotations</listitem>
+            </itemizedlist>
+         </para>
+      </sect2>
+
+      <sect2>
+         <title>Example</title>
+         <para>In this example we will show how to create a parameterized =
test case that bootstrap a bean using
+            the microcontainer. The boostrapped bean will be configured fr=
om the test case parameters and then
+            will be injected in the test case.</para>
+
+         <example>
+         <programlisting><![CDATA[
+public class MyService
+{
+
+   private String dataSourceName;
+
+   public String getDataSourceName()
+   {
+      return dataSourceName;
+   }
+
+   public void setDataSourceName(String dataSourceName)
+   {
+      this.dataSourceName =3D dataSourceName;
+   }
+
+   public void start()
+   {
+      System.out.println("MyService start for data source " + dataSourceNa=
me);
+   }
+
+   public void stop()
+   {
+      System.out.println("MyService stop");
+   }
+
+}
+]]></programlisting>
+            <caption>
+               <para>The service</para>
+            </caption>
+         </example>
+
+         <example>
+         <programlisting><![CDATA[
+(a)Bootstrap(resourceName =3D"/jboss-beans.xml")
+public class MyTest
+{
+
+   private MyService service;
+   private String dataSourceName;
+
+   public MyService getService()
+   {
+      return service;
+   }
+
+   @Inject(bean=3D"Service")
+   public void setService(MyService service)
+   {
+      this.service =3D service;
+   }
+
+   public String getDataSourceName()
+   {
+      return dataSourceName;
+   }
+
+   @Parameter
+
+   public void setDataSourceName(String dataSourceName)
+   {
+      this.dataSourceName =3D dataSourceName;
+   }
+
+   @Test
+   public void test()
+   {
+      System.out.println("MyTest test with service " + service);
+   }
+}
+]]></programlisting>
+            <caption>
+               <para>The test suite</para>
+            </caption>
+         </example>
+
+         <para>Our tested system is composed of a service and a test suite=
. The service is configured from
+         a <parameter>dataSourceName</parameter> parameter that will be in=
jected from the test suite <parameter>dataSourceName</parameter>
+         corresponding property. The test suite is parameterized with the =
<parameter>dataSourceName</parameter> parameter that will
+         be set by JBoss Unit. The test suite interacts with the microcont=
ainer thanks to the <interfacename>@Bootstrap</interfacename>
+         annotation configured to use the file available from the classpat=
h under the name <literal>/jboss-beans.xml</literal>. The
+         <interfacename>@Inject</interfacename> annotation is a microconta=
iner annotation that will trigger the injection
+         of the service in the test case.</para>
+
+         <example>
+         <programlisting><![CDATA[
+<?xml version=3D"1.0" encoding=3D"UTF-8"?>
+<deployment xmlns:xsi=3D"http://www.w3.org/2001/XMLSchema-instance"
+            xsi:schemaLocation=3D"urn:jboss:bean-deployer:2.0 bean-deploye=
r_2_0.xsd"
+            xmlns=3D"urn:jboss:bean-deployer:2.0">
+
+   <bean name=3D"Service" class=3D"org.jboss.test.unit.mc.MyService">
+      <property name=3D"dataSourceName"><inject
+         bean=3D"TestCase"
+         property=3D"dataSourceName"
+         state=3D"Instantiated"/></property>
+   </bean>
+
+</deployment>
+]]></programlisting>
+            <caption>
+               <para>The <filename>jboss-beans.xml</filename> file</para>
+            </caption>
+         </example>
+
+         <note>The injection of the <parameter>dataSourceName</parameter> =
property from the <literal>TestCase</literal> bean
+         requires to add the <parameter>state</parameter> attribute with t=
he value <literal>Instantiated</literal>. Without
+         this we would have a a bidirectional dependency between the servi=
ce and the test case and the kernel would not
+         be able to resolve it: the test case wants the injection of the s=
ervice and the service wants the injection
+         of a portion of the test case state. Using the <literal>Instantia=
ted</literal> state tells the kernel to use
+         the test case bean when it is instantiated and that allows the re=
solution of all the dependencies.</note>
+
+         <para>One of the benefit of using JBoss Microcontainer is that it=
 takes care of the overral orchestration of the whole setup
+            and resolve the dependencies and configuration issues. When JB=
oss Unit executes the test case the following sequence happens:
+            <itemizedlist>
+               <listitem>An instance of <classname>MyTest</classname> is c=
reated by JBoss Unit</listitem>
+               <listitem>JBoss Unit configures the instance and set the <p=
arameter>dataSourceName</parameter> property</listitem>
+               <listitem>JBoss Unit creates a new microcontainer kernel an=
d registers the <classname>MyTest</classname> instance under the <literal>T=
estCase</literal> name</listitem>
+               <listitem>JBoss Unit deploys the <filename>jboss-beans.xml<=
/filename> file</listitem>
+               <listitem>JBoss MC creates an instance of the <classname>My=
Service</classname> service and configures it with the test case <parameter=
>dataSourceName</parameter>
+               value</listitem>
+               <listitem>JBoss MC starts the service</listitem>
+               <listitem>JBoss MC inject the service in the test case</lis=
titem>
+            </itemizedlist>
+         </para>
+
+         <para>Once the test is finished a shutdown of the kernel will be =
done that will trigger the stopping and destruction of the
+         involved services.</para>
+
+      </sect2>
+
    </sect1>
 =

 </chapter>

Modified: modules/test/trunk/unit/src/main/org/jboss/unit/api/pojo/annotati=
ons/Description.java
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/test/trunk/unit/src/main/org/jboss/unit/api/pojo/annotations/De=
scription.java	2007-10-19 10:42:51 UTC (rev 8714)
+++ modules/test/trunk/unit/src/main/org/jboss/unit/api/pojo/annotations/De=
scription.java	2007-10-19 12:28:58 UTC (rev 8715)
@@ -38,6 +38,6 @@
 public @interface Description
 {
 =

-   String description();
+   String value();
 =

 }

Modified: modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProv=
iderSupport.java
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProviderSu=
pport.java	2007-10-19 10:42:51 UTC (rev 8714)
+++ modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProviderSu=
pport.java	2007-10-19 12:28:58 UTC (rev 8715)
@@ -118,7 +118,7 @@
 =

       //
       Description descriptionAnnotation =3D ((AnnotatedElement)testClass).=
getAnnotation(Description.class);
-      String suiteDescription =3D descriptionAnnotation !=3D null ? descri=
ptionAnnotation.description() : "";
+      String suiteDescription =3D descriptionAnnotation !=3D null ? descri=
ptionAnnotation.value() : "";
       if (suiteDescription.length() =3D=3D 0)
       {
          suiteDescription =3D "Test of class " + testClass.getName();
@@ -226,7 +226,7 @@
 =

             //
             Description descriptionMethodAnnotation =3D method.getAnnotati=
on(Description.class);
-            String description =3D descriptionMethodAnnotation !=3D null ?=
 descriptionMethodAnnotation.description() : "";
+            String description =3D descriptionMethodAnnotation !=3D null ?=
 descriptionMethodAnnotation.value() : "";
             if (description.length() =3D=3D 0)
             {
                description =3D "Parameter " + name;
@@ -361,7 +361,7 @@
 =

                   //
                   Description descriptionArgumentParameterAnnotation =3D (=
Description)parameterAnnotationMap.get(Description.class);
-                  String description =3D descriptionArgumentParameterAnnot=
ation !=3D null ? descriptionArgumentParameterAnnotation.description() : "";
+                  String description =3D descriptionArgumentParameterAnnot=
ation !=3D null ? descriptionArgumentParameterAnnotation.value() : "";
                   if (description.length() =3D=3D 0)
                   {
                      description =3D "Method parameter " + name;
@@ -385,7 +385,7 @@
 =

             //
             Description descriptionMethodAnnotation =3D method.getAnnotati=
on(Description.class);
-            String description =3D descriptionMethodAnnotation !=3D null ?=
 descriptionMethodAnnotation.description() : "";
+            String description =3D descriptionMethodAnnotation !=3D null ?=
 descriptionMethodAnnotation.value() : "";
             if (description.length() =3D=3D 0)
             {
                description =3D "Test of method " + method.getName();


--===============9102132251543558372==--