Section : Documentation > Development

Component Tests

DataNucleus uses JUnit for unit testing. The traditional style of unit test are included with the project that they are testing. For example core has some unit tests, and these are run when you build the project. In general DataNucleus doesnt have many of this style of tests (youre welcome to write some) because the more important aspect of testing is the actual reading/writing involving the datastore (see below).

End-to-End Tests

End-to-End tests also use JUnit, and are available in the GitHub DataNucleus repository tests. In these tests we persist objects in a datastore, and test the result. There are several scenarios for this type of test, because JDO/JPA have many aspects. By this we mean that we separate our tests into what they test. When developing anything, the tests should be the guiding light as to whether you should be checking anything in to GitHub. If your change breaks things, you shouldnt check things in. We have tests divided by the persistence API that they are testing; look under the directories jdo, jpa and rest.

framework

All DataNucleus end-to-end tests are based around a framework and this requires building first before running any tests. Navigate into the framework directory, and build and install it by typing

mvn clean install

This builds the jar under target and installs it into your Maven repository.

framework.maven

This is a Maven plugin that allows some of the tests to be run with different configurations. You should build and install it by typing

mvn clean install

This builds the jar under target and installs it into your Maven repository.

samples

The samples project provides typical model classes to be persisted, with all different types of relations. This project doesnt define how the classes are persisted, just what the classes are. They are then usable by all persistence APIs. You should build and install it by typing

mvn clean install

This builds the jar under target and installs it into your Maven repository.

End-to-End Test Scenarios

So we have now built the framework, framework.maven and samples projects and are ready to run any of the scenarios. There are many scenarios including

  • Tests for JDO API
    • jdo/general - General tests for JDO
    • jdo/identity - Tests for JDO that run with both application and datastore identity types
    • jdo/jta - Tests for using JTA transactions with JDO
    • jdo/geospatial - Tests for use spatial types with JDO
    • jdo/rdbms - Tests specific to RDBMS, using JDO
    • jdo/ldap - Tests specific to LDAP, using JDO
    • jdo/spreadsheet - Tests specific to Excel and ODF, using JDO
    • jdo/hbase - Tests for basic handling with HBase, using JDO
    • jdo/mongodb - Tests for basic handling with MongoDB, using JDO
  • Tests for JPA API
    • jpa/general - General tests for JPA
    • jpa/jta - Tests for using JTA transaction with JPA
    • jpa/geospatial - Tests for using spatial types with JPA
    • jpa/rdbms - Tests specific to RDBMS, using JPA
  • Tests for REST API
    • rest/general - Tests using the REST API

To run a test scenario, go into the scenario project and type

mvn clean test

This then runs the tests for that scenario. There are also occasionally additional tests under org.datanucleus.tests.knownbugs and org.datanucleus.tests.newfeatures intended for incorporation into the test scenario at some later point; these are not run by default.

To run the tests on a different datastore (default=H2) type

mvn clean test -Pmysql

or replace mysql with postgresql, oracle, mongodb, hbase etc

Long term strategy is to just have the overall test scenarios that apply just to JDO or JPA and drop the datastore-specific scenarios except where providing some feature specific to that datastore. Reality is that we dont have resource to do this yet, so typically run such as test.jdo.mongodb for testing MongoDB, which obviously only tests a small subset of what ought to be tested. Offering your time to make all store plugins more feature complete is the only way this task will be performed.

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 (e.g jdo/general, jpa/general)
  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, or JPAPersistenceTestCase
  4. Run your test.
  5. Raise a JIRA and attach your testcase to the issue

Alternate Test Configurations

All tests run with a default test configuration (see the files in framework under src/conf). You can, with some test suites, run alternate test configurations. This is achieved using the framework.maven Maven plugin.

  1. Look for a configuration file under src/conf of framework such as optimistic-conf.properties. These properties are used to override the default properties
  2. Run the tests with -Dtest.configs=optimistic or -Dtest.configs=optimistic,pessimistic for example

JDO TCK

DataNucleus GitHub master passes the JDO TCK, and hence is a fully-compliant implementation of JDO. All developers should run this TCK from time to time to validate any changes. The following shows the results of the TCK as proof of compatibility. You can, of course, simply run DataNucleus yourself with the JDO TCK (downloadable from the Apache JDO Project). JDO is an open standard, being developed by the Apache JDO project. As yet there are no other fully compliant implementations of JDO, publishing their results on a publically visible website; dont believe their claims of compliance unless they post this output below. The tests below were run with DataNucleus GitHub master (v3.3) on 20/Dec/2013.

app-runonce-junit.txt:
    OK Tests run: 002, Time: 002 seconds.
