JOnAS Test Suite

Table of contents

Aim of the suite

The aim of this suite is to provide tests that verify that JOnAS conforms to the EJB specifications. This suite is used to identify regressions in contributions made in the JOnAS code. This suite is far from complete and will be expanded in the future. Anyone is welcome to write or add new test cases to this suite according to the guidelines explained below.

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.forge.objectweb.org:/cvsroot/jonas login
cvs -d :pserver:anonymous@cvs.forge.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 will find different test suites :

conformance test of EJB spec conformance
stress test of robustness and scalibility
j2eeca test Application Server conformance to J2EE Connector Architecture

Other suites are likely to be added in the future.

conformance and stress are made of the following files and directories:

build.xml ant file to build and run all the tests
src source files
junit.sh script to run 1 or more tests

The source code is organized according to the package name. So, for the conformance test suite, the source is located in src/org/objectweb/jonas/jtests :

beans Each directory contains code for a set of beans (a ejb-jar file)
annuaire session bean accessing entity beans
beanexc beans used for exception testing
cluster entity beans with shared attribute
ebasic
folder mainly to test local interfaces
j2eeca beans used for jca 1.0 Connector Architecture testing
jca15 beans used for JCA 1.5 Connector Architecture testing
jdbcra beans used for jdbc resource adapter testing
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 test suites 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
j2eeca tests related to JCA 1.0 Connector Architecture testing
jca15 tests related to JCA 1.5 Connector Architecture testing
jdbcra tests related to JDBC RA testing
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 the DDs with emacs).
tables The definition of a session bean used for creating and initializing the database tables used by tests.
templates Templates of a test suite.
util Utility classes.

The stress test suite structure is slightly different, in fact simplified. This documentation focuses on the conformance test suite, however, all tests can be applied to 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.

The 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 suites.
report to run the all set and produce a report

To build the jonas tests :

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

  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 needs only one datasource with jdbc_1 as datasource.name.
    The jms service must be set in jonas.services property.
  2. Run the JOnAS Server : jonas start
  3. Once it is running you can launch the complete JOnAS test suite via the report ant target.
  4. A test suite report is generated under jonas_tests/conformance/reports/html.

Using JDBC Resource Adapter

To execute the JDBC Resouce Adapter tests, two datasources jdbc_xa1 and jdbc_xa2 are required.

  1. Update the jonas.properties file according to your environment.
    Replace the dbm service with resource in jonas.services property.
  2. There are four JDBC Resource Adapters available:
    Data Manager
    Data Service
    Connection Pool
    XA Support
  3. Configure the deployment descriptors to access the JDBC driver.
  4. Reference the JOnAS documentation for configuration details.

Running J2EE Connector Architecture 1.5 (JCA 1.5) tests

To execute the jca 1.5 tests, a fictional Resource Adapter is created when the jonas_test suite is built. Verify the following to assure proper setup of the test.

  1. Update the jonas.properties file according to your environment. Include resource in the jonas.services property. For example,
    jonas.services registry,jmx,jtm,dbm,security,jms,resource,ejb,web,ear
  2. The deployed Ersatz (fictional) Resource Adapters are deployed in the JONAS_BASE rar autoload area.
    eis/ErsatxEIS.rar
    eis/ErsatzNolog.rar
    eis/ErsatzSecurity.rar
    eis/ErsatzLoTransaction.rar
    eis/ErsatzXATransaction.rar
  3. Add entries to the trace.properties files if traces are desired. The entries should look like the following.
    # ------------------------------------------------
    # logger definitions
    # ------------------------------------------------
    #logger.org.objectweb.jonas_tests.level DEBUG
    logger.org.objectweb.jonas.jtests.j2eeca.level DEBUG
    logger.ersatz.resourceadapter.level DEBUG
    logger.fictional.resourceadapter.level DEBUG (for JCA 1.0 only)

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.

To do this a script jonas_tests/junit.bat can be run. Depending on the number of arguments, you will run:

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

Windows Example:

junit conformance jca15
junit conformance jca15 F_connectorTest testConnectionBasics
    

Update the junit.bat file according to your environment. Note the location of TEST_CLASSES, JPROJ_BASE and ANT_HOME.

Naming conventions

In order to have a homogeneous suite we have defined strict naming conventions that should be followed. This makes it easier to understand a test suite.

The coding conventions 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 that work together. Assuming we choose:
bdir directory for this bean
bname name of this bean
To avoid name conflicts in JNDI, the bdir/bname combination must be unique in the junit suite . 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(cmp version 1.x)
EC2 entity bean with container managed persistence(cmp version 2.x)
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 improve the readability of these files and to know which suite can be run with which testcase, we have enforced the following 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 separately, but not with only 1 testcase. Their main routine should be very simple, only 1 line.
F_name.java Final suites that can be run separately 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 writing new tests

Creating a new suite

Adding test cases to an existing suite

Adding a new test case is pretty straightforward. Have a look at the tests already written then mimic them. In most cases you will not have to catch exceptions. So the tests look very simple. You can refer to the junit primer for more details.

Submitting a contribution to jonas team

Follow the same rules as for contributing to jonas.

Current conformance test results

You can find conformance test results for the most recent JOnAS builds on the Objectweb website at http://jonas.objectweb.org/tests.html. The suite results are organized by configuration. Each configuration is identified as follows:

ORB/Operating System/DataSource/JDK version/JOnAS build

e.g. RMI / Solaris / Oracle / JDK1.3/JOnAS-Tomcat