Author: veithen
Date: Wed Apr 28 22:16:46 2010
New Revision: 939113
URL: http://svn.apache.org/viewvc?rev=939113&view=rev
Log:
Added some notes about unit tests to the dev guide.
Modified:
webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml
Modified: webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml
URL:
http://svn.apache.org/viewvc/webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml?rev=939113&r1=939112&r2=939113&view=diff
==============================================================================
--- webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml (original)
+++ webservices/commons/trunk/modules/axiom/src/docbkx/devguide.xml Wed Apr 28
22:16:46 2010
@@ -47,6 +47,56 @@
<chapter>
<title>Testing</title>
<section>
+ <title>Unit test organization</title>
+ <para>
+ Historically, all unit tests were placed in the
<filename>axiom-tests</filename> project.
+ One specific problem with this is that since all tests are in
a common Maven module
+ which depends on both <filename>axiom-impl</filename> and
<filename>axiom-dom</filename>,
+ it is not rare to see DOOM tests that accidentally use the
LLOM implementation (which is the default).
+ The project description in
<filename>axiom-tests/pom.xml</filename> indicates that it
+ was the intention to split the
<filename>axiom-tests</filename> project into several parts
+ and make them part of <filename>axiom-api</filename>,
<filename>axiom-impl</filename> and
+ <filename>axiom-dom</filename>. This reorganization is not
complete
+ yet<footnote><para>See <ulink
url="https://issues.apache.org/jira/browse/WSCOMMONS-419";>WSCOMMONS-419</ulink>.</para></footnote>.
+ For new test cases (or when refactoring existing tests), the
following guidelines should be applied:
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Tests that validate the code in
<filename>axiom-api</filename> and that do not require
+ an Axiom implementation to execute should be placed in
<filename>axiom-api</filename>.
+ This primarily applies to tests that validate utility
classes in <filename>axiom-api</filename>.
+ </para>
+ </listitem>
+ <listitem id="test.category.api">
+ <para>
+ The code of unit tests that apply to all Axiom
implementations and that check conformance
+ to the specifications of the Axiom API should be added
+ to <filename>axiom-api</filename> and executed in
<filename>axiom-impl</filename> and
+ <filename>axiom-dom</filename>. Currently, the
recommended way is to create a
+ base class in <filename>axiom-api</filename> (with
suffix <classname>TestBase</classname>) and
+ to create subclasses in
<filename>axiom-impl</filename> and <filename>axiom-dom</filename>.
+ This makes sure that the DOOM tests never accidentally
use LLOM (because
+ <filename>axiom-impl</filename> is not a dependency of
<filename>axiom-dom</filename>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tests that check integration with other libraries
should be placed in
+ <filename>axiom-integration</filename>. Note that this
is the only module that requires
+ Java 1.5 (so that e.g. integration with JAXB2 can be
tested).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tests related to code in
<filename>axiom-api</filename> and requiring an Axiom
+ implementation to execute, but that don't fall into
category <xref linkend="test.category.api"/>
+ should stay in <filename>axiom-tests</filename>.
+ </para>
+ </listitem>
+ </orderedlist>
+ </section>
+ <section>
<title>Testing Axiom with different StAX implementations</title>
<para>
The following StAX implementations are available to test
compatibility with Axiom:
