How to run Castor JDO's test suite

# How to run Castor JDO's test suite

## Overview

At the time of this writing Castor JDO has 3 kinds of test suites:

- Database independend plan unit tests.

- A JUnit based test suite (CTF) that is used to test various functional areas against different database engines to give developers/committers some reassurance when changing the codebase.

- A Junit based test suite (PTF) to evaluate impact of changes on performance.

This document provides general information about running Castor JDO's test suite (CTF).

## Intended Audience

Anyone who wants to run the CTF test suite. This document outlines the basic steps to get people unfamiliar with this area started.

## Prerequisites

Anybody wishing to run the CTF test suite should have access to the source code of Castor. This can be obtained in one of the following ways:

- Download the sources distribution from the download page

- Download the latest snapshot from SVN from Fisheye (see links on the bottom left corner)

- Check out the latest code from SVN into your prefered developement environment. For instructions on this task, take a look at Subversion access. For eclipse How to setup Castor project in eclipse provides a detailed description of this task.

## 2 versions of CTF

At the moment we are in the middle of replacing the old CTF with a new one. While the old CTF still is our reference for refactorings of Castor does the new CTF contain some tests which could not be added to the old one due to its limitations. On the other hand are not all tests ported to the new CTF yet.

In the next sections we describe how to setup the environment to execute both CTF versions. While both versions of CTF are designed to be executed against every supported database engine, we will describe things with regard to mysql. Having said that there are only scripts for mysql at the new CTF at the moment. At a later step of the CTF refactoring we will add scripts for other databases as well. In addition we intend to allow its execution with an embedded derby database out of the box, but this have not been implemented yet.

For those who might be wondering about the numbering of tests, the numbers of the old tests are just random. The numbers of the new tests are the jira issue numbers.

## Steps to setup environment for old CTF

To execute tests against mysql database you probably need access to a mysql server. To create a database for CTF, you have to execute the following commands on mysql consol.

    # create database test;
    # grant all on test.* at "localhost" to "test" identified by "test";
    # use test;
    # source [path-to-script];

If the server is not installed on your local machine (the one you execute the tests on) you have to replace "`localhost`" with the IP of the machine the tests get executed on. The script to execute can be found in "`cpactf/src/old/ddl/`" directory. For mysql it's "`mysql.sql`". If you like to use a different name for the database or use other user credential you can adjust them at "`cpactf/src/old/resources/jdo/mysql.xml`".

As we do not include JDBC drivers for every database with Castor you also have to add the driver you like to use to your classpath to execute the tests. The easiest way is to copy the driver to "`lib/`" directory as all jar's contained therein are added automatically. Another option is to modify "`bin/test.sh`" or "`bin/test.bat`" script depended on your operating system.

For mysql we still use "`mysql-connector-java-3.1.13-bin`", also for mysql server of version 5. This version has proven to be stable. While other versions of mysql connector may also work, some of them have bugs from our experience.

As already explained you will find JDO configurations for every supported database in "`cpactf/src/old/resources/jdo`". The JDO configurations are named `mysql.xml`, `oracle.xml` etc. In the same directory you will also find main mapping file "`mapping.xml`" that includes all other mappings which are located in the "`cpactf/src/old/resources/ctf/jdo/...`" directories. There is one more important file for the old tests "`cpactf/src/old/resources/tests.xml`", it is the main config file which defines which test should be executed against which database engine. As mentioned previously not every test works with every database engine as some missing some features or castor does not support everything of every engine.

## Steps to run old CTF from commandline

