TestNG with JBoss Embeddable EJB3 Microcontainer

As a developer, you are always tempted to get by with smallest amount of unit testing...some even avoid the subject all together. With the introduction of EJB 3.0, it was intended to make things easier, including testing. Setting up the right test environment was always a difficult, especially when you don't always have the luxury of time to get it right!

The EJB3 cartridge now provides a basic test framework for your session beans. You can now use the popular TestNG framework, along with JBoss Embeddable EJB3 Microcontainer to perform your tests outside of the application server.

Read up on the JBoss Embedded container. Read about the TestNG framework.

The example widely available on the internet uses JUnit in combination with TestNG. The EJB3 cartridge only uses TestNG with Maven2. It is currently using TestNG version 4.7-jdk15 and JBoss Embeddable ALPHA_9.

Setup

You do not need to download any of the tools mentioned above. The cartridge will generate all the required configuration necessary for the JBoss Embeddable container. All the required artifacts are also available from the AndroMDA repository.

Because we consider testing such a key component of a project, there is no option to enable or disable the test framework with an EJB3 project. Everything is generated whether you want it or not. However, all the tests will finish successfully (as there is not implementation for them).

All you need to do is follow the project howto to generate your EJB3 project. Make sure you are running the latest AndroMDA since the test framework is only available from AndroMDA version 3.3-SNAPSHOT onwards.

The test framework will be generated as long as you have at least 1 session bean modeled in your project.

Configuration

The following are typical testing configuration files generated for an ejb3 project.

  • Auto-generated source that does not need manual editing
  • Auto-generated source that should be edited manually
  • File that is affected by the modifications applied in this section

When you first run mvn over your project, the cartridge will generate all the JBoss Embeddable container configuration files in core/src/test/resources. All these files are generated ONCE ONLY and will NOT be over-written. You can safely make any modifications to any of these files.

There is one exception to the latter. The testng.xml configuration file is also generated in core/src/test/resource, however, this is over-written on every run over your model. This is because when you add a new session bean, the trigger to run the tests for this new bean is inserted into the testng.xml file.

Once of the most interesting configuration files generated is the embedded-jboss-beans.xml. Take a look at your project's file and notice that the EJB3 cartridge has added your datasource to this file, along with the existing DefaultDS datasource, which is used by the JMS provider. You are free to modify the connection settings so that you point this to your development database server.

The log4j.xml file in this directory sets the Threshold to WARN by default. If you want to see more detailed log information to the console while the tests are running, change this to something like DEBUG.

The login-config.xml sets up the JAAS environment for your tests. If you had enabled security before running maven over your project the first time, everything will be generated for you and you don't need to worry about the following. If you had not enable security for your project on the first run, a relevant security context will not be generated for you in this file. Say that you want to enable security at a later point, then by simply following the security howto, you uncomment the securityRealm property in the ejb3 and the web framework namespaces. You must then copy the last application-policy section of the login-config.xml and change the name property to your application.id. If your project application id name is howtomodel, the login-config.xml should contain the following:

  <application-policy name="howtomodel">
    <authentication>
      <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule"
        flag="required"/>
    </authentication>
  </application-policy>

The cartridge will also generate a roles.properties and users.properties which will help provide basic JAAS authentication for users/roles.

Session Tests

Now take a look in your source folder core/src/test/java. You should have a file named EJB3Container.java in one of the packages here. This file starts and shuts down the embeddable container before and after running any tests respectively. It also provides helper static methods to get the InitialContext so you can retrieve the stub for the session bean (local or remote interface) from JNDI.

It is important to note that if you want to propagate security credentials (principal and password) because you have enable security and secured your session beans by modeling actors to the class or operations, you must use the overloaded getInitialContext methods with signature that allows you to provide a username and password. The generated tests actually provide a basic template that shows you how to do this.

In case you did not enable security on the first generation run, and find you need it later, apart from following the instructions above to modify the login-config.xml, you must also modify the EJB3Container.java to uncomment the following section in the startup method:

            logger.info("==>Deploying security-beans");
            EJB3StandaloneBootstrap.deployXmlResource("security-beans.xml");
            logger.info("==>Deployed security-beans");

Now open up any of the test classes. These are generated to the core/src/test/java source folder in the corresponding package. You will notice the EJB3 cartridge just creates one test case per session bean business operation. The the test source files will NOT be over-written, so if you add or delete business operations from your model, you must make the changes to these files manually.

You may have noticed how simple these test sources really are and you may be wondering how we start and stop the embeddable microcontainer and deploy our archives which contain the EJB 3 beans. Take a look at your testng.xml in core/src/test/resources. The first class listed to run is the EJB3Container. This will call the annotated methods to start and shutdown the embeddable container before and after your tests respectively.

You can now open the tests and add your implementation before running maven over the core project or running the tests.

Message Driven Tests

If you have one or more message driven beans, you must make sure the EJB3Container.java contains the following section in the startup method:

            logger.info("==>Deploying jboss-jms-beans - init JBoss MQ core services");
            EJB3StandaloneBootstrap.deployXmlResource("jboss-jms-beans.xml");
            logger.info("==>Deployed jboss-jms-beans");
            logger.info("==>Configure test queue and topic");
            EJB3StandaloneBootstrap.deployXmlResource("testjms.xml");
            logger.info("==>Configured test queues and topics");

The cartridge will generate one test class with one test case per message driven bean to the core/src/test/java source folder in the corresponding package. The the test source files will NOT be over-written, so if you wish, you can add further cases.

Take a look at your testng.xml in core/src/test/resources. Apart from the other session test classes, you also have a message driven test class reference. This is how message driven tests are triggered.

Finally, take a look at testjms.xml. This file contains the necessary configuration to create the queue/topics within the embedded container before the MDB's are deployed and tests are run. This file will be automatically re-generated on every run, so when you add another MDB, this file will be updated to reflect the addition of another queue or topic.

For your message driven test framework to work, you need to make sure the jms-ra.rar and jcainflow.rar RAR files exist in your project src/test/resources folder. These are from JBoss Embeddable Microcontainer lib. When you run your model generation phase, these libs will be automatically copied to your resources folder. We are forced to do this until Eclipse (perhaps other IDE's don't have this issue) can include .rar files in the project classpath.