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 =================================================================== --- modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml 2007-10-19 09:53:23 UTC (rev 8713) +++ modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml 2007-10-19 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 = 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</literal>. 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> + </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 the first argument + <methodname>equals</methodname> method with the second 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 first 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 = 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 same 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 = assertInstanceOf(o, String.class); } } ]]></programlisting> - <para>.</para> + <caption> + <para>Assert that an object implements or extends the specified 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</interfacename> 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 used to provide an initial state to the tests. + It is possible to annotate Javabean property setters or test case method arguments. When a property is annotated, + the parameter is scoped for all test cases contained in the POJO. 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 = foo; + } + + @Parameter(name = "bar") + public void setJuu(String juu) + { + this.juu = 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 test case will have access to the parameter. In that + use case, the optional annotation parameter <parameter>name</parameter> 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 = foo; + } + @Test + public void test(@Parameter(name = "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 method 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 <parameter>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 = "test2") + public void test1() + { + } + + @Test + public void test(@Parameter(name = "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 <interfacename>@Destroy</interfacename> annotations + are targetted for public, non static, methods that will be invoked to provide the POJO notifications + of the test life cycle.</para> + <para>The create method will be invoked prior any test case and will 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.</para> + <para>The destroy method is guaranteed to be always invoked whether 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>