<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.org/test-framework.xml">
    <properties>
        <title>Castor Test Framework - JDO</title>
        <author email="ferret@frii.com">Bruce Snyder</author>
        <abstract>
        Outlines the Castor JDO test framework. 
        </abstract>
        <status>Final</status>
    </properties>

    <body>
        <title>Test Framework Overview</title>

        <section title="Test Framework Overview">

            <p>The Castor Test Framework for JDO (CTF-JDO) is a thin wrapper around 
            <a href="http://www.junit.org">JUnit</a>, the well known Java unit test framework. CTF-JDO 
            provides the ability to execute tests based on an XML configuration file. This is very 
            powerful when faced with a large number of tests because it allows the execution of 
            only certain tests out of that large pool of tests. Also, this feature can save 
            an immense amount of time in the software development process because no code need by 
            cut to execute a different set of tests. Upon execution of the suite of tests listed in the 
            XML configuration file, the results are then reported to the terminal.</p>
            
            <p>For more information on writing unit tests with JUnit, please see this 
            <a href="http://junit.sourceforge.net/doc/testinfected/testing.htm">quick introduction</a> article.</p>

            <!--
            <p>
            <h1>&lt;remove-this&gt;</h1> 
            The following objects make up the Test Framework:
            <ol type="bullet">
                <li>package harness:</li>
                <ol type="bullet">
                    <li>Case</li> provides createTestCase()
                    <li>CaseDescriptor</li>
                    <li>CastorTestCase extends junit.framework.TestCase</li>
                    <li>Category</li> provides createTestCategory() which calls Case.createTestCase()
                    <li>CategoryDescriptor</li>
                    <li>Harness</li> provides createTestHarness() which calls createTestCategory()
                    <li>HarnessDescriptor</li>
                    <li>TestHarness extends junit.framework.TestSuite</li>
                </ol>
            </ol>
            <h1>&lt;/remove-this&gt;</h1> 
            </p>
            -->

        </section>

        <section title="Executing the Castor JDO Test Cases">

            <p>In the Castor directory is a test script that accepts arguments and passes them along to 
               the TestSuite in CTF-JDO. Executing the test script (test.[sh|bat])with the argument 
               '-info' yields a full list of the test cases available for execution.<br /><br />
            
               The following is a quick start guide to running the tests that come with Castor: 

               <ol type="1">
                  <li><b>Configure the database connection.</b><br />
            
                      This is done in the XML file corresponding to the database being tested. For example, 
                      database connections for Oracle are configured in the file oracle.xml. Change this file to contain 
                      the proper username, password, driver and any driver parameters necessary. For more information on this,
                      see <a href="database-conf.html">JDO Config</a>.</li>
            
                  <li><b>Create the appropriate database tables.</b><br />
            
                      This is done by loading the SQL file corresponding to the database being tested.
                      For example, the tables needed to test Oracle reside in oracle.sql. Consult the 
                      database documentation on loading the SQL file. Alternatively, there is a little 
                      utility available with Castor called BatchUpdateSQL in the src/tests/jdo directory 
                      that can assist in the loading of SQL files.</li>
            
                  <li><b>Compile the tests.</b><br />
            
                      The tests can be compiled by executing the build script with the argument 
                      'tests'. Note that compiling Castor is a prerequisite to compiling the tests.</li>

                  <li><b>Run the tests.</b><br />
            
                      To run only the tests for Oracle, for example, execute the test script with the 
                      argument 'castor.oracle'. This argument will cause the CTF-JDO to execute only 
                      the battery of tests for Oracle.</li><br /><br />

                      Incidentally, if more feedback is needed from the tests as they're being run, execute 
                      the test script with the argument '-verbose'. This will cause the CTF-JDO to output 
                      more information about what is actually taking place while tests are executing. 
 
               </ol>

            </p>

        </section>

        <section title="Writing Test Cases">

           <section title="Introduction">

              <p>Writing test cases is a very important yet often misunderstood task. Unit tests are pieces 
                 of code that exercise different scenarios of a piece of software. Test cases are made up 
                 of groups of unit tests. Writing test cases for specific uses of Castor is extremely 
                 vital. Submitting test cases assists the Castor developers in verifying bugs and/or 
                 patches. Whenever a user submits a request to the mail list stating that Castor is 
                 not working in their situation, someone must analyze the user's description or, if 
                 it's submitted, the user's code, and create a test case for that situation. This is 
                 very time consuming and sometimes quite difficult to achieve. Submitting test cases 
                 with a complete description of the problem saves everyone a tremendous amount of time and 
                 expedites the entire process.</p>

              <p>Understanding why unit tests are so important is the first step to addressing this issue.
                 It may seem counterintuitive, but writing unit tests will actually save development time.</p>

           </section> 
        
           <section title="Writing Tests Using the CTF-JDO">
        
              <p>Writing test cases using the CTF-JDO can be difficult to figure out. The following 
                 steps serve to assist in writing your own:

              <ol type="1">
                 <li><b>Customize the database XML descriptor to connect to your database.</b><br/>
                     
                     There are database descriptors in the src/test/jdo directory for most, if not 
                     all, of the supported databases. The database descriptor is an XML file corresponding 
                     to the database being tested. It provides the information needed to make connections to 
                     the database. For example, database connections for Oracle are configured in the 
                     file oracle.xml.  (Note: In this descriptor is a reference to a mapping descriptor. This 
                     should point to the mapping descriptor created in step two.) For more information on 
                     this, see <a href="database-conf.html">JDO Config</a>.</li>
            
                 <li><b>Create the appropriate database tables.</b><br />
            
                     This is done by loading the SQL file corresponding to the database being tested. </li>

                 <li><b>Create the mapping descriptor.</b><br/>
                 
                     Most situations will require the creation of an object model for the tests. 
                     This requires that an XML mapping descriptor also be created. For information 
                     on this, see the section on <a href="xml-mapping.html">XML mapping</a>. This 
                     mapping descriptor will need to be referenced in the database descriptor as 
                     noted in step one.</li>

                 <li><b>Write the tests.</b><br/>
                 
                     <p>The easiest way to write a test for your situation is to copy one of the 
                     existing tests in the src/tests/jdo directory and change it to suit your 
                     needs. Each test implements a certain set of methods. The list of methods 
                     is as follows:</p>

                     <ol type="A">
                        <li>The constructor - This is used to identify the test by giving it a name and a number.</li>
                        <li>setUp() - This method is used for any necessary assembly of the test.</li>
                        <li>tearDown() - This method is used to disassemble the test upon completion of execution.</li>
                        <li>runTest() - This method is passed to JUnit to execute any tests called in the method body.</li>
                        <li>testXXX() - Any number of test methods can be written. Each test method's name begins with the word test followed by a descriptive name using an initial capital letter.</li>
                     </ol><br /><br />
                
                     <p>Simply change setUp(), runTest() and tearDown() to suit your needs. Then 
                     proceed to write any number of testXXX() methods necessary to test your 
                     situation. Just place the name of each testXXX() method (in the proper 
                     order) in the runTest() method.</p></li>

                 <li><b>Create the test descriptor.</b><br/>
                 
                     The XML test descriptor is simply a list of tests to be executed. The important 
                     part of this file is each &lt;case&gt; element. This is where the fully 
                     qualified name of each test resides. The following is a small example of a 
                     stand alone XML descriptor containing some tests to run:

