<?xml version="1.0"?>
<document url="http://openejb.exolab.org/CG-1.xml">
    <properties>
        <abstract>
  The perfect place to get involved and gently brought up to speed is by  creating unit tests.  The unit tests are a fabulous way to get started because it gets you right into the core code right away without needing any knowledge in the overall design.  This document details the guidelines for creating unit tests.
        </abstract>
        <author email="david.blevins@visi.com" ldap="">David Blevins</author>
    </properties>
  <body>
    <title>Contributor's Guide -- Unit Tests</title>
    <header>
    <p> 
    <table border="0" cellpadding="0" width="100%">
    <tr><td>OpenEJB - Container System</td><td ALIGN="RIGHT">David Blevins</td></tr>
    <tr><td>Contributor's Guide: CG-1</td><td ALIGN="RIGHT">July 2001</td></tr>
    </table>
    </p>
    <p><center>Contributor's Guide -- Unit Tests</center></p>

    <p>Abstract</p><p>

  The perfect place to get involved and gently brought up to speed is by  creating unit tests.  The unit tests are a fabulous way to get started because it gets you right into the core code right away without needing any knowledge in the overall design.  This document details the guidelines for creating unit tests.
    
    </p>

    <p>Table of Contents</p>

    </header>
    
<section title="1   Introduction" ref-id="1">
  
	<p>
		In the OpenEJB world, unit tests test a specific method or constructor of a
        specific class.  Ideally, every class in OpenEJB should have an equivalent 
        test class with test methods (unit tests) testing all the constructors and
        methods of that class.  Some methods may execute differently based upon the
        input, multiple unit tests should be written to exercise each aspect the
        method to ensure complete coverage of the methods functionality. 
	</p>

</section>

<section title="2   Package name" ref-id="2">

	<p>
		Tests go in the same package as the class being tested.  This allows the unit
        tests in the test class to have package level, protected and public access to 
        the methods in the class being tested.
	</p>
	<p>
		If we had a class called MyClass in the package org.openejb.foo, the test 
        class would declare org.openejb.foo as its package.
	</p>

</section>

<section title="3   Class name" ref-id="3">

	<p>
		Test class names follow this format: <br/>
		<code>UT&lt;className&gt;</code>
	</p>

	<p>
		<code>UT</code> is a prefix to quickly distinguish the that the class is a
        unit test and not part of the API.<br/>
        <code>&lt;className&gt;</code> is the name of the class being tested.

	</p>
	<p>
		Example:<br/>
		org.openejb.foo.MyClass --> org.openejb.foo.UTMyClass
	</p>

</section>

<section title="4   Location" ref-id="4">

	<p>
		All test classes are to be placed under the <code>test/src/</code> directory 
        of the repository regardless of where the class being tested is located.
	</p>

</section>

<section title="5   Superclass and Constructor" ref-id="5">

	<p>
		All test classes must extend subclass from <code>org.openejb.test.NamedTestCase</code>
	</p>

	<p>
		There must be a public no-arg constructor.  In the constructor, the 
        superclass's constructor must be called passing in the name of the class 
        being tested followed by a period as a string.
	</p>

	<p>
		Example:<br/>
		<code>
        <br/>package org.openejb.foo;
		<br/>
        <br/>import org.openejb.test.NamedTestCase;
		<br/>
        <br/>public class UTMyClass extends NamedTestCase{
        <br/><tab/>public UTMyClass(){
        <br/><tab/><tab/>super("org.openejb.foo.MyClass.");
        <br/><tab/>}
        <br/>}
        </code>
	</p>

</section>

<section title="6   Testing Constructors" ref-id="6">

	<p>
		All constructors of a class must be tested before testing individual methods.
	</p>

</section>

<section title="6.1   Test Method Names for Constructors" ref-id="6.1">

	<p>
		All test methods (unit tests) should be declared as public, return void, and
        have no arguments.  Test method names for testing a classes constructor follow 
        this format:<br/>
		<code>public void test&lt;XX&gt;_constructor()</code>
	</p>

	<p>
		<code>test</code> -- A prefix which signifies that the method in the test
        class is a unit test.  Methods with this prefix are automatically collected, 
        sorted and executed when the test suite is ran.<br/>
	    <code>&lt;XX&gt;</code> -- This should be replaced with a two digit number 
        that dictates the order in which the test will be executed in reference to 
        the other unit tests in the test class.<br/>
		<code>constructor</code> -- A suffix denoting that the unit test is testing a
        constructor of the class being tested.
	</p>

	<p>
		Example:<br/>
		<code>public void test01_constructor(){...}</code>
	</p>

</section>

<section title="6.2   Classes with overloaded constructors" ref-id="6.2">

	<p>
		To test a constructor more than once or to test multiple signatures in the
        case of overloaded constructors, used the naming format above with a number 
        appended to the test method signature.
	</p>

	<p>
		For example, MyClass has two constructors: MyClass(Integer i) and 
        MyClass(int i).  This requires at least two test methods:<br/>
        <code>
		test01_constructor1() {...} <br/>
		test02_constructor2() {...}
        </code>
	</p>

</section>

<section title="7   Testing Methods" ref-id="7">

	<p>
		Each method should be tested starting with the simplest method working up to
        the more complicated/interrelated ones.  For example, if <code>methodC()</code>
        calls <code>methodA()</code> and <code>methodB()</code>, test <code>methodA()</code>
        and <code>methodB()</code> before <code>methodC()</code>.
	</p>

</section>

