Naresh's Blog

   Does your application have RESTful Web Services? Do you want to ensure that these services are working properly on a wide range of containers - both light weight and heavy weight ones?

     Have you ever felt the need of an infrastructure setup, which you can use to test your services against all these containers without having to worry about things like deployment descriptors, etc? If so, you have a news. Jersey 1.0.3 got released day before yesterday, and it comes with a testing framework called the Jersey Test Framework. 

     The Jersey Test Framework currently allows you to run your tests on any of the following three light weight containers:

• Embedded GlassFish
• Grizzly Web Server
• Lightweight HTTP Server

The framework is built over JUnit 4.x using Maven.

How do I use the Jersey Test Framework?

          Using the framework is simple. All that you will need  is do this:

1. Add the following dependency to your pom.xml:
• <dependency>
              <groupId>com.sun.jersey.test.framework</groupId>
              <artifactId>jersey-test-framework</artifactId>
              <version>1.0.3</version>
              <scope>test</scope>
   </dependency>
2. Create a class which extends com.sun.jersey.test.framework.JerseyTest.
3. Some minimal number of parameters need to be passed by the test class to the JerseyTest class. This can be done in one of the following ways:
• super(String rootResourcePackage): Pass the root resource package name to the super constructor. This constructor will then take care of initialising, starting and/or stopping the test container.
• super(String contextPath, String servletPath, String resourcePackageName): Pass the application context path, servlet path and root resource package name to the super constructor if you are working on a web application. Again this constructor will take care of initializing, starting and/or stopping the test container.
• super(): When you call the default no parameter super constructor, you still can pass the information to the JerseyTest class by creating an instance of the com.sun.jersey.test.framework.util.ApplicationDescriptor class, setting the parameters using the setter methods defined in that class. This has to be done in your test class's constructor. Also, a call needs to be made to the JerseyTest class's setupTestEnvironment(ApplicationDescriptor applicationDescriptor) method. This call would take care of the init, start and/stop of the test container.
4. Annotate your test methods with the org.junit.Test annotation.
5. The handles to com.sun.jersey.api.client.Client and com.sun.jersey.api.client.WebResource instances - client and webResource get inherited from the JerseyTest class. You can use them in your test methods for building URIs and sending HTTP requests.
   
6. Run the tests using the maven command - mvn clean test. This will by default run the tests against the Grizzly Web Server. If you want to run the tests on the container of your choice, set the system property container.type with one of the following values:
• EmbeddedGF : Makes the tests run against Embedded GlassFish.
• GrizzlyWeb : Makes the tests run against the Grizzly Web container.
• HTTPServer : Makes the tests run against the Simple HTTP Server.
7. The framework also provides an option of seeing the HTTP requests and responses sent over the wire. It could be done by just setting the system property enableLogging, i.e., if you want to see the request and response sent over the wire, while running tests against Embedded GlassFish, execute the following command:
• mvn clean test -Dcontainer.type=EmbeddedGF -DenableLogging
8. And that's it. You have got the framework working.

Are there any samples which are using this framework?

                 Some of the samples that come with the Jersey distribution have been modified to use this framework. These are:

• helloworld
• helloworld-webapp
• extended-wadl-webapp
• entity-provider
• simple-console
• jsonp
• jaxb

You should try running tests of these samples and see how the test framework works. I'm sure you will like it :)

If you see some of these samples do not have a deployment descriptor, but still you are able to run the tests against Embedded GlassFish. This is because the framework generates a deployment descriptor on the fly in such cases.

Future Enhancements

It is being planned to support the following features in the coming versions:

1. Support for external containers - GlassFish v2 and GlassFish v3
2. Giving the user an option to specify the containers which his test doesn't support.
   

If you have any queries or see any issues with the current implementation or feel there should be something more, please send an email to the Jersey user mailing list - users@jersey.dev.java.net