From a command line (e.g a shell), please execute the following commands to run the whole test suite against mysql (where `<castor-root>` points to the directory where you installed the Castor sources:

    cd <castor-root>/bin
    build clean
    build tests
    test castor.mysql

To execute just one of the many tests of the complete test suite, please change this to:

    cd <castor-root>/bin
    build clean
    build tests
    test castor.mysql.TC30

You have to execute "`build clean`" and "`build tests`" again if you have changed anything within eclipse (e.g. a configuration file or a class).

## Steps to run old CTF out of eclipse

Now, let's see how we can run these old CPACTF tests through eclipse.

- Go to "/cpacft/src/old/java" and right click

- Select `Run As -> Run...`

- Select `"Java Application"` from the left side menu and double click on it to create `"New_configuration"`.

- Select `Project -> castor`

- Enter `Main class -> MainApp`

- Select Arguments Tab

- Enter `Program Arguments` for example: "`castor.mysql.TC31`" or "`castor.mysql`"

- Now "Run"

## Short description of the old CTF tests

As some features are not supported by all database engines (e.g. sequence keygenerator) or a test have not been verified against a database, only a subset of the following tests will be executed if you run CTF.

- TC01 Duplicate key detection tests.

- TC02 Concurrent access tests.

- TC03 Read only tests.

- TC04 Deadlock detection tests.

- TC05 Update rollback tests.

- TC06 Race tests.

- TC07 Cache leakage tests.

- TC08 Cache expiry measure.

- TC09 TxSynchronizable interceptor tests.

- TC10 Type handling tests.

- TC11 Type handling of LOB tests.

- TC12 Type Conversion tests.

- TC13 Serializable object tests.

- TC14 Rollback primitive tests.

- TC15 Multiple columns primary keys tests.

- TC15a Multiple columns primary keys only tests.

- TC16 Nested fields tests.

- TC17 Timestamp tests.

- TC18 Persistence interface tests.

- TC19 InstanceFactory interface tests.

- TC20 Key generators: MAX, HIGH-LOW.

- TC23 Key generator: IDENTITY.

- TC24 Key generator: UUID.

- TC25 Dependent objects tests.

- TC26 Dependent objects tests.

- TC27 Dependent update objects tests.

- TC28 Dependent update objects tests.

- TC30 OQL-supported syntax.

- TC31 OQL queries for extends.

- TC32 Test limit clause.

- TC33 Test limit clause with offset.

- TC34 Test limit clause with offset at extended object.

- TC36 SizeOracle.

- TC37 Absolute.

- TC38 CALL SQL with parameters.

- TC38a Named query support.

- TC70 Collections.

- TC71 Test special collections.

- TC72 Test sorted collections.

- TC73 ManyToMany.

- TC74 ManyToManyKeyGen.

- TC75 Expire Many-To-Many.

- TC76 Cached OID with db-locked.

- TC77 Query garbage collected.

- TC78 JDBC connection.

- TC79 Test the use of Database.isLocked().

- TC79a Test auto-store attribute.

- TC79aa Test auto-store attribute for 1:M relations.

- TC79b Test the use of Database.isPersistent().

- TC80 self-referential relation test with extend hierarchies.

- TC81 Dependent relation test.

- TC82 Dependent relation test (using no key generators).

- TC83 Identity definition through identity attribute in field mapping.

- TC84 Transient attribute.

- TC85 TestEnum.

- TC87 TestLazy1to1.

- TC88 Lazy Loading.

- TC89 Expire Lazy Employee.

- TC93 Polymorphism Degenerated tests.

- TC94 Polymorphism tests.

- TC95 Polymorphism tests with key generator.

- TC96 Polymorphism tests for depend relations.

- TC97 Polymorphism tests.

- TC98 Polymorphism tests in a threaded environment.

- TC99 Polymorphism tests (many 2 many).

- TC200 Self-referential relation tests.

- TC201 Self-referential relation tests with extend hierarchy.

- TC202 ForeignKeyFirst tests.

- TC203 Timezone tests.

## Steps to setup environment for new CTF

To execute tests against mysql database you probably need access to a mysql server. To create a database for CTF, you have to execute the following commands on mysql console.

    # create database cpactf;
    # grant all on cpactf.* at "localhost" to "test" identified by "test";
    # use cpactf;
    # source <path-to-script>;

If the server is not installed on your local maschine (the one you execute the tests on) you have to replace "`localhost`" with the IP of the maschine the tests get executed on. For mysql execute every "`mysql.sql`" script found in subdirectories of "`cpactf/src/test/ddl/`" directory. If you like to use a different name for the database or use other user credential you can adjust them at "`cpactf/src/test/resources/cpactf-conf.xml`".

As we do not include JDBC drivers for every database with Castor you also have to add the driver you like to use to your classpath to execute the tests. The easiest way is to copy the driver to "`lib/`" directory as all jar's contained therein are added automatically. Another option is to modify "`bin/test.sh`" or "`bin/test.bat`" script depended on your operating system.

For mysql we still use "`mysql-connector-java-3.1.13-bin`", also for mysql server of version 5. This version has proven to be stable. While other versions of mysql connector may also work, some of them have bugs from our experience.

## Steps to run new CTF out of eclipse

Execution of the new test suite from within eclipse against mysql is very simple.

- Select "cpactf/src/test/java" and right click

- Select "`Run as`" -> "`JUnit tests`"

In in the configuration file "cpactf-conf.xml" mysql is configuerd as default database. To execute tests against another database engine or to force execution of tests that have been excluded you can pass VM parameter to the test framework. VM Arguments can also be specified in eclipse.

- Select "`Run as`" -> "`Run..`" from main menu

- Select Arguments Tab

- Enter `VM Arguments` for example: "`-Dname=value`"

- Now "`Run`"

The following VM parameters are supported by CTF.

config

  Path to an alternate configuration file.

database

  Name of the database configuration.

transaction

  Name of the transaction manager configuration.

force

  Force execution of excluded tests (true/false).

## Troubleshooting

For those who face the following problem in eclipse while executing the tests

    #An unexpected error has been detected by HotSpot Virtual Machine:
    #
    #EXCEPTION_ACCESS_VIOLATION (0xc0000005) at pc=0x7c918fea, pid=2460, tid=3712
    #
    #Java VM: Java HotSpot(TM) Client VM (1.5.0-b64 mixed mode)
    #Problematic frame:
    #C [ntdll.dll+0x18fea]
    #
    #An error report file with more information is saved as hs_err_pid2460.log
    #
    #            If you would like to submit a bug report, please visit:
    #              http://java.sun.com/webapps/bugreport/crash.jsp
    #

It is a problem with memory configured for eclipse. It can be changed in `eclipse.ini` file which can be found in installation directory of Eclipse. By default it is `-Xmx256m`, just increase it and problem go away.

## References

- How to setup Castor project in eclipse

- Subversion access

- The testing framework