Unit Testing with HttpClient’s LocalTestServer

When unit testing code that uses HttpClient, it can get a bit tricky to not test against a active web server.  There are a couple of approaches to this to keep your tests at the unit level.

  1. Mock and inject HttpClient — While this is certainly possible and gives you complete control, it can take a lot of mocking and get tedious quite quickly.
  2. Use LocalTestServer from HttpClient — This is the point of this post and I will now explain.

Let’s take a look at the basic setup for getting this test server up.

Basic Setup

First, if you’re using Maven, you’ll need to bring in a new depedency.


Next, you’ll need to setup your unit test with the test server.

public void setUp() {
    LocalTestServer server = new LocalTestServer(null, null);

That’s all it takes to get the server in place and started but it’s not very useful without some handlers.

Adding Handlers

To really get something worthwhile out of the server, you’ll want to register at least one handler.  Your handler must implement


which has one really obvious method,

void handle(HttpRequest request, HttpResponse response, HttpContext context) throws HttpException, IOException;

Since we should be in a unit test, you can decide to either Mock this interface or create concrete classes that implement it.

Now that we have this spiffy way of controlling the response of the server, let’s see what it takes to register this handler with the server.

// do something to mock this or instantiate your own concrete class
HttpRequestHandler handler;

server.register("/someUrl/*", handler);

That’s all it takes to setup a local test server with at least 1 registered handler listening on /someUrl. For clarity, let’s take a look at the code all together.

public class MyUnitTest {
  private LocalTestServer server = null;

  HttpRequestHandler handler;

  public void setUp() {
    server = new LocalTestServer(null, null);
    server.register("/someUrl/*", handler);

    // report how to access the server
    String serverUrl = "http://" + server.getServiceHostName() + ":"
        + server.getServicePort();
    System.out.println("LocalTestServer available at " + serverUrl);

  // do lots of testing!

  public void tearDown() {

9 thoughts on “Unit Testing with HttpClient’s LocalTestServer

  1. Carl,

    Thanks for this example – very helpful! I’m having a problem that maybe you can help me solve:

    I’ve set up a LocalTestServer in my Junit test, with a custom implementation of HttpRequestHandler;

    I’m posting to my LocalTestServer using a PostMethod with HttpClient;

    I’m setting a post parameter on that method before posting;

    When my HttpRequestHandler fields the request, my post parameter is not there.

    Any ideas as to what I’m doing wrong?


    • The issue seems to be that HttpRequest in httpcore is for protocol-level requests; I was expecting to be able to use it like an HttpServletRequest.

      I used the following workaround:

      – create a test mode for the service I’m unit testing;

      – in test mode, append my post parameter to the request URI like this: “http://localhost:4565/my-path/myResource?myParam=”

      – then in my implementation of RequestHandler, I parse out the value and do what I need to with it.

      Not an ideal solution, but works for now.

      Has anyone else dealt with this issue?

      Brian Y

      • HttpClient does deal with protocol level commands and access. You might find a servlet test bit that could coupled with this to yield HttpServletRequest and HttpServletResponse.

  2. My project has a functioning dependency on HttpClient, but I can’t seem to reference the LocalTestServer… and some api’s (http://hc.apache.org/httpcomponents-client-ga/httpclient/apidocs/index.html?org/apache/http/client/package-summary.html) don’t include the localserver package, while some (http://hc.apache.org/httpcomponents-client-ga/httpclient/xref-test/index.html) do. What is the difference? How can I reference this class?

    • The difference there is that LocalTestServer is in src/test and not part of the main code. The apidocs show the code from src/main and the xref-test docs show you the tests. To reference this in your maven dependencies, be sure to include classifier=tests.

  3. Hi just a very basic question the some url part in your code can be any url right not necesarily the url of main web app or server

    My requirements are I need to test wether the httpclient is being able to establish the connection or not

    • You will need to configure the client in your code to connect to localhost or wherever your local test server can be found. For the bit in the example code that has someUrl, that is just the path part of the overall URL. This should reflect the context that your application expects to connect to. This is independent of the server’s url.

      If your the URL you connect to in production is http://greatserver.yes/aservice/anId, you will need to make sure “http://greatserver.yes” is configurable in the application and have your handler look for “server.register(“/aservice/*”, handler)”.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s