From portal-commits at lists.jboss.org Fri Oct 19 06:42:51 2007
Content-Type: multipart/mixed; boundary="===============3107500700731743195=="
MIME-Version: 1.0
From: portal-commits at lists.jboss.org
To: portal-commits at lists.jboss.org
Subject: [portal-commits] JBoss Portal SVN: r8714 -
 modules/test/trunk/docs/user-guide/en/modules.
Date: Fri, 19 Oct 2007 06:42:51 -0400
Message-ID: <E1IipJb-0005nr-9C@committer01.frg.pub.inap.atl.jboss.com>

--===============3107500700731743195==
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 06:42:51 -0400 (Fri, 19 Oct 2007)
New Revision: 8714

Modified:
   modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml
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 09:53:23 UTC (rev 8713)
+++ modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml	2007-10-1=
9 10:42:51 UTC (rev 8714)
@@ -96,7 +96,8 @@
 =

          <sect3>
             <title><methodname>assertNull</methodname></title>
-            <programlisting><![CDATA[
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
@@ -106,123 +107,324 @@
    }
 }
 ]]></programlisting>
-            <para>Assert that the argument is null.</para>
+               <caption>
+                  <para>Assert that the argument is <literal>null</literal=
>.</para>
+               </caption>
+            </example>
          </sect3>
 =

          <sect3>
             <title><methodname>assertNotNull</methodname></title>
-            <programlisting><![CDATA[
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
    public void test()
    {
+      assertNotNull("foo");
       String s =3D assertNotNull("foo");
    }
 }
 ]]></programlisting>
-            <para>Assert that the argument is not null. The method relies =
on the generics and returns the same type
-            of the argument type in order to avoid a type cast, improving =
the readability of the code.</para>
+               <caption>
+                  <para>Assert that the argument is not <literal>null</lit=
eral>. The method relies on the generics and returns the same type
+                  of the argument type in order to avoid a type cast, impr=
oving the readability of the code.</para>
+               </caption>
+            </example>
          </sect3>
 =

          <sect3>
-            <title><methodname></methodname></title>
-            <programlisting><![CDATA[
+            <title><methodname>assertEquals</methodname></title>
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
    public void test()
    {
+      assertEquals("foo", "foo");
+      assertEquals(null, null);
+      assertEquals(1, 1);
+      assertEquals(true, true);
+      assertEquals(new String[]{"foo"}, new String[]{"foo"});
    }
 }
 ]]></programlisting>
-            <para>.</para>
+               <caption>
+                  <para>Assert that the arguments are either <literal>null=
</literal> or both are non <literal>null</literal> and the invocation of th=
e first argument
+                     <methodname>equals</methodname> method with the secon=
d argument as parameter returns true.</para>
+               </caption>
+            </example>
          </sect3>
 =

          <sect3>
-            <title><methodname></methodname></title>
-            <programlisting><![CDATA[
+            <title><methodname>assertNotEquals</methodname></title>
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
    public void test()
    {
+      assertNotEquals("foo", "bar");
+      assertNotEquals("foo", null);
+      assertNotEquals(null, "bar");
+      assertNotEquals(true, false);
+      assertNotEquals(1, 2);
    }
 }
 ]]></programlisting>
-            <para>.</para>
+               <caption>
+                  <para>Assert that either one argument is <literal>null</=
literal> and the other is not or that both arguments are non
+                     <literal>null</literal> and the invocation of the fir=
st argument <methodname>equals</methodname> method returns false.</para>
+               </caption>
+            </example>
          </sect3>
 =

          <sect3>
-            <title><methodname></methodname></title>
-            <programlisting><![CDATA[
+            <title><methodname>assertSame</methodname></title>
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
    public void test()
    {
+      Object o =3D new Object();
+      assertSame(o, o);
+      assertSame(null, null);
    }
 }
 ]]></programlisting>
-            <para>.</para>
+               <caption>
+                  <para>Assert that the arguments are either <literal>null=
</literal> or are non <literal>null</literal> and have the same reference.<=
/para>
+               </caption>
+            </example>
          </sect3>
 =

          <sect3>
-            <title><methodname></methodname></title>
-            <programlisting><![CDATA[
+            <title><methodname>assertNotSame</methodname></title>
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
    public void test()
    {
+      assertNotSame(new String("foo"), "foo");
+      assertNotSame("foo", null);
+      assertNotSame(null, "bar");
    }
 }
 ]]></programlisting>
-            <para>.</para>
+               <caption>
+                  <para>Assert that either one argument is <literal>null</=
literal> and the other is not or that both arguments
+                  are non <literal>null</literal> but do not share the sam=
e reference.</para>
+               </caption>
+            </example>
          </sect3>
 =

          <sect3>
