Java Persistent Objects - JPOX Design : Unit Tests

JPOX uses JUnit for unit testing. JPOX uses 2 types of unit tests.

Component tests - the traditional "unit" test and these are stored in CVS with the project they are testing.
End-to-End tests - where we persist objects in a datastore, and test the result. These are stored in their own separate project in CVS.

For this second type, and because JDO/JPA have many aspects, we use a "scenario" testing strategy. By this we mean that we separate our unit tests into what they test. When developing anything, the unit tests should be the guiding light as to whether you should be checking anything in to CVS. If your change breaks things, you shouldn't check things in. Each test "scenario" has its own project in CVS with names like "test.jdo.general", "test.jpa.general", etc.

End-to-End Test Scenarios

The base dependents of all test scenarios are the following projects

test.framework - providing the base test classes for creating PMF/EMF for the datastore, and convenience methods.
test.samples - providing a series of model classes that can be used in the test scenario for persistence.

There are currently the following scenarios

test.jdo.general - General tests for JDO
test.jdo.datastore - Datastore identity specific tests for JDO
test.jdo.application - Application identity specific tests for JDO
test.jdo.jta - Tests for using JDO with JTA (but not JCA)
test.jdo.java5 - JDK1.5+ tests for JDO
test.jdo.spatial - Spatial tests for JDO
test.jpa.general - General tests for JPA
test.jdo.db4o - Tests specific to DB4O, using JDO

JCA Test Scenarios

The JPOX JCA connector test scenarios are the following projects. To run these tests you must create the data source, deploy the JPOX JCA connector and deploy the EJB application.

test.jca.jdo - EJB application with tests for JDO

Testing with Maven

Prerequisites

Before running any tests you need to setup a database which will be used during the tests. Please see Database Notes below for details.

The scenario tests are run via Maven1 using the "test" plugin. Before running any tests, you need to build and install the plugin by typing the following from within Plugins/Maven1:

maven clean plugin:install

Running the tests

From within one of the test projects, you simply type

maven clean test

The results of the tests are stored under target/test-reports/

If you want to run an individual test only, you need to modify the file "project.xml" within the test project in question. If you want to e.g. run only the JDOQLBasicTest in test.jdo.application, the test.jdo.application/project.xml should look like this:

                        [..]
                                <!-- JUnit, component tests -->
                                <unitTestSourceDirectory>src/test</unitTestSourceDirectory>
                                <unitTest>
                                    <includes>
                                        <include>**/JDOQLBasicTest.java</include>
                                    </includes>
                                </unitTest>
                        [..]

Testing with Ant

TODO - provide documentation on how to run tests using Ant

Adding Unit Tests

Where you feel that our unit tests do not adequately cover functionality, you should add a test. Please follow the following process

Decide which scenario your test fits into
Look at the available model samples and choose one.
Write your unit test, extending one of the common base classes, for example JDOPersistenceTestCase.
Run your test.
Raise a JIRA and attach your testcase to the issue

Debugging Tests in Eclipse

Debugging JPOX unit tests might be very boring, but there is a way of reducing the pain in Eclipse using the JPOX Eclipse Plugin. Follow the next steps to make this easier:

Install the JPOX Eclipse Plugin.
Add enhancement to the JPOX project. Right Click on the project > JPOX > Enhance with JPOX 1.1.
Setup the enhancement. Right Click on the project > JPOX > Enhance setup. If you are going to run the test in General or Datastore Scenario use "jdo,jdod" as suffix for jdo files and for Application Scenario use "jdo,jdoa".
Run a JUNIT test in DEBUG mode, but first, you must setup some configuration to run the tests

Don't forget to set the jdo file suffix for the Scenario you are going to run.

Debugging Enhancer in Eclipse

To debug the JPOX enhancement, follow the next steps:

Create a new Java application for run or debug. In Eclipse, click on the menu Run and Run... or Debug....
Click on the Java Application and New
Set up the configuration as presented on the next screenshots.
Input all of the jdo (jdo,jdod,jdoa) files with space to separate each file.
Make sure the classpath is correct.
That's all. Now run it in debug mode.

Databases Notes

Database setup for running tests

Each test project contains a "project.properties" file that determines which database will be used for running the tests of that particular project, e.g. test.jdo.general/project.properties. The value of the property maven.jpox.datastore refers to database configuration files under test.framework/src/conf.

Some tests require two database instances, which is why for every database there exist two files, e.g. "maven.jpox.datastore=hsql" refers to both

test.framework/src/conf/jpox-hsql.1.properties, and
test.framework/src/conf/jpox-hsql.2.properties

The default database configured in the test projects is hsqldb.

Following are notes about running the JPOX unit tests with particular databases.

HSQLDB

For general information about running HSQLDB see the HSQL documentation. Follwing is an exemplary commandline to start the HSQLDB server with the two schemas "jpox" and "jpox2" required for running the jpox test suites:

                    java -cp /usr/local/maven-repository/hsqldb/jars/hsqldb-1.8.0.4.jar org.hsqldb.Server -database.0 jpoxdb -database.1 jpoxdb2 -dbname.0 jpox -dbname.1 jpox2

Test results can best be compared when starting off with a completely empty database. With HDSQLDB this can be achieved easily by simply erasing all files that it created. If you issued the above commmand line from an empty directoy, after stopping the database you can safely delete all files found in that directory to start off with an empty database again.

Oracle 10.2.0.1

If you face the issue ORA-12519, TNS:no appropriate service handler, try increasing the parameters sessions and processes to 300 and open_cursors to 1000. To change these values in Oracle, issue the following statements.

alter system set open_cursors = 1000 scope=spfile
alter system set sessions = 300 scope=spfile
alter system set processes = 300 scope=spfile

Refer also to the Oracle spfile (see also initXE.ora or init.ora)

*.processes=300
*.sessions=300
*.open_cursors=1000

If you face the issue ORA-01000: maximum open cursors exceeded, try increasing the parameter open_cursors to 1000 in the file initXE.ora or init.ora.

*.open_cursors=1000

If you face OutOfMemory errors, increase the Xms and Xmx JVM args for running the junit tests.