app-instancecallbacks-junit.txt:
    OK Tests run: 016, Time: 003 seconds.
app-jdohelper-junit.txt:
    OK Tests run: 045, Time: 003 seconds.
app-pm-junit.txt:
    OK Tests run: 167, Time: 029 seconds.
app-pmf-junit.txt:
    OK Tests run: 068, Time: 024 seconds.
app-detach-junit.txt:
    OK Tests run: 018, Time: 004 seconds.
app-embeddedInheritance-junit.txt:
    OK Tests run: 004, Time: 002 seconds.
app-enhancement-junit.txt:
    OK Tests run: 031, Time: 003 seconds.
app-extents-junit.txt:
    OK Tests run: 013, Time: 005 seconds.
app-fetchplan-junit.txt:
    OK Tests run: 021, Time: 003 seconds.
app-fetchgroup-junit.txt:
    OK Tests run: 035, Time: 002 seconds.
app-lifecycle-junit.txt:
    OK Tests run: 017, Time: 006 seconds.
app-models-junit.txt:
    OK Tests run: 050, Time: 093 seconds.
app-models1-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-query-junit.txt:
    OK Tests run: 159, Time: 027 seconds.
app-jdoql-junit.txt:
    OK Tests run: 134, Time: 028 seconds.
app-jdoql1-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-transactions-junit.txt:
    OK Tests run: 030, Time: 004 seconds.
app-companyNoRelationships-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyEmbedded-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-company1-1Relationships-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-company1-MRelationships-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyM-MRelationships-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAllRelationships-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyMapWithoutJoin-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyListWithoutJoin-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyPMClass-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyPMInterface-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotated1-1RelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotated1-MRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotatedAllRelationshipsFCConcrete-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedAllRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedAllRelationshipsPCConcrete-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedAllRelationshipsJPAConcrete-junit.txt:
    OK Tests run: 001, Time: 006 seconds.
app-companyAnnotatedAllRelationshipsJPAPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedAllRelationshipsPCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedAllRelationshipsPIPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedEmbeddedFCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedM-MRelationshipsFCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotatedM-MRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotatedNoRelationshipsFCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotatedNoRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotatedNoRelationshipsPCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-companyAnnotatedEmbeddedJPAConcrete-junit.txt:
    OK Tests run: 001, Time: 005 seconds.
app-companyAnnotatedEmbeddedJPAPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedNoRelationshipsPCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
app-companyAnnotatedNoRelationshipsPIPM-junit.txt:
    OK Tests run: 001, Time: 005 seconds.
app-companyOverrideAnnotatedAllRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 005 seconds.
app-inheritance1-junit.txt:
    OK Tests run: 001, Time: 005 seconds.
app-inheritance2-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-inheritance3-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
app-inheritance4-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-relationshipAllRelationships-junit.txt:
    OK Tests run: 034, Time: 011 seconds.
app-relationshipNoRelationships-junit.txt:
    OK Tests run: 015, Time: 007 seconds.
app-schemaAttributeClass-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
app-schemaAttributeOrm-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
app-schemaAttributePackage-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
app-compoundIdentity-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
app-throwOnUnknownStandardProperties-junit.txt:
    OK Tests run: 002, Time: 000 seconds.
dsid-instancecallbacks-junit.txt:
    OK Tests run: 016, Time: 003 seconds.
dsid-jdohelper-junit.txt:
    OK Tests run: 045, Time: 003 seconds.
dsid-pm-junit.txt:
    OK Tests run: 167, Time: 030 seconds.
dsid-pmf-junit.txt:
   OK Tests run: 068, Time: 021 seconds.
dsid-detach-junit.txt:
    OK Tests run: 018, Time: 003 seconds.
dsid-embeddedInheritance-junit.txt:
    OK Tests run: 004, Time: 002 seconds.
dsid-enhancement-junit.txt:
    OK Tests run: 031, Time: 001 seconds.
dsid-extents-junit.txt:
    OK Tests run: 013, Time: 005 seconds.
dsid-fetchplan-junit.txt:
    OK Tests run: 021, Time: 003 seconds.
dsid-fetchgroup-junit.txt:
    OK Tests run: 035, Time: 002 seconds.
dsid-lifecycle-junit.txt:
    OK Tests run: 017, Time: 007 seconds.
dsid-models-junit.txt:
    OK Tests run: 050, Time: 084 seconds.
dsid-models1-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-query-junit.txt:
    OK Tests run: 159, Time: 026 seconds.
dsid-jdoql-junit.txt:
    OK Tests run: 134, Time: 030 seconds.
dsid-jdoql1-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-transactions-junit.txt:
    OK Tests run: 030, Time: 004 seconds.
