8:10 p.m.
Author: julien(a)jboss.com
Date: 2007-10-18 21:10:14 -0400 (Thu, 18 Oct 2007)
New Revision: 8711
Added:
modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml
Modified:
modules/test/trunk/docs/user-guide/en/master.xml
modules/test/trunk/docs/user-guide/en/modules/introduction.xml
Log:
initial checkin of the documentation
Modified: modules/test/trunk/docs/user-guide/en/master.xml
===================================================================
--- modules/test/trunk/docs/user-guide/en/master.xml 2007-10-19 00:48:05 UTC (rev 8710)
+++ modules/test/trunk/docs/user-guide/en/master.xml 2007-10-19 01:10:14 UTC (rev 8711)
@@ -2,6 +2,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3CR3//EN"
"../../docbook-support/support/docbook-dtd/docbookx.dtd" [
<!ENTITY introduction SYSTEM "modules/introduction.xml">
+ <!ENTITY pojotesting SYSTEM "modules/pojotesting.xml">
]>
<book lang="en">
<bookinfo>
@@ -16,5 +17,6 @@
</bookinfo>
<toc/>
<!-- Introduction --> &introduction;
+ <!-- POJO Testing --> &pojotesting;
</book>
Modified: modules/test/trunk/docs/user-guide/en/modules/introduction.xml
===================================================================
--- modules/test/trunk/docs/user-guide/en/modules/introduction.xml 2007-10-19 00:48:05 UTC
(rev 8710)
+++ modules/test/trunk/docs/user-guide/en/modules/introduction.xml 2007-10-19 01:10:14 UTC
(rev 8711)
@@ -7,52 +7,46 @@
<email>julien(a)jboss.org</email>
</author>
</chapterinfo>
- <title>My title</title>
- <para>This section covers the ajax features provided by the
portal.</para>
+ <title>Introduction</title>
<sect1>
- <title>Introduction</title>
+ <title>Motivation</title>
<para>Todo</para>
</sect1>
<sect1>
- <title>Ajaxified markup</title>
+ <title>Principles</title>
+ <para>JBoss Unit clearly separates the different concerns for unit testing an
application.</para>
<sect2>
- <title>Ajaxified layouts</title>
- <para>Part of the Ajax capabilities are implemented in the layout
framework which provide the structure for
- generating portal pages. The good news is that the existing layout only requires
a few modifications in
- order to be ajaxified.</para>
- <para>We will use as example an simplified version of the layout JSP
provided in JBoss Portal 2.6 and outline
- what are the required changes that makes it an ajaxified layout:
- <programlisting><![CDATA[
-<%@ taglib uri="/WEB-INF/theme/portal-layout.tld" prefix="p"
%>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
-"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml">
-<head>
- <meta http-equiv="Content-Type" content="text/html;"/>
- <!-- inject the theme, default to the Renaissance theme if
- nothing is selected for the portal or the page -->
- <p:theme themeName="renaissance"/>
- <!-- insert header content that was possibly set by portlets on the page -->
- <p:headerContent/>
-</head>
-]]></programlisting>
- <itemizedlist>
- <listitem><![CDATA[<p:theme
themeName="renaissance"/>]]> should be already present as it exists since
2.4 but is even more
- necessary as it will inject in the page the reference to the ajax
stylesheet.</listitem>
- <listitem><![CDATA[<p:region regionName='AJAXScripts'
regionID='AJAXScripts'/>]]> should be added before any other region
- in the markup of the layout.</listitem>
- <listitem><![CDATA[<p:region regionName='AJAXFooter'
regionID='AJAXFooter'/>]]> should be added after any other region
- in the markup of the layout.</listitem>
- </itemizedlist>
- </para>
- <mediaobject>
- <imageobject>
- <imagedata align="center"
fileref="images/sample/partial-refresh.png" format="png"/>
- </imageobject>
- <caption>
- <para>The portal providing partial refresh</para>
- </caption>
- </mediaobject>
+ <title>Framework API</title>
+ <para>Writing a test case often requires the usage of an API in order to
perform interactions between the code tested
+ and the unit test framework. The first thing that a developer does is to
declare the different methods of the code
+ that are subject to be tested. In addition it can also declare how the
different tests needs to be parameterized. The
+ last interaction we recognize is the capability for a developer to perform
assertions during the execution of the
+ test and signal to the unit test framework that it failed. JBoss Unit
provides an API for those purposes that leverages
+ the features of the Java 5 platform such as annotations, generics or statis
imports. This API is not tied to the
+ framework itself which means that the test written will not have to import
anything from the framework itself.</para>
</sect2>
+ <sect2>
+ <title>Test Driver</title>
+ <para>The test driver is the part of the framework which defines the
contract of what a tested system is. It
+ provides support for retrieving the rich description of the tested system and
perform interactions i.e executing
+ tests.</para>
+ <para>The goal of this concept is to isolate the tested system from the
unit test framework itself. For instance
+ the testing of POJOs is done via the implementation of a specific test driver
that understand how to extract
+ test description from a POJO and how to test a POJO.</para>
+ </sect2>
+ <sect2>
+ <title>Test Runner</title>
+ <para>The test runner is the engine of the framework. Indeed the interface
exposed by a test driver is very
+ simple and low level. The test runner provides a framework that can be used
to trigger a serie of tests
+ leveraging one or several test drivers. The definition of the tests to
execute is written in an XML file
+ that contains the base configuration for executing a serie of test. It also
provide additional features
+ such as eventing capabilities and filtering capabilities.</para>
+ </sect2>
+ <sect2>
+ <title>Tooling</title>
+ <para>Tests are triggered by build systems or from command line, test
reporting must also be done in a manner
+ such as it integrates with other reporting systems. By default the framework
comes with support of Ant, Maven
+ and JUnit XML reporting schema.</para>
+ </sect2>
</sect1>
</chapter>
Copied: modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml (from rev 8708,
modules/test/trunk/docs/user-guide/en/modules/introduction.xml)
===================================================================
--- modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml
(rev 0)
+++ modules/test/trunk/docs/user-guide/en/modules/pojotesting.xml 2007-10-19 01:10:14 UTC
(rev 8711)
@@ -0,0 +1,228 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<chapter id="pojotesting">
+ <chapterinfo>
+ <author>
+ <firstname>Julien</firstname>
+ <surname>Viet</surname>
+ <email>julien(a)jboss.org</email>
+ </author>
+ </chapterinfo>
+ <title>POJO testing</title>
+ <para>We will describe in this chapter how to write tests for POJOs. We will
also cover the integration with JBoss Microcontainer
+ which allow the setup of complex POJO assemblies which enable to test complex
system with a reasonable amount of efforts.</para>
+ <para>The POJO test API leverages numerous Java 5 features in order to make
tests easy to write and read.</para>
+ <sect1>
+ <title>The simplest test case</title>
+ <para>A test cases is public non static method annotated with the
<interfacename>@Test</interfacename> annotation. The method
+ should have en empty list of arguments. At runtime an instance of the class is
created and the method is invoked, if the invocation
+ of the method can be achieved then the test case is considered as a success. Any
exception thrown by the method will signal
+ that the test failed.</para>
+ <para>A class containing a serie of test cases is considered as a test
suite.</para>
+ <example>
+ <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Test;
+
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <caption><filename>MyTest.java</filename></caption>
+ </example>
+ <para>In this example the method <methodname>test</methodname> is
our test case, and the class <classname>MyTest</classname>
+ is our test suite.</para>
+ <para>The various tested items tested must be declared in a file. This file
defines what is tested and how it should be.
+ One interesting thing is that it describes a tested system in an manner
independant of the tool which will trigger
+ your tests (command line, Ant, Maven, ...).</para>
+ <example>
+ <programlisting><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
+<jboss-unit
+ xmlns="urn:jboss:jboss-unit:1.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="urn:jboss:jboss-unit:1.0 jboss-unit_1_0.xsd">
+ <pojo>
+ <test>
+ <class name="MyTest"/>
+ </test>
+ </pojo>
+</jboss-unit>
+]]></programlisting>
+ <caption><filename>jboss-unit.xml</filename></caption>
+ </example>
+ </sect1>
+ <sect1>
+ <title>Making a test fail</title>
+ <sect2>
+ <title>Asssertion and errors</title>
+ <para>We explained in the previous section that a test is considered as
failed if it throws an exception during
+ its execution. There are two categories of failure.</para>
+ <itemizedlist>
+ <listitem>Assertion failures: produced by any exception instance of the
error
<exceptionname>java.lang.AssertionError</exceptionname>.</listitem>
+ <listitem>Error failures: produced by any exception not instance of the
error
<exceptionname>java.lang.AssertionError</exceptionname>.</listitem>
+ </itemizedlist>
+ <para>JBoss Unit relies on the assertion mechanism introduced by the Java
1.4 platform which introduces the <emphasis>assert</emphasis>. The first
+ advantage is that we leverage an existing feature of the platform, the second
advantage is that it will report assertion
+ failures that would be in the tested domain.</para>
+ <para>Obviously throwing instances of
<exceptionname>AssertionError</exceptionname> in your code is just an option
+ that you could use if you want. JBoss Unit comes with its own set of utility
methods that can perform various checks and
+ will throw an <exceptionname>AssertionError</exceptionname> if a
condition is evaluated to false. The class
+ <classname>org.jboss.unit.api.Assert</classname> contains those
static methods. The class is final which means that
+ your code cannot extend it, instead you should rather rely on the static import
mechanism in order to import the various
+ methods needed by your test cases.</para>
+ <example>
+ <programlisting><![CDATA[
+import org.jboss.unit.api.pojo.annotations.Test;
+import static org.jboss.unit.api.Assert.*;
+
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ fail("Don't freak out");
+ }
+}
+]]></programlisting>
+ </example>
+ <para>The <methodname>fail</methodname> method will simply
throw a <exceptionname>AssertionError</exceptionname> with the specified
message. It will
+ stop the execution of the test case and it will be considered as an assertion
faillure.</para>
+ </sect2>
+ <sect2>
+ <title>Various assertions</title>
+
+ <sect3>
+ <title><methodname>assertNull</methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ assertNull(null);
+ }
+}
+]]></programlisting>
+ <para>Assert that the argument is null.</para>
+ </sect3>
+
+ <sect3>
+
<title><methodname>assertNotNull</methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ 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>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ <sect3>
+ <title><methodname></methodname></title>
+ <programlisting><![CDATA[
+public class MyTest
+{
+ @Test
+ public void test()
+ {
+ }
+}
+]]></programlisting>
+ <para>.</para>
+ </sect3>
+
+ </sect2>
+ </sect1>
+</chapter>