7:28 a.m.
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/Description.java
modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProviderSupport.java
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 10:42:51 UTC
(rev 8714)
+++ modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml 2007-10-19 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;
+
+@Description("A test suite")
+public class MyTest
+{
+
+ private String foo;
+
+ @Parameter
+ @Description("A test parameter")
+ public void setFoo(String foo)
+ {
+ this.foo = 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.</para>
+
+ <example>
+ <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Keyword;
+import org.jboss.unit.api.pojo.annotations.Test;
+
+@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 managing
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
<interfacename>@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
indicates the resource name of the microcontainer
+ bootstrap file.</para>
+ <para>The current POJO being tested will be inserted in the microcontainer
kernel and it is possible to reference it
+ in the bootstrap file under the special
<literal>TestCase</literal> name. It is possible to override the name
+ using the <parameter>beanName</parameter> parameter of the
<interfacename>@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
Microcontainer 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 from 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 = dataSourceName;
+ }
+
+ public void start()
+ {
+ System.out.println("MyService start for data source " + dataSourceName);
+ }
+
+ public void stop()
+ {
+ System.out.println("MyService stop");
+ }
+
+}
+]]></programlisting>
+ <caption>
+ <para>The service</para>
+ </caption>
+ </example>
+
+ <example>
+ <programlisting><![CDATA[
+@Bootstrap(resourceName ="/jboss-beans.xml")
+public class MyTest
+{
+
+ private MyService service;
+ private String dataSourceName;
+
+ public MyService getService()
+ {
+ return service;
+ }
+
+ @Inject(bean="Service")
+ public void setService(MyService service)
+ {
+ this.service = service;
+ }
+
+ public String getDataSourceName()
+ {
+ return dataSourceName;
+ }
+
+ @Parameter
+
+ public void setDataSourceName(String dataSourceName)
+ {
+ this.dataSourceName = 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
injected 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 microcontainer thanks to
the <interfacename>@Bootstrap</interfacename>
+ annotation configured to use the file available from the classpath under the
name <literal>/jboss-beans.xml</literal>. The
+ <interfacename>@Inject</interfacename> annotation is a
microcontainer annotation that will trigger the injection
+ of the service in the test case.</para>
+
+ <example>
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<deployment xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:bean-deployer:2.0
bean-deployer_2_0.xsd"
+ xmlns="urn:jboss:bean-deployer:2.0">
+
+ <bean name="Service"
class="org.jboss.test.unit.mc.MyService">
+ <property name="dataSourceName"><inject
+ bean="TestCase"
+ property="dataSourceName"
+ state="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 the
value <literal>Instantiated</literal>. Without
+ this we would have a a bidirectional dependency between the service and the test
case and the kernel would not
+ be able to resolve it: the test case wants the injection of the service and the
service wants the injection
+ of a portion of the test case state. Using the
<literal>Instantiated</literal> state tells the kernel to use
+ the test case bean when it is instantiated and that allows the resolution 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 JBoss Unit
executes the test case the following sequence happens:
+ <itemizedlist>
+ <listitem>An instance of <classname>MyTest</classname>
is created by JBoss Unit</listitem>
+ <listitem>JBoss Unit configures the instance and set the
<parameter>dataSourceName</parameter> property</listitem>
+ <listitem>JBoss Unit creates a new microcontainer kernel and
registers the <classname>MyTest</classname> instance under the
<literal>TestCase</literal> name</listitem>
+ <listitem>JBoss Unit deploys the
<filename>jboss-beans.xml</filename> file</listitem>
+ <listitem>JBoss MC creates an instance of the
<classname>MyService</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</listitem>
+ </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/annotations/Description.java
===================================================================
---
modules/test/trunk/unit/src/main/org/jboss/unit/api/pojo/annotations/Description.java 2007-10-19
10:42:51 UTC (rev 8714)
+++
modules/test/trunk/unit/src/main/org/jboss/unit/api/pojo/annotations/Description.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/TestProviderSupport.java
===================================================================
---
modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProviderSupport.java 2007-10-19
10:42:51 UTC (rev 8714)
+++
modules/test/trunk/unit/src/main/org/jboss/unit/spi/pojo/TestProviderSupport.java 2007-10-19
12:28:58 UTC (rev 8715)
@@ -118,7 +118,7 @@
//
Description descriptionAnnotation =
((AnnotatedElement)testClass).getAnnotation(Description.class);
- String suiteDescription = descriptionAnnotation != null ?
descriptionAnnotation.description() : "";
+ String suiteDescription = descriptionAnnotation != null ?
descriptionAnnotation.value() : "";
if (suiteDescription.length() == 0)
{
suiteDescription = "Test of class " + testClass.getName();
@@ -226,7 +226,7 @@
//
Description descriptionMethodAnnotation =
method.getAnnotation(Description.class);
- String description = descriptionMethodAnnotation != null ?
descriptionMethodAnnotation.description() : "";
+ String description = descriptionMethodAnnotation != null ?
descriptionMethodAnnotation.value() : "";
if (description.length() == 0)
{
description = "Parameter " + name;
@@ -361,7 +361,7 @@
//
Description descriptionArgumentParameterAnnotation =
(Description)parameterAnnotationMap.get(Description.class);
- String description = descriptionArgumentParameterAnnotation != null ?
descriptionArgumentParameterAnnotation.description() : "";
+ String description = descriptionArgumentParameterAnnotation != null ?
descriptionArgumentParameterAnnotation.value() : "";
if (description.length() == 0)
{
description = "Method parameter " + name;
@@ -385,7 +385,7 @@
//
Description descriptionMethodAnnotation =
method.getAnnotation(Description.class);
- String description = descriptionMethodAnnotation != null ?
descriptionMethodAnnotation.description() : "";
+ String description = descriptionMethodAnnotation != null ?
descriptionMethodAnnotation.value() : "";
if (description.length() == 0)
{
description = "Test of method " + method.getName();