dsid-companyNoRelationships-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyEmbedded-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-company1-1Relationships-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-company1-MRelationships-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyM-MRelationships-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAllRelationships-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-companyMapWithoutJoin-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyListWithoutJoin-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyPMClass-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyPMInterface-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-companyAnnotated1-1RelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotated1-MRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedAllRelationshipsFCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedAllRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-companyAnnotatedAllRelationshipsPCConcrete-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-companyAnnotatedAllRelationshipsJPAConcrete-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
dsid-companyAnnotatedAllRelationshipsJPAPM-junit.txt:
    OK Tests run: 001, Time: 001 seconds.
dsid-companyAnnotatedAllRelationshipsPCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-companyAnnotatedAllRelationshipsPIPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-companyAnnotatedEmbeddedFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedM-MRelationshipsFCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedM-MRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedNoRelationshipsFCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedNoRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedNoRelationshipsPCConcrete-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedEmbeddedJPAConcrete-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
dsid-companyAnnotatedEmbeddedJPAPM-junit.txt:
    OK Tests run: 001, Time: 001 seconds.
dsid-companyAnnotatedNoRelationshipsPCPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyAnnotatedNoRelationshipsPIPM-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-companyOverrideAnnotatedAllRelationshipsFCPM-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-inheritance1-junit.txt:
    OK Tests run: 001, Time: 004 seconds.
dsid-inheritance2-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
dsid-inheritance3-junit.txt:
    OK Tests run: 001, Time: 001 seconds.
dsid-inheritance4-junit.txt:
    OK Tests run: 001, Time: 003 seconds.
dsid-relationshipAllRelationships-junit.txt:
    OK Tests run: 034, Time: 012 seconds.
dsid-relationshipNoRelationships-junit.txt:
    OK Tests run: 015, Time: 007 seconds.
dsid-schemaAttributeClass-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
dsid-schemaAttributeOrm-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
dsid-schemaAttributePackage-junit.txt:
    OK Tests run: 001, Time: 002 seconds.
dsid-compoundIdentity-junit.txt:
    OK Tests run: 001, Time: 001 seconds.
dsid-throwOnUnknownStandardProperties-junit.txt:
    OK Tests run: 002, Time: 000 seconds.
-------
Total tests run: 1800.
All (117) configurations passed.

JPA 1 TCK

All releases of DataNucleus since v1 pass the JPA1 (JSR 220) TCK. JPA1 is a standard developed in private by the JCP. Its discussions were not open and the TCK is not freely downloadable and so users cannot check any such claims for compliance. This is in direct contrast to the JDO standard. We leave it to users to decide how they feel about that. The tests below were run with JPA TCK 1.0b and DataNucleus GitHub master (v3.3) on 20/Dec/2013 against MySQL 5.0.37.

Completed running 435 tests.
Number of Tests Passed      = 435
Number of Tests Failed      = 0
Number of Tests with Errors = 0

Sadly Im not legally allowed to disclose any further details about these tests due to having to sign an NDA just to get hold of the TCK.

JPA 2+ TCK

As mentioned in this blog post we applied for the JPA 2.0 TCK on 8th February 2010. This request was handled by Jonathan Nimer and Patrick Curran at SUN/Oracle. They (eventually) provided us with a form to sign and return to gain access to the JPA2 TCK. This was returned to them at the end of April 2010 to their address of 4150 Network Circle, Santa Clara, CA 95054, USA. We have since prompted them on more than 3 occasions when we will be getting access to this secret TCK. They have still not provided it and as a result we are forced to claim full compliance with the JPA2 spec since testing is being hidden from us. The only possible conclusions for this unwillingness to provide the TCK as per their terms and conditions are either incompetence, or deliberate prevention of access. How do you, the user, feel about an organisation like Oracle preventing a level playing field for such technologies?

Since the JPA group have still not published an official JPA 2.0 / 2.1 API jar into Maven Central we really feel that their priorities are not in the best interests of you the user. The basic minimum should be publish the official JPA API jars, and get a public open source TCK. Once those are in place then we can talk

Databases Notes

Database setup for running tests

Each test project is run against a datastore (as defined above). The configuration of the datastores is stored under framework src/conf. Some tests require two database instances, which is why for every database there exist two files, e.g. maven.datanucleus.datastore=hsql refers to both

  • framework/src/conf/datanucleus-hsql.1.properties, and
  • framework/src/conf/datanucleus-hsql.2.properties

The default database configured in the test projects is H2.

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

Oracle 10.2.0

If you face the issue ORA-12519, TNS:no appropriate service handler, try increasing the parameters sessions and processes to 300 and _opencursors 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 _opencursors 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.