# Jonas Test Suite

## Aim of the Suite

The aim of this suite is to provide tests that verify that JOnAS is conform to the EJB Specifications. This suite may be used to control that there is no regression when contributions are made in the JOnAS code.

This suite is far from complete and will be incremented in the future. In particular there are no tests on performance or scalability yet.

Everybody is welcome for writing and adding new testcases in this suite.

Note that this test suite has been done to test JOnAS, and its use to test other application servers is not straightforward.

## Getting the Suite from CVS repository

Anyone can checkout source code from our anonymous CVS server. To do so, simply use the following commands (if you are using a GUI CVS client, configure it appropriatly):

      cvs -d :pserver:anonymous@cvs.objectweb.org:/cvs/Jonas login
      cvs -d :pserver:anonymous@cvs.objectweb.org:/cvs/Jonas co jonas_tests

When prompted for a password for anonymous, simply press the Enter key.

## Description of the source tree

Under `jonas_tests` you can find the conformance suite test. Other suites (performance, stress, etc.) are likely to be added in the future.

conformance is made of the following directories:

doc | test documentation (this file)
scripts | scripts to build and run tests
src | source files

The set of sources is organized according to the package name. So, the sources are located in src/org/objectweb/jonas/jtests :

beans

Each directory contains code for a set of beans (a ejb-jar file)

annuaire |
beanexc | beans used for exception testing
ebasic |
folder |
local | beans used for local interfaces testing
message | beans used for jms testing
secured | beans used for security testing
transacted | beans used for transaction testing
remoterunner | beans used for running junit testsuites on the server side.

clients

Each directory contains code for a set of test suites.

distribution | tests related to the chapter 19 of the Specs EJB2.0
entity | tests related to the chapter 9,10,11,12,14 of the Specs EJB2.0
exception | tests related to the chapter 18 of the Specs EJB2.0
jms |
local | test suites that must be run on the server side
security | tests related to the chapter 21 of the Specs EJB2.0
session | tests related to the chapter 6,7 of the Specs EJB2.0
suite | suite that run all the suites
transaction | tests related to the chapter 17 of the Specs EJB2.0

dtds | A local copy of the dtds used in the deployment descriptors. (Useful to be able to edit friendly the DDs with emacs).
tables | The definition of a session bean used for creating and initialize the database tables used by tests.
templates | Templates of a test suite.
util | Utility classes.

## Building the suite

### Using ant

This test has been designed to be compiled and run using Ant.
Ant must be installed (with the optional tasks package) and the environment variables `%ANT_HOME%` or `$ANT_HOME` must be set.
`$ANT_HOME/bin` must have been added to the `PATH` environment variable.
The xalan product must be installed, and the `xalan.jar` must be present in `$ANT_HOME/lib`. (xalan is necessary for the JUnitReport ant task).
The JUnit product must also be installed, and the `junit.jar` must be present in `$ANT_HOME/lib`.
For xalan and JUnit, you may also choose to update the file $JONAS_ROOT/bin/unix/config_env (on Unix) or %JONAS_ROOT%\bin\nt\config_env.bat (on Windows) by adding the path to `xalan.jar` and `junit.jar` in the predefined classpath used by JOnAS which is defined in this file.

Main Ant targets are the following :

clean | for deleting all generated classes
compile | for compiling all java classes
deploy | for deploying, generating ejbjars
install | for installing ejbjars under $JONAS_ROOT/ejbjars This target should be used to rebuild all the test suite.

To build the jonas tests :

1. Customize jonas-tests/conformance/scripts/build.properties according to your environment.

2. Go to the jonas-tests/conformance/scripts directory and type
   `sh build.sh install` on Unix or
   `build install` on Windows

### Using make

1. Set the correct paths for all the jar files included in classpath.
   For this, edit the file `$JONAS_ROOT/gmk/config.mk` and follow the instructions at the end of the file.

2. Then you have to do is:

         cd $OBJECTWEB_HOME/jonas_test/conformance
         make

## Running the suite

### Using Ant

You can launch the complete JOnAS test suite via Ant and obtain a test suite report.

You should use the XTRA_CLASSPATH environment variable or modify the predefined classpath used by JOnAS in the $JONAS_ROOT/bin/unix/config_env (on Unix) or %JONAS_ROOT%\bin\nt\config_env.bat (on Windows) file, by adding the path to jonas_tests/conformance/classes/$OBJECTWEB_ORB.

1. Update the dbm.datasources property in the jonas-tests/conformance/scripts/build.properties file according to your environment.
   Actually, the JOnAS suite need only one datasource with jdbc_1 as datasource.name.

