Testing Servlets with JUnit

In my day-to-day job I write a lot of unit tests, and I try to test everything I can. Recently though I had written a service that I was unable to test completely. One of the methods in the service had the job of sending an HTTP request to a remote server and responding with the results. For my project I used commons-httpclient to send the request.

@SuppressWarnings("unchecked")
public String sendHttpPost (String url, String queryString)
   throws Exception
{
    String result = null;
    
    try {
        HttpClient client = new HttpClient();
        PostMethod post = new PostMethod(url);
        post.setQueryString(queryString);
        client.executeMethod(post);
        
        result = post.getResponseBodyAsString();
        post.releaseConnection();
    }
    catch (Exception e) {
        throw new Exception("post failed", e);
    }
    
    return result;
}

If you have used commons-httpclient, this is about as simple as it gets, but I still wanted to have a unit test for it. So the problem became, "how can I test this method when it requires that I hit a web site". After some searching I found that the Jetty servlet-container has a ServletTester class just for this purpose.

In my Maven 2 I included the ServletTester using the following repository and dependency information. I always use Maven 2 as allows other developers to quickly set up their IDE and download all required JARs. If you don't use Maven, you will need to manually download all of the dependencies.

<repositories>
  <repository>
    <id>codehaus-release-repo</id>
    <name>Codehaus Release Repo</name>
    <url>http://repository.codehaus.org</url>
  </repository>
</repositories>

...

<dependency>
  <groupId>org.mortbay.jetty</groupId>
  <artifactId>jetty-servlet-tester</artifactId>
  <version>6.1.6</version>
  <scope>test</scope>
</dependency>

With this in place the next step was writing the JUnit test cases. For me I wanted to initialize the servlet-container once, then run a set of tests against it. In JUnit 4 you can use the @BeforeClass and @AfterClass annotations to mark methods that should be executed before and after all of the tests.

public class HttpPostServiceTest
{
    private static ServletTester tester;
    private static String baseUrl;
    

    /**
     * This kicks off an instance of the Jetty
     * servlet container so that we can hit it.
     * We register an echo service that simply
     * returns the parameters passed to it.
     */
    @BeforeClass
    public static void initServletContainer () throws Exception
    {
        tester = new ServletTester();
        tester.setContextPath("/");
        tester.addServlet(EchoServlet.class, "/echo");
        baseUrl = tester.createSocketConnector(true);
        tester.start();
    }

    /**
     * Stops the Jetty container.
     */
    @AfterClass
    public static void cleanupServletContainer () throws Exception
    {
        tester.stop();
    }
}

The code highlighted in blue is where we start an instance of the server. I created a new instance of the ServletTester, setting the context path and adding a servlet mapping. This alone does not bind the server to a port, for that you need to call createSocketConnector(true), which binds the server to a local port and returns the URL. The port used will be a high unused port. I save an instance of the ServletTester so that I can stop the service in the @AfterClass block, and I save the baseUrl so that I can target it in my tests.

The servlet I added to the container I called EchoServlet. This servlet simply echos the parameters passed to it.

public class EchoServlet extends GenericServlet
{
    
    @SuppressWarnings("unchecked")
    @Override
    public void service (ServletRequest request, ServletResponse response)
        throws ServletException, IOException
    {
        PrintWriter out = response.getWriter();
        Map<String, String[]> params = 
            new TreeMap<String, String[]>(request.getParameterMap());

        out.println("SIZE=" + params.size());
        for (Entry<String, String[]> entry : params.entrySet()) {
            out.println(entry.getKey() + ":::"
                + StringUtils.join(entry.getValue(), ","));
        }
    }
}

The servlet takes the parameter map and creates a TreeMap out of it. The TreeMap is needed so that the parameter names are returned in sorted order. Being able to predict the order of the returned keys is required in order to test against the output of the servlet.

To finish things up, I just needed to write a unit test.

@Test
public void testPost () throws Exception
{
    PostService svc = new PostService();
    
    String res = svc.sendHttpPost(baseUrl + "/echo",
        "foo=bar&baz=%25%26%3D%2F");
    String[] resList = StringUtils.split(res, "\n");
    
    assertEquals(3, resList.length);
    assertEquals("SIZE=2", resList[0].trim());
    assertEquals("foo:::bar", resList[1].trim());
    assertEquals("baz:::%&=/", resList[2].trim());
}

After that, run the test and watch it work.