<?xml version="1.0" encoding="ISO-8859-1"?>
<document url="http://castor.codehaus.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>Castor JDO 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 be
        cut to execute a different set of tests. Upon complete execution of the
        suite of tests listed in the XML configuration file, the results are
        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.
      </p>

      <p>
        The following is a quick start guide to running the tests that come with
        Castor:
      </p>

      <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 <tt>oracle.xml</tt>. Change this file to contain the proper
          username, password, driver and any driver parameters necessary. For
          more information on this, see <a href="jdo-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
          <tt>oracle.sql</tt>. Consult the database documentation on loading the
          SQL file. Alternatively, there is a little utility available with
          Castor called <tt>BatchUpdateSQL</tt> in the directory
          <tt>src/tests/jdo</tt> 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 building 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>

        <p>
          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.
        </p>

      </ol>

    </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 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
          then 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,
          at first.  The following steps will assist you in writing your own:
        </p>

        <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 <tt>oracle.xml</tt>.  (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="jdo-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 <tt>src/tests/jdo</tt> 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>
                <tt>setUp()</tt> -- This method is used for any necessary
                assembly of the test.
              </li>
              <li>
                <tt>tearDown()</tt> -- This method is used to disassemble the
                test upon completion of execution.
              </li>
              <li>
                <tt>runTest()</tt> -- This method is passed to JUnit to execute
                any tests called in the method body.
              </li>
              <li>
                <tt>testXXX()</tt> -- Any number of test methods can be written.
                Each test method's name begins with the word <tt>test</tt>
                followed by a descriptive name using an initial capital letter.
              </li>
            </ol>
            <br />
            <br />

            <p>
              Simply change <tt>setUp()</tt>, <tt>runTest()</tt>, and
              <tt>tearDown()</tt> to suit your needs. Then proceed to write any
              number of <tt>testXXX()</tt> methods to test your situation. Just
              place the name of each <tt>testXXX()</tt> method (in the proper
              order) in the <tt>runTest()</tt> 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 <tt>&lt;case&gt;</tt>
            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 its own file. For the sake of
            this example, we'll call the file <tt>myapp_tests.xml</tt>.
          </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
            <tt>src/tests/jdo</tt> directory. For example, the tables needed
            to test Oracle reside in <tt>oracle.sql</tt>. Incidentally, there
            is a little utility called <tt>BatchUpdateSQL</tt> in the
            <tt>src/tests/jdo</tt> 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>

      </section>

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

    </section>

  </body>

</document>
