Development
Core Plugins
Datastores
Documentation
Testing
DataNucleus : Unit Tests

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

  • Component tests - the traditional "unit" test and these are stored in SVN 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 projects in SVN

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 SVN. If your change breaks things, you shouldn't check things in. Each test "scenario" has its own project in SVN 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.jdo.db4o - Tests specific to DB4O, using JDO
  • test.jdo.rdbms - Tests specific to RDBMS, using JDO
  • test.jdo.rdbms.datastore - Tests specific to RDBMS with datastore id, using JDO
  • test.jdo.rdbms.application - Tests specific to RDBMS with app id, using JDO
  • test.jdo.ldap - Tests specific to LDAP, using JDO
  • test.jdo.excel - Tests specific to Excel, using JDO
  • test.jpa.general - General tests for JPA
  • test.jpa.rdbms - Tests specific to RDBMS, using JPA


JCA Test Scenarios

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

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


Testing with Maven1

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 "DataNucleus" plugin to enhance. Before running any tests, you need to build and install the plugin by typing the following from within "tools/maven1/trunk" 

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 Maven2

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.

To run the scenario tests you need to have the Maven2 DataNucleus plugin installed. If you want to build this yourself you can go to "tools/maven2/trunk" and type 

mvn clean install

Running the tests

From within one of the test projects, you simply type 

mvn clean test

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

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

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

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

  1. Install the DataNucleus Eclipse Plugin.
  2. Add enhancement to the DataNucleus project. Right Click on the project > DataNucleus > Enhance with DataNucleus 1.1 .

  3. Setup the enhancement. Right Click on the project > DataNucleus > 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".

  4. 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 DataNucleus enhancement, follow the next steps:

  1. Create a new Java application for run or debug. In Eclipse, click on the menu Run and Run... or Debug... .
  2. Click on the Java Application and New
  3. Set up the configuration as presented on the next screenshots.



  4. Input all of the jdo (jdo,jdod,jdoa) files with space to separate each file.



  5. Make sure the classpath is correct.



  6. 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.datanucleus.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/datanucleus-hsql. 1 .properties, and
  • test.framework/src/conf/datanucleus-hsql. 2 .properties

The default database configured in the test projects is hsqldb.

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

HSQLDB

For general information about running HSQLDB see the HSQL documentation. Following 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 HSQLDB 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.