-            <title><methodname></methodname></title>
-            <programlisting><![CDATA[
+            <title><methodname>assertInstanceOf</methodname></title>
+            <example>
+               <programlisting><![CDATA[
 public class MyTest
 {
    @Test
    public void test()
    {
+      assertInstanceOf(o, String.class);
+      String s =3D assertInstanceOf(o, String.class);
    }
 }
 ]]></programlisting>
-            <para>.</para>
+               <caption>
+                  <para>Assert that an object implements or extends the sp=
ecified class object. It leverages the generics to
+                  have the same return type than the class argument which =
allow to reuse the object with its asserted class
+                  directly.</para>
+               </caption>
+            </example>
          </sect3>
+      </sect2>
+   </sect1>
 =

-         <sect3>
-            <title><methodname></methodname></title>
+   <sect1>
+      <title>Annotations</title>
+      <para>So far we have covered only the <interfacename>@Test</interfac=
ename> annotation, in this chapter we will
+      review the other annotations available.</para>
+
+      <sect2>
+         <title><interfacename>@Parameter</interfacename></title>
+         <para>It is often interesting to run several times the same test =
with different initial conditions. The
+            <interfacename>@Parameter</interfacename> annotation can be us=
ed to provide an initial state to the tests.
+            It is possible to annotate Javabean property setters or test c=
ase method arguments. When a property is annotated,
+            the parameter is scoped for all test cases contained in the PO=
JO. Note that it is allowed to override
+            the name of the parameter using the <parameter>name</parameter=
> argument of the annotation.</para>
+
+         <example>
             <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Test;
+import org.jboss.unit.api.pojo.annotations.Parameter;
+import static org.jboss.unit.api.Assert.*;
+
 public class MyTest
 {
+
+   private String foo;
+   private String juu;
+
+   @Parameter
+   public void setFoo(String foo)
+   {
+      this.foo =3D foo;
+   }
+
+   @Parameter(name =3D "bar")
+   public void setJuu(String juu)
+   {
+      this.juu =3D juu;
+   }
+
    @Test
    public void test()
    {
+      assertEquals(foo, bar);
    }
 }
 ]]></programlisting>
-            <para>.</para>
-         </sect3>
+            <caption>
+               <para>A POJO with annotated Javabean property setters</para>
+            </caption>
+         </example>
 =

-         <sect3>
-            <title><methodname></methodname></title>
+         <para>When a test case method argument is annotated, only the tes=
t case will have access to the parameter. In that
+            use case, the optional annotation parameter <parameter>name</p=
arameter> becomes mandatory.</para>
+
+         <example>
             <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Test;
+import org.jboss.unit.api.pojo.annotations.Parameter;
+import static org.jboss.unit.api.Assert.*;
+
 public class MyTest
 {
+
+   private String foo;
+
+   @Parameter
+   public void setFoo(String foo)
+   {
+      this.foo =3D foo;
+   }
+
    @Test
+   public void test(@Parameter(name =3D "bar") String bar)
+   {
+      assertEquals(foo, bar);
+   }
+}
+]]></programlisting>
+            <caption>
+               <para>A POJO with annotated Javabean property setters</para>
+            </caption>
+         </example>
+
+      </sect2>
+
+      <sect2>
+         <title><interfacename>@Test</interfacename></title>
+         <para>The <interfacename>@Test</interfacename> annotation is used=
 to annotate a test case method that
+         is invoked at runtime by the JBoss Unit POJO extension. The metho=
d must be public, non static, non abstract
+         and should have only arguments annotated with an <interfacename>@=
Parameter</interfacename> annotation.</para>
+
+         <para>By default the test name is the name of the
+            method but the annotation can be parameterized with a <paramet=
er>name</parameter> argument that
+            will override the default name.</para>
+
+         <example>
+            <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Test;
+
+public class MyTest
+{
+
+   @Test
    public void test()
    {
    }
+
+   @Test(name =3D "test2")
+   public void test1()
+   {
+   }
+
+   @Test
+   public void test(@Parameter(name =3D "bar") String bar)
+   {
+   }
 }
 ]]></programlisting>
-            <para>.</para>
-         </sect3>
+            <caption>
+               <para>A POJO with several test cases</para>
+            </caption>
+         </example>
 =

       </sect2>
+
+      <sect2>
+         <title><interfacename>@Create</interfacename> and <interfacename>=
@Destroy</interfacename></title>
+         <para>The <interfacename>@Create</interfacename> and <interfacena=
me>@Destroy</interfacename> annotations
+         are targetted for public, non static, methods that will be invoke=
d to provide the POJO notifications
+         of the test life cycle.</para>
+         <para>The create method will be invoked prior any test case and w=
ill have access to POJO scoped parameters.
+         It is allowed to fail by throwing any kind of throwable and will =
make the test fail whenever it happens. If the
+         create method fails the test case method will not be invoked.</pa=
ra>
+         <para>The destroy method is guaranteed to be always invoked wheth=
er the test pass or fails.</para>
+         <example>
+         <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Create;
+import org.jboss.unit.api.pojo.annotations.Destroy;
+import org.jboss.unit.api.pojo.annotations.Test;
+
+public class MyTest
+{
+   @Create
+   public void create()
+   {
+   }
+
+   @Test
+   public void test()
+   {
+   }
+
+   @Destroy
+   public void destroy()
+   {
+   }
+}
+]]></programlisting>
+            <caption>
+               <para>A POJO aware of its life cycle</para>
+            </caption>
+         </example>
+      </sect2>
+
+      <sect2>
+         <title><interfacename>@Description</interfacename></title>
+         <para></para>
+      </sect2>
+
+      <sect2>
+         <title><interfacename>@Tag</interfacename></title>
+         <para></para>
+      </sect2>
+
    </sect1>
+
+   <sect1>
+      <title>Integration with JBoss Microcontainer</title>
+   </sect1>
+
 </chapter>


--===============3107500700731743195==--