2. You can launch the complete JOnAS test suite via the batchtest ant target.

3. Then you obtain a test suite report generated under jonas_tests/conformance/reports/html.

### Using scripts

It may be interesting to launch only one of the suites or only one testcase of a test suite, particularly to debug a testcase that fails.

For that, you can find under the jonas_tests/conformance/scripts directory two Unix scripts.

ser1.sh must be run first, after a slight customization. It will run the EJBServer. EJBServer name is EJB. You will have to customize DATASOURCES variable according to the datasource file you use.

junit.sh can be run then. Depending on the number of arguments, you will run

1. all the junit tests
2. all suite in a client directory
3. 1 named suite in a directory
4. 1 testCase in 1 particular suite in a directory

Exemple:

    sh ser1.sh
    sh junit.sh security
    sh junit.sh entity F_BasicHomeInterfaceEB testFinderEnumObjNotFound

## Naming conventions

In order to have an homogeneous suite we have defined strict naming conventions that it is worth to follow. This make easier the understanding of a test suite.

The coding convention are related to :

- file names for the suite classes
- interfaces, beans, deployment descriptor, ejb-jar names
- ejb-name, jndi names, table names in DB, field names
- etc.

### Rules for bean names in the tests

Beans must be put in a directory under src/org/objectweb/jonas/jtests/beans. Each directory will produce a jar file holding a set of beans working together. Assuming we choose:

bdir | directory for this bean
bname | name of this bean

The couple bdir/bname must be unique in the junit suite, to avoid name conflicts in JNDI. Other names can be deduced from these:

optional remote interface | bname
optional home interface | bnameHome
optional local interface | bnameLocal
optional local home interface | bnameLocalHome
bean class implementation | bnameXX
optional primary key class | bnamePK
jar file name | bname.jar
ejb-name in dd | bnameXX
display-name in dd | bdir/bnameXX
JNDI name for home | bdirbnameXXHome
table name in DB (entity) | bdirbnameXX
field names (entity CMP) | c_field

XX must be one of the following values :

EB | entity bean with bean managed persistence
EC | entity bean with container managed persistence
SL | session bean stateless
SF | session bean stateful
SY | session bean stateful implementing Synchronization interface
ST | session bean stateful with bean managed transactions
MD | message driven bean

Note : that these rules are inforced when using the Newbean tool.

### Rules for files names for the client suites

Each directory in src/org/objectweb/jonas/jtests/clients holds a set of test suites relative to a common topic (entity, session, transaction, etc...). To ease the readability of these files and to know what Suite can be run with 1 testcase, we have enforced these naming conventions :

A_name.java | Abstract class holding test cases shared by several suites. These files cannot be run as a test suite, since they do not have a main.
C_name.java | Composite Suites that link several Suites together. They can be run separatly, but not with only 1 testCase. Their main routine should be very simple, only 1 ligne.
F_name.java | Final Suites that can be run separatly or with only 1 testCase. They must have a main routine with a -n arg to be able to be run with a specified test case.

## How to contribute ?

### Coding conventions

Coding conventions are the same for jonas or for jonas_tests. They must follow Code Conventions for the JavaTM Programming Language

### Methodology for writting new tests

- Each testCase must be independant of the others. Moreover, it is possible to run more than once each testcase without problem. This implies to clean everything after the test, for example, a testCase creating an instance should remove it before returning.
- Beans and clients are in different packages. All beans should be under beans directory, all clients (tests) should be in clients directory. A useBean() method must be used in the client to ask the EJBServer to load a bean, if not loaded yet.
- When loading entity beans the first time in the server, tables in database are dropped and created. This is to avoid problems due to previous run of tests. This is done by setting a boolean in useBean
- Each testCase name must begin by the String test. Inside the tests method, no need to try/catch unexpected exceptions. Only catch exception that are expected.

### Creating a new suite

- You must first decide in which directory your Suite should be. A limited number of directories has been defined in clients, See Structure of source code You should not add a new directory since all needed directories have already been defined.
- An exemple of Suites is given in src/org/objectweb/jonas/jtests/templates
- More sofisticated suites can be found for example in src/org/objectweb/jonas/jtests/clients/entity

### Adding testcases in an existing suite

Adding a new test case is pretty straightforward. Have a look at the test already written, and mimic them. Basically, you will not have to catch exceptions, most of the time, so the tests look very simple. You can refer to the junit primer for more details.

### Submitting a contribution to jonas team

Today, you must follow the same rules than for jonas.