Java Persistent Objects - Design : Unit Tests

JPOX Design : Unit Tests

JPOX uses JUnit for unit testing. Because JDO has 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.

Test Scenarios

There are currently 4 scenarios

General - generic tests, like MetaData, or internationalisation.
Schema - relating specifically to the datastore schema.
Datastore - testing of datastore identity functionality.
Application - testing of application identity functionality.

Because the last 2 scenarios are very similar in nature, we often use the same classes for testing, but specify different MetaData, meaning that the class is persisted in different ways. The way this is done is by providing jdoa (application id) and jdod (datastore id) MetaData files. These are standard MetaData files, but with a different suffix to define which applies where. This is then interpreted by the testing process and copied across to the testing area with suffix jdo.

The tests to run in each scenario are defined in the file test.properties.

Testing with Maven

The testing process with Maven operates via a Maven jpoxtest plugin. This provides the functionality necessary for a scenario to be tested. It operates as follows

Copy all test classes across to the scenarios work area.
Copy all MetaData files with suffix jdo across to the scenarios work area.
Copy all MetaData files with the specified suffix (e.g jdod across to the scenarios work area with suffix jdo.
Run the enhancer on the classes and JDO files in the scenarios work area.
Run JUnit on all tests specified as input to the scenario test.
Convert the JUnit output into a single page for use on the website.

The results of the tests are stored under target/test-reports-{scenario name}.

To run the unit tests with Maven you use the following goals

maven jpoxtest-general

maven jpoxtest-schema

maven jpoxtest-datastore

maven jpoxtest-application

Testing with Ant

The Ant process operates similarly to Maven, using Ant scripts. To run Ant, you need to use the following Ant targets : test.general, test.schema, test.datastore, test.application, test.Enhancer to run the different test scenarios. The results of the tests are stored under tests/results/.

ant test.general

ant test.datastore

ant test.application

ant test.schema

ant test.Enhancer

In addition, you can run the Ant target test to run all test scenarios : general, schema, datastore, application and Enhancer.

ant test

If you want run independent tests cases with Ant, use the following command :

ant test.case -Dtest.suite.case=Test -Dtest.suite.case.identity=scenario

e.g. for the org.jpox.RelationshipTest using datastore identity

ant test.case -Dtest.suite.case=**/RelationshipTest.class -Dtest.suite.case.identity=datastore

e.g. for the org.jpox.RelationshipTest using application identity

ant test.case -Dtest.suite.case=**/RelationshipTest.class -Dtest.suite.case.identity=application

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

Write your unit test, extending one of the common base classes in src/test/org/jpox, for example PersistenceTestCase.
Decide which test scenario your test fits into. It may fit in to more than 1 if necessary. You add the test to the test.properties file.
Run your test.

SCO Unit Tests

The SCO collection unit tests sit in their own area (org.jpox.sco) and are all related, in the same way as all java Collections are related. Each collection type has its own subdirectory containing helper classes and elements to be persisted. In addition there is one test class for each SCO collection class. The test class tests Normal and Inverse operation of the collection class.