<section title="7.1   Test Method Names" ref-id="7.1">

	<p>
		All test methods (unit tests) should be declared as public, return void, and
        have no arguments.  Test method names follow this format:<br/>
		<code>public void test&lt;XX&gt;_&lt;methodName&gt;()</code>
	</p>

	<p>
		<code>test</code> -- Same as above.<br/>
        <code>&lt;XX&gt;</code> -- Same as above.<br/>
        <code>&lt;methodName&gt;</code> -- The method name of the method in the class
        being tested. <br/>

		For example, the method <code>myMethod()</code> of <code>MyClass</code> might have a unit test method like the following in the class <code>UTMyClass</code>:
	    <br/>
        <code>
		public void test05_myMethod(){...}
        </code>
	</p>

</section>

<section title="7.2   Overloaded methods" ref-id="7.2">

	<p>
		To test a method more than once or to test multiple signatures for overloaded
        methods, used the naming format above with a number appended to the test 
        method signature.
	</p>

	<p>
		For example, <code>myMethod</code> has two signatures: 
        <code>myMethod(Integer i)</code> and <code>myMethod(int i)</code>.
        This requires at least two test methods, once for each signature.<br/>

        <code>
        public void test05_myMethod1(){...}<br/>
        public void test06_myMethod2(){...}
        </code>
	</p>

</section>

<section title="9   Test Method Body " ref-id="9">

<section title="9.1   Passing and Failing " ref-id="9.1">

	<p>
		Use the <code>junit.framework.Assert</code> class to assert method results. 
        ALWAYS include a descriptive message string for the methods <code>assert(...)</code>,
        <code>assertNotNull(...)</code>, and <code>assertNull(...)</code>.
	</p>

	<p>
		Example:<br/>
        <code>
        <br/>public void test06_myMethod1(){
        <br/>        
        <br/><tab/>Integer excepted = new Integer(4);
        <br/><tab/>Integer actual = classInstance.myMethod(new Integer(3));
        <br/>        
        <br/><tab/>Assert.assertNotNull(actual,"Null string!!!");
        <br/><tab/>Assert.assertEquals(expected, actual);
        <br/>}
        </code>
	</p>
</section>

<section title="9.2   Exceptions" ref-id="9.2">

	<p>
		All testing code should be placed inside a try and catch block to exceptions
        from leaving the test method and being logged as unknown errors by the testing
        framework. If an unexpected exception is thrown, the test must be failed with 
        sufficient message to find the problem.
	</p>

	<p>
		Example:
        <code>
        <br/>public void test06_myMethod1(){
        <br/>        
        <br/><tab/>try{
        <br/><tab/><tab/>Integer excepted = new Integer(4);
        <br/><tab/><tab/>Integer actual = classInstance.myMethod(new Integer(3));
        <br/>        
        <br/><tab/><tab/>Assert.assertNotNull(actual,"Null string!!!");
        <br/><tab/><tab/>Assert.assertEquals(expected, actual);
        <br/><tab/>} catch (Exception e){
        <br/><tab/><tab/>Assert.assert("Received Exception "+
        <br/><tab/><tab/><tab/><tab/>e.getClass()+ " : " +
        <br/><tab/><tab/><tab/><tab/>e.getMessage(), false);
        <br/><tab/>}
        <br/>}
        </code>
	</p>

</section>
</section>

<section title="10   Uncovering Bugs" ref-id="10">

	<p>
		If the test methods runs and uncovers a bug, prefix the test method name with
        "BUG_" as in "BUG_test06_myMethod1()".  
        This serves a few important functions:<br/>
        <UL>
        <LI>Prevents the test suite output from being deluded with reports from known bugs.</LI>
        <LI>Allows us to easily locate known bugs in the code and even write scripts that generate a bug list by searching test files for "BUG_".</LI>
        <LI>Removing the "BUG_" prefix gives developers an easy way to put the test back into the suite for debugging.</LI>
        </UL>
	</p>

</section>

<section title="11   Unfinished Tests" ref-id="11">

	<p>
		Tests that aren't finished or fail due to problems in testing 
        code --NOT the code of the class being tested-- should be prefixed 
        with "TODO_" as in "TODO_test06_myMethod1()"
	</p>

</section>

<section title="12   Working on a Test" ref-id="12">

	<p>
		If you will be working on a test already in the repository for an extended 
        period of time for debugging or other reasons, it may be useful to prefix your
        initials in capitol letters to the test method name as in 
        "DMB_test06_myMethod1()".  This lets others know not to spend time working on
        what is already covered.  This can be done in addition to one of the "BUG_" or
        "TODO_" prefixes above as in "DMB_TODO_test06_myMethod1()".
	</p>

	<p>
		Similarly, if you wish to assign a test to someone for completion or 
        debugging, you may prefix their initials to the test method name as in 
        "RMH_test06_myMethod1()".  This can be done in addition to one of 
        the "BUG_" or "TODO_" prefixes above as in "RMH_BUG_test06_myMethod1()".
	</p>

	<p>
		Once the prefix is added, simply check the file in so others are aware of 
        what you are working on or what they should be working on.  If you don't
        have CVS access to commit files, you can send an email like the following 
        to the OpenEJB-CVS@exolab.org mailing list:<br/>
        <code>
		TO: OpenEJB-CVS@exolab.org<br/>
		FROM: you@yourdomain.com<br/>
		SUBJECT: org.openejb.foo.MyClass.DMB_TODO_test06_myMethod1()<br/>
        </code>
	</p>

</section>

<section title="13   Other Resources" ref-id="13">
  <a href="www.junit.org">www.junit.org</a>
</section>
</body>
</document>
