|  |  |  | License Codehaus OpenEJB OpenJMS OpenORB Tyrex

Old releases
General
Release 1.3
Release 1.3rc1
Release 1.2

Main
Home
About
Features
Download
Dependencies
Reference guide
Publications
JavaDoc
Maven 2 support
Maven 2 archetypes
DTD & Schemas
Recent HTML changes
News Archive
RSS news feed
Project Wiki

Development/Support
Mailing Lists
SVN/JIRA
Contributing
Support
Continuous builds
Prof. services

Related projects
Spring ORM support
Spring XML factories
WS frameworks

XML
XML

XML Code Generator
XML Code Generator

JDO
Introduction
First steps
Using JDO
JDO Config
Types
JDO Mapping
JDO FAQ
JDO Examples
JDO HOW-TOs
Tips & Tricks
Other Features
JDO sample JAR

Tools
Schema generator

Advanced JDO
Caching
OQL
Trans. & Locks
Design
KeyGen
Long Trans.
Nested Attrs.
Pooling Examples
LOBs
Best practice

DDL Generator
Using DDL Generator
Properties
Ant task
Type Mapping

More
The Examples
3rd Party Tools
JDO Tests
XML Tests
Configuration

About
License
User stories
Contributors
Marketplace
Status, Todo
Changelog
Library
Contact
Project Name

## Castor JDO Test Framework Overview

Documentation Author(s):
Bruce Snyder

Test Framework Overview
Executing the Castor JDO Test Cases
Writing Test Cases
Introduction
Writing Tests Using the CTF-JDO
Additional Information

## Test Framework Overview

The Castor Test Framework for JDO (CTF-JDO) is a thin wrapper around JUnit, 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.

For more information on writing unit tests with JUnit, please see this quick introduction article.

## Executing the Castor JDO Test Cases

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.

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

1. Configure the database connection.
   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 JDO Config.
2. Create the appropriate database tables.
   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 directory `src/tests/jdo` that can assist in the loading of SQL files.
3. Compile the tests.
   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.
4. Run the tests.
   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.

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.

## Writing Test Cases

### Introduction

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.

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.

### Writing Tests Using the CTF-JDO

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:

1. Customize the database XML descriptor to connect to your database.
   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 JDO Config.
2. Create the appropriate database tables.
   This is done by loading the SQL file corresponding to the database being tested.
3. Create the mapping descriptor.
   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 XML mapping. This mapping descriptor will need to be referenced in the database descriptor as noted in step one.
4. Write the tests.

   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:

   1. The constructor - This is used to identify the test by giving it a name and a number.
   2. `setUp()` -- This method is used for any necessary assembly of the test.
   3. `tearDown()` -- This method is used to disassemble the test upon completion of execution.
   4. `runTest()` -- This method is passed to JUnit to execute any tests called in the method body.
   5. `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.

   Simply change `setUp()`, `runTest()`, and `tearDown()` to suit your needs. Then proceed to write any number of `testXXX()` methods to test your situation. Just place the name of each `testXXX()` method (in the proper order) in the `runTest()` method.

5. Create the test descriptor.
   The XML test descriptor is simply a list of tests to be executed. The important part of this file is each `<case>` 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:

       <harness name="Instance Creation Tests">
          <category name="Misc" class="jdo.JDOCategory">
             <jdo database-name="mytestcases" configuration="my_test_cases.xml" />
             <case class="myapp.TestOne" />
             <case class="myapp.TestTwo" />
             <case class="myapp.TestThree" />
                ...
          </category>
       </harness>

   This XML would need to be placed in its own file. For the sake of this example, we'll call the file `myapp_tests.xml`.
6. Create the database tables.
   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.
7. Compile the tests.
   Execute the build script with the argument 'tests' to compile the tests. The standard Castor build script should pick up the files created.
8. Execute the tests.
   Execute the test script with the argument '-file myapp_tests.xml'. This points to the proper XML test descriptor for execution.

### Additional Information

Not yet created.

<notice> Copyright © 1999-2005 ExoLab Group, Intalio Inc., and Contributors. All rights reserved. </notice>
<notice> Java, EJB, JDBC, JNDI, JTA, Sun, Sun Microsystems are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and in other countries. XML, XML Schema, XSLT and related standards are trademarks or registered trademarks of MIT, INRIA, Keio or others, and a product of the World Wide Web Consortium. All other product names mentioned herein are trademarks of their respective owners. </notice>