Unit Testing WebLogic Workshop 8.1 Applications
Sample Extension for BEA WebLogic Workshop
By Joshua Eckels, Staff Software Engineer, BEA
Abstract
In this paper I describe how to do unit testing of applications developed with WebLogic Platform 8.1 using JUnit. I will show how you can write and run unit tests for all components of a generic WebLogic Platform application during application development. This paper is intended for lead developers and architects who are planning to integrate JUnit into the WebLogic Platform.
Introduction
Unit testing is a key practice during iterative development. Software engineers use unit tests to test code at the code level. Unit tests are typically run frequently and are therefore perfectly suitable for automation. In this paper, I will discuss how to write and run unit tests using WebLogic Platform 8.1. I will explain how to use JUnit to test all WebLogic Platform components, whether accessible inside or outside the server container.
I will assume that you already have a basic understanding of the principles of unit testing, and have some familiarity with the JUnit framework. More information on both topics can be found at the JUnit Web site, http://www.junit.org/.
In this paper I will first discuss some basics integration issues on how to integrate JUnit with WebLogic Workshop. Specifically, I will suggest locations for the JUnit test cases in a WebLogic Platform application and discuss various ways to launch these JUnit tests from WebLogic Workshop. Next I will discuss how to test specific types of components.
File LayoutSince JUnit test cases are just standard Java classes, you can put them in almost any type of project within your application. When testing components that are not directly exposed to the outside world from the server's virtual machine, your test classes will need to be accessible from within the server, which means they should either be part of a web project or a Java project that's built into your APP-INF/lib directory.
It's important to note that when deploying your application to production, you probably don't want to include your test classes. If you keep all your tests in separate test projects, you can exclude those projects from the build.
Launching JUnit from WebLogic WorkshopThere are a number of different ways that you can start a JUnit process from within Workshop. The actual method you use is not particularly relevant, although some may be more or less convenient depending on your application's setup and usage. Of course, you can also start JUnit separately from the command line if you prefer.
Regardless of the method used to start JUnit, it will create a .junitsession file in your home directory to remember which tests you've previously run. Because you won't have to retype the test class' name after you've run it for the first time, it's less important that JUnit be passed the test class' name on startup, although it's still more convenient to run a test directly instead of first starting JUnit and then selecting the test from the combo box.
Using a main() method and the Start button
If JUnit tests are saved in a Java project, you can configure WebLogic Workshop to use the start button to launch your tests. You must give the test class a main()method that starts up the JUnit runner of your choice. If you haven't already configured the debugger settings for the project, click the Start button and Workshop will ask you if you would like to set the current class as the main class. Alternatively, go to Tool-->Project Properties…-->[Test project], and select Debugger from the list. Be sure that the Create new process radio button is selected and fill in the name of your test class.
Assuming you want to turn off JUnit's reloading classloader, your main() method might look something like:
String[] jUnitArgs = new String[] { "-noloading", TestCase.class.getName() };
junit.swingui.TestRunner.main( jUnitArgs );
|
Assuming you have your classpath set up to include all runtime dependencies, you will be up and running. This will also let you debug code running in the JUnit process, which is often convenient for tracking down why a test is failing.
Using External Tools
Workshop provides a means for launching third-party programs through the IDE. Go to Tools-->IDE Preferences… and select the Tools node in the list. You can create a new tool configuration to launch JUnit. Just set the full command-line used to start JUnit, including a -classpath argument, and give it a sensible directory in which to start the process. For example, if your application is rooted in c:\wlw_app and you have installed WebLogic Workshop in the c:\bea directory, you might use c:\wlw_app as the directory. Assuming that you're testing code in a Java project named JavaProject and your test code is in a separate Java project named UnitTestProject and you've defined a TestSuite in a class named somePackage.MainTestSuite, your command would look like something of the form:
| c:\bea\jdk141_05\java.exe -classpath c:\wlw_app\APP-INF\lib\junit-3.8.1.jar; c:\wlw_app\APP-INF\lib\UnitTestProject.jar; c:\wlw_app\APP-INF\lib\UnitTestProject.jar; junit.swingui.TestRunner -noloading somePackage.MainTestSuite |
You can then easily launch JUnit by going to the Tools-->External Tools-->[JUnit Tool Name] menu in the IDE.
Using Ant
Ant provides an optional task for running JUnit tests, the task. A call to Ant might look as follows:
<target name="test">
<junit haltonerror="yes" fork="true">
<test name="JPFTest" />
<classpath>
<pathelement location="${app.local.directory}/APP-INF/lib/junit-3.8.1.jar"/>
<pathelement location="${app.local.directory}/APP-INF/lib/JPFTestProject.jar"/>
<pathelement location="${app.local.directory}/APP-INF/lib/htmlunit-1.2.3.jar"/>
<pathelement location="${app.local.directory}/APP-INF/lib/nekohtml-0.7.7.jar"/>
<pathelement location="${app.local.directory}/APP-INF/lib/commons-logging-1.0.3.jar"/>
<pathelement location="${app.local.directory}/APP-INF/lib/commons-httpclient-2.0.jar"/>
</classpath>
</junit>
</target>
|
If you launch JUnit through either the External Tools or Ant methods, you can still debug it by attaching to the JUnit process from the IDE. First, create or choose a Java project inside your Workshop application. It does not necessarily need to contain the code for your tests. Go to its Project Properties and configure the debugger settings to attach to a port of your choosing on the machine that will be running the JUnit tests. Then, start the JUnit process, passing its Java Virtual Machine the correct arguments to start listening for a debugger to attach, typically something of the form, where SELECTED_PORT is replaced with the port on which it should listen for the debugger:
-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=SELECTED_PORT,suspend=y,server=y
Although the virtual machine will start, it will not begin running the tests until a debugger attaches. In the IDE, open a document in the Java project for which you configured the debugger settings and hit the Start button. The debugger should quickly attach to the process and JUnit should start executing the tests.
You can also use Ant to generate reports based on your test results. For more information on how to integrate Ant and JUnit, go to the Optional Tasks sections of the Ant Tasks topic in the Ant manual (http://ant.apache.org/manual/index.html).
Disabling JUnit Reloading
By default, JUnit's Swing interface uses a classloader that automatically reloads classes before running tests. This is convenient because you don't need to restart JUnit after recompiling your classes. However, in the past I've had problems with the way the classloader works in some cases, causing spurious ClassCastExceptions and other unwanted problems. When launching JUnit from a script, through Ant, or from the External Tools, you can disable the special classloader by passing in the -noloading argument. If you are using a main() method inside your test class, you can accomplish the same thing with the following code, where YourTestClass has been replaced with the name of the test class:
public static void main( String[] args ) {
String[] jUnitArgs = new String[] {
"-noloading",
YourTestClass.class.getName() };
junit.swingui.TestRunner.main( jUnitArgs );
}
|
Unit Testing Externally Testable ComponentsLet's now turn to the discussion on how to unit test WebLogic Platform components. In this discussion I will draw the distinction between internally testable components and externally testable components, which I will discuss first. For the purposes of this discussion, externally testable components are those components that can be invoked from outside the J2EE container, typically through HTTP. When writing tests, your test case can initiate a network connection to the server, send it the appropriate request, and verify that the server's response is correct.
Java Page Flows (JPF), Java Server Pages (JSP), and Servlets
When testing Web sites, your test is essentially simulating a browser requesting a page or a series of pages from the server. Depending on what the site involves, you'll need to create the correct HTTP request, including the relevant URL, headers, parameters, cookies, and so forth. Once the server responds, you'll need to verify the contents including the headers, the HTML itself, client-side JavaScript, and cookies. There are two general ways to do this.
Proxy Use
First, you could use a proxy to record the interaction between a normal web browser and the server. After you've gone through the correct sequence of pages and manually verified that the results are correct, you can use the recording to automatically play back the same series of requests and verify that the results are the same. There are a number of packages that use this approach, including MaxQ (http://maxq.tigris.org/) and QuickTest (http://www.mercury.com/us/products/quality-center/functional-testing/quicktest-professional/).
This approach is very quick to generate a set of tests, but is unfortunately very fragile. As soon as you make changes to the way the page layouts, you run a high risk of breaking your tests. For sites that are under constant layout changes, this means that you'll likely have to re-record your tests on a regular basis.
Object Model
A second approach is to use a more programmatic technique by writing a test that builds up an object requesting the HTTP request, hits the server, and gets an object back representing the HTTP response. Although this is more work than using a proxy to record the session, it is less likely to be broken by tweaks to the HTML layout. Several libraries, including HTTPUnit (http://httpunit.sourceforge.net/), HTMLUnit (http://htmlunit.sourceforge.net/), and jWebUnit (http://jwebunit.sourceforge.net/) all provide APIs to simulate the browser interaction.
Sample Page Flow
For an example of the object model approach, let's take a look at HTMLUnit. Its API provides an object model for the HTML page that the server returns. Each request returns an HtmlPage, which you can then query about its contents. After finding a link in the page, you can simulate a user clicking on it in a browser, which will then return another HtmlPage. Similarly, you can locate forms within the page, find specific fields, set values, and submit to the server.
HTMLUnit uses the Rhino JavaScript engine to let you test script within your pages. However, it's important to note that it only supports a subset of the JavaScript that most browsers support, and that JavaScript behavior is always at least somewhat browser dependent.
To demonstrate testing a web site, I've taken the multipleForms page flow from the WebLogic Workshop 8.1 SP2 SamplesApp. In the code download, you can find it in the JPFWebProject project. The portion of the flow the test covers has two text fields. After entering values into them and hitting the submit button, the values are displayed on the subsequent page.
The JUnit test case for this example is {JPFTestProject}/JPFTest.java. It has a main() method as described above so that you can run it by clicking the Start button inside the IDE. The relevant code from the test method is as follows:
public void testPageFlow() throws Exception {
WebClient webClient = new WebClient();
HtmlPage page = (HtmlPage)webClient.getPage(
new URL( "http://localhost:7001/JPFWebProject/multipleForms/multipleFormsController.jpf" ) );
HtmlAnchor anchor = page.getFirstAnchorByText( "Show the JSP with blank form fields." );
HtmlPage page2 = (HtmlPage)anchor.click();
HtmlForm form = (HtmlForm)page2.getFormByName( "form1" );
Iterator elements = form.getAllSubmittableElements().iterator();
int count = 1;
while( elements.hasNext() ) {
HtmlElement element = (HtmlElement)elements.next();
assertTrue( element instanceof HtmlTextInput );
HtmlTextInput textInput = (HtmlTextInput)element;
textInput.setValueAttribute( "Value" + count++ );
}
HtmlPage page3 = (HtmlPage)form.submit();
String pageText = page3.asText();
assertTrue( pageText.indexOf( "Field A = \"Value1\"" ) != -1 );
assertTrue( pageText.indexOf( "Field B = \"Value2\"" ) != -1 );
}
|
The test itself is fairly straightforward. It first creates a WebClient object, which corresponds to a Web browser. It then issues a request to the server at the page flow's URL. The test looks for a link with the text "Show the JSP with blank form fields." It clicks on the link, and in the resulting page locates the form. After iterating through the form elements and giving them values, the test submits the form and looks for those values in the result page.
If you are using NetUI on your site, be warned that the taglibs typically do not generate a very simple name for the form elements. Normally, this does not matter because neither you as a developer nor the end user need to be concerned with the names, but when writing tests you usually need to set specific elements to particular values. You can always find the name for an element by viewing the page's HTML source in a browser.
Java Web Services (JWS)
Like HTML-based components, Java Web Services are accessible from outside the server over HTTP. A JWS, though, provides a more stable API through its WSDL, which can make it easier to test because the shape of the input and output XML is less likely to change than the exact HTML that represents the output of a JSP. The XML returned from a web service does not contain the formatting information that makes HTML much more likely to change due to layout tweaks.
You might want to consider testing your web services from the same client platform from which they will be called in production. For example, if you use WebLogic Workshop to implement your web services on your server and always call them from clients written in Microsoft .NET, you may want to write at least some of your tests in .NET to also test the cross-platform interaction.
Assuming that you want to write and run your tests in Java, you'd like to be able to write the tests using strongly typed Java objects instead of crafting an HTTP request and parsing the resulting XML. In 8.1, there are two ways to create such an interface conforming to the JAX-RPC specification.
Using <clientgen>
WebLogic Server provides a <clientgen> Ant task. You point the task at a WSDL that describes the Web service and tell it where to put the resulting Java classes. For documentation on how to use the task, see http://e-docs.bea.com/wls/docs81/webserv/anttasks.html#1080160.
Using Test Client
You can also use the WebLogic Workshop Test Client to generate the proxy JAR. Just hit the Start button on your JWS file, go to the Overview tab in the Test Client, and click on the Java Proxy button. If you prefer, you can specify the package in which to put the proxy classes otherwise use the default weblogic.jws.proxies.
Sample Web Service
The JWS that is shown below as an example can be found in {UnitTestingWeb}/jws/JWSToTest.jws. It defines two very simple operations. While not very interesting, they'll be sufficient for our purposes. You'll also see that we've generated a WSDL from the JWS, which Workshop will automatically keep in sync with the JWS if its interface changes.
public class JWSToTest implements com.bea.jws.WebService {
static final long serialVersionUID = 1L;
/** @common:operation */
public int square( int i ) {
return i * i;
}
/** @common:operation */
public String hello() {
return "Hello";
}
}
|
The test for our JWS is {JWSTestProject}/JWSTest.java, which is partially shown here:
private JWSToTest _proxy;
public void setUp() throws IOException {
_proxy = new JWSToTest_Impl();
}
public void testJWS() throws Exception {
assertEquals( 25, _proxy.getJWSToTestSoap().square( 5 ) );
}
|
Like the page flow test, it has a main() method so you can run it just by clicking on the Start button. In the setUp() method, which is called before each individual test is run, we create an instance of the JAX-RPC proxy. Then, inside our tests, we can simply pass the relevant arguments to the method and verify that the result is correct.
Since the proxy is generated from the WSDL, it already knows the URL at which to access the web service. You can test a different server running the same web service, like a staging server, by passing a different URL to the proxy. For more information on the JAX-RPC proxies, see http://java.sun.com/xml/jaxrpc/index.jsp.
Enterprise Java Beans (EJB)
Testing an EJB as an external component is very similar to calling it from any other client. (You can also test an EJB as an internal component. For more information, see below.) You'll need to do the basic set of steps that you are used to with EJBs: (1) look up the home interface in JNDI, (2) create an instance of the bean, and (3) call methods on it.
Sample EJB
We'll be testing the stateless session bean found at {EJBProject}/ejbpackage/SampleSessionBean.ejb. It defines a single bean method, doSomethingBoring(), which certainly lives up to its name by simply returning 5:
public class SampleSessionBean extends GenericSessionBean
implements SessionBean {
public void ejbCreate() {}
/** @ejbgen:remote-method */
public int doSomethingBoring() {
return 5;
}
}
|
For this sample, the test case is {UnitTestProject}/EJBTest.java, of which a snippet is shown below:
private SampleSessionHome lookupHome() throws NamingException {
Context ctx = getInitialContext();
// Lookup the bean's home using JNDI
Object home = ctx.lookup("ejb.SampleSessionRemoteHome");
return (SampleSessionHome) narrow(home, SampleSessionHome.class);
}
private Object narrow(Object ref, Class c) {
return PortableRemoteObject.narrow(ref, c);
}
private Context getInitialContext() throws NamingException {
// Set up the environment properties
Hashtable h = new Hashtable();
h.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
h.put(Context.PROVIDER_URL, "t3://localhost:7001");
return new InitialContext(h);
}
public void testEJB() throws Exception {
assertEquals( 5, lookupHome().create().doSomethingBoring() );
}
|
Within our test method, we get the initial context for the server, lookup the home interface in JNDI, narrow it, call the create method, and invoke the bean method. This test, too, can be run using the Start button.
Unit Testing Internally Testable ComponentsSome WebLogic Workshop components can only be accessed from inside the server container. The most notable example is controls, which can only be instantiated by the framework and given to other components including other controls, JWS, JPF, and JPD classes. Therefore, to effectively unit test these kinds of components, your tests need to be running inside the server process.
Cactus
When running against externally testable components, you run a JUnit test as a client process which issues HTTP requests to the components. To run a JUnit test inside the server container, you use the Cactus framework, a free, open-source code base that is part of the Apache Jakarta project. The Cactus Web site, http://jakarta.apache.org/cactus/index.html, contains detailed information about how the JUnit client connects to the server and causes tests to be run. Here I will summarize the mechanics.
When writing a JUnit test that you want to run inside the server using Cactus, instead of extending TestCase, you will usually want to extend ServletTestCase. Alternatively, you can have your suite() method return an instance of ServletTestSuite. When you run the client-side JUnit process on your test, it will detect that it's a server-side test, and issue HTTP requests to a URL you specify. On the server, Cactus receives the requests, creates an instance of your test class, and runs the tests. It then returns the results to the JUnit client process, which displays them as if they were run like a standard JUnit test.
In order to use Cactus, you'll need to configure your webapp to route incoming requests to Cactus appropriately, which is done by editing the web.xml deployment descriptor as is shown in the following snippet:
<servlet>
<servlet-name>ServletRedirector</servlet-name>
<servlet-class>
org.apache.cactus.server.ServletTestRedirector
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>ServletRedirector</servlet-name>
<url-pattern>/ServletRedirector</url-pattern>
</servlet-mapping>
|
Furthermore, both the server and client will need to have the JUnit, Cactus, and test classes on their runtime classpaths. Generally speaking, you'll want to add the Cactus and JUnit JARs to your application's APP-INF/lib directory. You can also use Ant tasks to package up an EAR that contains all of the classes you need to run your tests. When starting the JUnit client process, you need to specify what URL Cactus should use when connecting to the server with -Dcactus.contextURL=SomeURL. For more information, look at http://jakarta.apache.org/cactus/integration/ant/task_cactus.html.
Enterprise Java Beans (EJB)
If your production code that calls EJBs runs inside the same virtual machine as the EJB instances, you can make your test environment more closely match your production environment by using Cactus. This is shown in the following example.
Sample EJB
In this example the above EJB test for the external component test has been converted to run inside the server. You can find the EJB test demonstrating Cactus at {UnitTestingWeb}/ejb/CactusEJBTest.java. It's placed inside a web project so that it's deployed to the server, although a Java project that builds a JAR file into the APP-INF/lib directory would also be deployed to the server. A code snippet for this test is shown below:
public class CactusEJBTest extends ServletTestCase
{
private SampleSessionHome lookupHome() throws NamingException {
Context ctx = getInitialContext();
// Lookup the bean's home using JNDI
Object home = ctx.lookup("ejb.SampleSessionRemoteHome");
return (SampleSessionHome) narrow(home, SampleSessionHome.class);
}
private Object narrow(Object ref, Class c) {
return PortableRemoteObject.narrow(ref, c);
}
private Context getInitialContext() throws NamingException {
System.out.println( "getInitialContext()" );
// Set up the environment properties
Hashtable h = new Hashtable();
h.put(Context.INITIAL_CONTEXT_FACTORY,
"weblogic.jndi.WLInitialContextFactory");
h.put(Context.PROVIDER_URL, "t3://localhost:7001");
return new InitialContext(h);
}
public void testEJB() throws Exception {
assertEquals( 5, lookupHome().create().doSomethingBoring() );
}
...
|
If you look at the source code for the test, you'll notice that it's virtually identical to the non-Cactus version. It extends ServletTestCase instead of TestCase and has a different class and package name. It also prints out some debugging output inside its getInitialContext()method so that you can see that it is indeed running inside the server VM but is otherwise unchanged. Make sure that you build and deploy the application before trying to run the test to ensure that the test class is indeed deployed to the server.
Java Controls (JCS, JCX)
Controls are perhaps the most difficult components to test in WebLogic Workshop 8.1 because the user code does not directly instantiate them. Instead, you must allow the framework to give an instance of the control to one of the types of components that support controls, like a JPF. The following example shows how to make this happen.
Sample Java Control
In this sample, I have included an abstract base class, AbstractUnitTestController, for a Java Page Flow that can receive Cactus requests. To test a control, you create a subclass with JUnit test methods. Since your test case extends AbstractUnitTestController, it is actually a page flow controller, so the server framework will give your class an instance of controls to use. Also, you can use the design tools you're already familiar with inside the IDE to write your tests, which simplifies test creation. Note that you can easily adapt this page flow to test any Java control that you develop for your WebLogic Platform application.
The control that we're testing is a service control automatically generated from the web service in the earlier example. The example also demonstrates a different way to test web services that doesn't require building the Java client proxy. Workshop will automatically keep the service control synchronized with the web service. A snippet code of this control, UnitTestingWeb}/jws/JWSToTestControl.jcx, is shown below:
public interface JWSToTestControl extends
com.bea.control.ControlExtension,
com.bea.control.ServiceControl {
public int square (int i);
public java.lang.String hello ();
static final long serialVersionUID = 1L;
}
...
|
The code of the test {UnitTestingWeb}/jws/newpageflow1/ ServiceControlTest.jpf, is shown here:
public class ServiceControlTest extends
AbstractUnitTestController {
/** @common:control */
private jws.JWSToTestControl jwsToTestControl;
/** @jpf:action */
protected Forward begin() throws ServletException {
return super.begin();
}
public static Test suite() {
return new ServletTestSuite( ServiceControlTest.class );
}
public void testMethod() {
Assert.assertEquals( jwsToTestControl.square( 2 ), 4 );
}
}
|
There are two elements in the code that are required that make the test work correctly with Cactus (the rest is standard JUnit test code). First, the test needs to have a protected begin() method that just delegates to the superclass. Because in WebLogic Workshop 8.1 subclasses cannot inherit annotations, each test class needs to define a jpf:action so that it can receive HTTP requests. The superclass, found at {UnitTestingWeb}/jwsTestPageFlow/ AbstractUnitTestController.jpf, will take care of processing the request itself and calling the relevant test methods.
Second, the test needs a suite() method that adds the class to a ServletTestSuite. Since the class needs to be a Controller subclass to get control instances from the framework, this tagging tells Cactus to run the tests on the server instead of inside the client JUnit VM.
To run the test, be sure that you've built and deployed the application to your WebLogic Server. Then, use the controlCactus.bat file to start the client process and cause Cactus to run the tests in the server. As with the EJB Cactus example, you may need to edit the paths in the file to point to the correct directories on your machine.
To write tests for your own controls, you'll just need to add the AbstractUnitTestController.jpf class to your project and create your own subclass. The normal design tools that help you edit page flow documents will also assist in creating tests that use controls.
ConclusionAlthough WebLogic Workshop 8.1 does not automate the writing and maintenance of tests, it does not prevent you from writing your own. In some cases you can easily run your tests directly from the IDE. Using the information from this article, you should be able to test your own WebLogic Workshop components quickly and easily.
Additional Reading
|
J2EE Weblog 
