JOnAS Test Suite

Table of contents

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. 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.jonas.debian-sf.objectweb.org:/cvsroot/jonas login
  cvs -d:pserver:anonymous@cvs.jonas.debian-sf.objectweb.org:/cvsroot/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 currently these test suites :
conformancetest of EJB spec conformance
stresstest of robustness and scalibility
perfstest used for performance measurements
samplehttptest used to do load tests for servlet+ejb
Other suites are likely to be added in the future.

conformance and stress are made of the following files and directories:
build.xmlant file to build and run all the tests
srcsource files
junit.shscript to run 1 or more tests

The set of sources is organized according to the package name. So, for the conformance test suite, the sources are located in src/org/objectweb/jonas/jtests :
beans Each directory contains code for a set of beans (an ejb-jar file)
annuaire session bean accessing entity beans
beanexc beans used for exception testing
bmt beans with bean managed persistance
cluster entity beans with shared attribute
ebasic miscellaneous entity beans
ejbql CMP2 entity beans used to test Ejb-QL
etype Entity beans used to test different type fields
folder mainly to test local interfaces
inherit beans used for testing inheritance
jdbc beans used for testing jdbc drivers
local beans used for local interfaces testing
message beans used for jms testing
relation, relationship, relatives CMP2 beans for different relationship 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). After a cvs co, this directory is empty. You must run "ant dtds" to populate this directory.
tables The definition of a session bean used for creating and initialize the database tables used by tests. This is not used in case of entity beans CMP2.x because the container is able to create the tables if they don't exist yet.
templates Templates of a test suite.
util Utility classes.
Concerning the stress test suite, the structure is slightly different, in fact more simple. This documentation focuses on the conformance test suite, but all can be applied for the stress test suite.

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
install for installing ejbjars under $JONAS_ROOT/ejbjars This target should be used to rebuild all the test suite.
runtest to run the all set and produce a report

To build the jonas tests :

  1. Customize jonas_tests/build.properties according to your environment. You may want for example define mappers for your DataBase, or set debug option.
  2. Go to the jonas_tests/ directory and type
    ant install

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 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 jonas.properties file according to your environment.
    Actually, the JOnAS suite need only one datasource with jdbc_1 as datasource.name.
    The jms service must be set in jonas.services property.
  2. Run the JOnAS Server with name "EJB" : jonas start -n EJB
  3. Once it is running, You can launch the complete JOnAS test suite via the runtest ant target.
  4. 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, there is a script jonas_tests/conformance/junit.sh that can be run. 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 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 :

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:
bdirdirectory for this bean
bnamename 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 interfacebname
optional home interfacebnameHome
optional local interfacebnameLocal
optional local home interfacebnameLocalHome
bean class implementationbnameXX
optional primary key classbnamePK
jar file namebname.jar
ejb-name in ddbnameXX
display-name in ddbdir/bnameXX
JNDI name for homebdirbnameXXHome
table name in DB (entity)JT_bdirbnameXX
field names (entity CMP)c_field

XX must be one of the following values :
EBentity bean with bean managed persistence
ECentity bean with container managed persistence(cmp version 1.x)
EC2entity bean with container managed persistence(cmp version 2.x)
SLsession bean stateless
SFsession bean stateful
SYsession bean stateful implementing Synchronization interface
STsession bean stateful with bean managed transactions
MDmessage 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

Creating a new suite

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.