<code>
&lt;harness name="Instance Creation Tests"&gt;
   &lt;category name="Misc" class="jdo.JDOCategory"&gt;
      &lt;jdo database-name="mytestcases" configuration="my_test_cases.xml" /&gt;
      &lt;case class="myapp.TestOne" /&gt;
      &lt;case class="myapp.TestTwo" /&gt;
      &lt;case class="myapp.TestThree" /&gt;
         ...
   &lt;/category&gt;
&lt;/harness&gt;
</code>
        
                      This XML would need to be placed in it's own file. For the sake of this 
                      example, we'll call the file myapp_tests.xml.</li>

                  <li><b>Create the database tables.</b><br/>
                  
                      This is done by loading an SQL file that describes the tables. For a 
                      sample of such an SQL file, see the SQL files in the src/tests/jdo 
                      directory. For example, the tables needed to test Oracle reside in 
                      oracle.sql. Incidentally, there is a little utility called BatchUpdateSQL in 
                      the src/tests/jdo directory that is helpful in executing SQL files.</li>

                 <li><b>Compile the tests.</b><br/>
                 
                     Execute the build script with the argument 'tests' to compile the tests. 
                     The standard Castor build script should pick up the files created.</li>

                 <li><b>Execute the tests.</b><br/>
                 
                     Execute the test script with the argument '-file myapp_tests.xml'. This points 
                     to the proper XML test descriptor for execution.</li>

              </ol>

           </p>

        </section>

        <section title="Additional Information">
           <p>Not yet created.</p>
        </section>

      </section>

   </body>
</document>
