JUnitEE Tutorial

JUnitEE

$Revision: 1.10 $

This tutorial will show you how to use JUnitEE to unit test an Enterprise JavaBean. All sources are included in the example directory of the JUnitEE distribution and are also browsable online.

Implement the EJB

As this is a tutorial on testing and not on implementing EJBs I will not go into details on how to write Enterprise JavaBeans. I assume that you already have some knowledge about this kind of stuff, otherwise you would not be interested in testing EJBs.

The EJB used for this tutorial is a simple session bean which adds two numbers. Have a look at the sources in the package org.junitee.ejb.einstein to see what is going on in the bean. The method addTwoNumbers is a little bit buggy to show the effect of a test failure, the method emc2 just throws an exception to cause a test error.

Write the test case

The test case is a standard JUnit TestCase. For the fixture, you can use the default JNDI InitialContext to get a reference to the EJB like this:


			protected void setUp() throws Exception {
  Context jndiContext = new InitialContext();

  Object einRef = jndiContext.lookup("java:comp/env/ejb/EinsteinEJB");
  EinsteinHome home = 
      (EinsteinHome)PortableRemoteObject.narrow(einRef, EinsteinHome.class);

  this.ein = home.create();
}

And the test methods themselves look like this:


			public void testSimpleAddition() throws RemoteException {
	String result = this.ein.addTwoNumbers("7", "10");
	assert(result.equals("17"));
}

The full source of the test case is included in the example - see package org.junitee.ejb.einstein.test.

Create the frontend web form

The JUnitEEServlet will execute test cases specified by the "suite" form parameter, which can appear multiple times. It's nice to have a simple form to start the tests:


			<html>
<body>
<p>
	You may type in the name of a test suite:
	<br/>
	<form action="TestServlet" method="get" name="youTypeItForm">
		<input type="text" name="suite" size=60 />
		<input type="submit" value="Run" />
	</form>
</p>
<hr/>
<p>
	You may pick one or more of the following test suites:
	<br/>
	<form action="TestServlet" method="get" name="youPickItForm">
		<select name="suite" size="2" multiple>
			<option value="org.infohazard.test.EinsteinTest">
				org.infohazard.test.EinsteinTest
			</option>
			<option value="some.other.Test">
				some.other.Test
			</option>
		</select>
		<input type="submit" value="Run" />
	</form>
</p>
</body>
</html>

Create the web.xml deployment descriptor

The web application must have a deployment descriptor which provides the ejb-ref mapping so that the "java:comp/env/ejb/EinsteinEJB" JNDI lookup will work. And the JUnitEEServlet and it's URL mapping is also required in the web.xml. Here is an example of how it should look like:


			<?xml version="1.0"?>
<!DOCTYPE web-app PUBLIC 
        "-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN" 
        "http://java.sun.com/j2ee/dtds/web-app_2_2.dtd">

<web-app>
  <display-name> Einstein Unit Tester Web Application </display-name>

  <servlet>
    <servlet-name>JUnitEETestServlet</servlet-name>
    <description>JUnitEE test framework</description>
    <servlet-class>org.junitee.servlet.JUnitEEServlet</servlet-class>
  </servlet>

  <servlet-mapping>
    <servlet-name>JUnitEETestServlet</servlet-name>
    <url-pattern>/TestServlet/*</url-pattern>
  </servlet-mapping>

  <ejb-ref>
    <ejb-ref-name>ejb/EinsteinEJB</ejb-ref-name>
    <ejb-ref-type>Session</ejb-ref-type>
    <home>org.infohazard.ejb.einstein.EinsteinHome</home>
    <remote>org.infohazard.ejb.einstein.Einstein</remote>
  </ejb-ref>
</web-app>

IMPORTANT NOTE: Orion Application Server has a bug in it's url pattern matching algorithm that causes some problems for JUnitEE. If you are using Orion please change the servlet mapping in the deployment descriptor to


			  <servlet-mapping>
    <servlet-name>JUnitEETestServlet</servlet-name>
    <url-pattern>/TestServlet*</url-pattern>
  </servlet-mapping>

Package the test WAR

Now you have everything ready to package the test web application. You have to put

junit.jar and junitee.jar to WEB-INF/lib
your test classes to WEB-INF/classes or a jar containing the test classes to WEB-INF/lib
the test frontend form to index.html
and the web.xml to WEB-INF

Finally, jar everything into the test.war and and create an EAR which contains test.war and the ejb-jar containing the Einstein bean.

Run the tests

After deploying the EAR point your browser to the index.html included in the test.war and select the EinsteinTest to be executed. After a few seconds your browser will display the test report showing successful and not so successful tests.

Make your life easier

Now you have seen how to create a .war file containing the JUnitEE servlet and your test classes. It requires some steps to create the war, but fortunately there is a way to automate these steps: use the JUnitEEWarTask created for use with Ant. Have a look at the Ant HowTo to learn more about this task.

Notes

Some things you might want to keep in mind when unit testing EJBs:

Unless you (and everyone else on the project) are extremely careful writing your unit tests, they are very likely going to seriously mess up your database. You should probably never run tests against a production system, and for this (and other security reasons) you should not enable the test web application on the production machine.
The testing of getters and setters is probably a waste of time.

References

Stuff you might find interesting and/or useful:

For information about JUnit, you naturally want to visit the JUnit home page.
For an introduction to extreme programming, you should read Extreme Programming: A Gentle Introduction and then go to XProgramming.com.
A fantastic resource for patterns, anecdotes, and other useful information is the Portland Pattern Repostory. You might want to start with the EjbUnitTest page or the JunitEe page.




This project is hosted by