Modern Mocking Tools and Black Magic

Challenges to Testing

Before delving into the method itself, first observe that this is a static method. In Java, C#, C++ (and many other languages), static methods are always bound at compile (or by link) time. What this means is that code calling static methods is directly coupled to those methods. The selection of the method and the calling mechanism are selected too early to easily allow tests to setup an environment in which they can divert to something the test controls. It is possible to call a different static method at runtime using what Michael Feathers calls a “link seam.” In the case of Java, you could make sure a different version of the class with the static method is available in the classpath earlier. There is more on this below.

Map<String, String> symbolToName = currencySymbols();
if (!symbolToName.containsKey(fromCurrency))
    throw new IllegalArgumentException(String.format(
            "Invalid from currency: %s", fromCurrency));
if (!symbolToName.containsKey(toCurrency))
    throw new IllegalArgumentException(String.format(
            "Invalid to currency: %s", toCurrency));

HttpClient httpclient = new DefaultHttpClient();
HttpGet httpget = new HttpGet(url);
HttpResponse response = httpclient.execute(httpget);
HttpEntity entity = response.getEntity();

StringBuffer result = new StringBuffer();
if (entity != null) {
    InputStream instream = entity.getContent();
    InputStreamReader irs = new InputStreamReader(instream);
    BufferedReader br = new BufferedReader(irs);
    String l;
    while ((l = br.readLine()) != null) {
        result.append(l);
    }
}
String theWholeThing = result.toString();

int start = theWholeThing.lastIndexOf("<div id=\"converter_results\"><ul><li>");
String substring = result.substring(start);
int startOfInterestingStuff = substring.indexOf("<b>") + 3;
int endOfIntererestingStuff = substring.indexOf("</b>",
        startOfInterestingStuff);
String interestingStuff = substring.substring(
        startOfInterestingStuff, endOfIntererestingStuff);
String[] parts = interestingStuff.split("=");
String value = parts[1].trim().split(" ")[0];

Getting setup - exercise the code

One place to start is to simply try to execute the code in question with either null arguments or “reasonable” values. Since the domain is currency conversion, and the method takes in two currencies, that seems like a reasonable starting place.

Here is the beginning of an automated unit test to simply exercise the code. My goal is to get through the method. One note, while this code will run with a live internet connection, I've turned off my connection while writing this test to make sure I do not require a live internet connection for my test to work:

@Test
public void returnExpectedConversion_v1() {
    CurrencyConversion.convertFromTo("USD", "EUR");
}

This works if the network is enabled, but if not, the code generates a java.net.UnknownHostException . However, the actual place where it happens is in the method CurrencyConversion.currencySymbols , and not in the method we care about. Using older tools, this is a bit of work, not so with our tool of choice for this article: JMockIt

Getting past validation

Here is a second version of the test that gets past the first exception:

@Test
public void returnExpectedConversion_v2() {
    new NonStrictExpectations(CurrencyConversion.class) {
        {
            CurrencyConversion.currencySymbols();
            result = mapFrom("USD", "EUR");
        }
    };
    CurrencyConversion.convertFromTo("USD", "EUR");
}

private Map<String, String> mapFrom(String... keyValuePairs) {
    Map<String, String> result = new ConcurrentHashMap<String, String>();
    for (int i = 0; i < keyValuePairs.length; ++i)
        result.put(keyValuePairs[i], keyValuePairs[i]);
    return result;
}

Running this, the same exception is thrown, UnknownHostException , but the exception is now in the method under test rather than a called method. That's an improvement. This allows the code to get past validation, but how?

new NonStrictExpectations(CurrencyConversion.class) {
    {
        CurrencyConversion.currencySymbols();
        result = mapFrom("USD", "EUR");
    }
};

Notice the creation of an anonymous inner class using NonStrictExpectations? This form tells JMockIt to do something with the CurrencyConversion class (replace a static method in this case). The code in the inner set of {} is a standard Java instance initializer. Code executed in that instance initializer tells JMockIt to replace the method executed, currencySymbols. This is an example of a partial mocking of the class; we replace one of the methods in the class such that any time it is called, it returns whatever is assigned to the inherited field “result”.

This involve some black magic. JMockIt is doing some Java bytecode magic and this code uses the JMockIt DSL to make this happen. Making this work involves adding the JMockIt jar file into the classpath. If you make sure it is listed before JUnit's jar file, that's enough to make this happen. JMockIt uses a JavaAgent registered in its MANIFEST.MF file to make this all automatic.

Dealing with the client

Now the code is failing on the part of the code that tries to read a webpage:

HttpClient httpclient = new DefaultHttpClient();
HttpGet httpget = new HttpGet(url);
HttpResponse response = httpclient.execute(httpget);
HttpEntity entity = response.getEntity();

This code is a bit more complex since it is embedded in the method, but we can get past this problem. However, to do so will be a bit more work:

• The first two lines call new . We need to make those uses of the new operator return a class under our control.
• The next line calls the execute method on an HttpClient , so we'll need to get that under control.
• The last line calls the getEntity method on an HttpResponse , which was the return value from the previous line, so this is much more involved overall.

Here is one way to take care of these three issues in one fell swoop:

new NonStrictExpectations() {
    DefaultHttpClient httpclient;
    HttpResponse response;
    HttpEntity entity;

    {
        httpclient.execute((HttpUriRequest) any);
        result = response;
        response.getEntity();
        result = entity;
        entity.getContent();
        result = bais;
    }
};

In this use of NonStrictExpectations, there is no parameter passed in on the first line, meaning we are working with instances in some way rather than static stuff. This anonymous inner class has three fields: DefaultHttpClient, HttpResponse, HttpEntity. Those classes are wholly replaced in the Java classloader for this test only. This means, for example, calling new DefaultHttpClient will return an instance of the JMockIt-created class rather than the version found in the HttpClient jar.

This is an example of what I call a dynamic link seam. It's a link seam like Michael Feathers discusses in his book, which is normally accomplished with build script/file magic. However, unlike using build scripts, this is using a library, which makes it available to Java code “within” the language, rather than outside of the language.

This code replaces those three classes but with what?

• The HttpClient.execute method will always return response, which is an instance of the JMockIt-created HttpResponse subclass.
• The HttpResponse.getEntity method will always return entity, which is an instance of the JMockIt-created HttpEntity subclass.
• The HttpEntity.getContent method will always return “bais”, which we will see in the next section.

Make no mistake, this is powerful stuff. In fact, I have a personal rule of thumb: If I think something is cool, then it may not be appropriate for real development. JMockIt makes my “cool spider senses” tingle on overdrive.

Handling File I/O

The underlying code needs the contents of a stream. To create this, the test uses some standard Java magic to make an in-memory stream:

final ByteArrayInputStream bais = new ByteArrayInputStream(
        "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>"
                .getBytes());

This creates an in-memory ByteArrayInputStream from a string. How did I know what to put in the string? I had to reverse-engineer the underlying code. Even so, this makes the code execute.

Putting it together

Here is the test as a single method rather than broken up as it has been so far:

@Test
public void returnExpectedConversion_v3() throws Exception {
    final ByteArrayInputStream bais = new ByteArrayInputStream(
            "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>"
                    .getBytes());

    new NonStrictExpectations() {
        DefaultHttpClient httpclient;
        HttpResponse response;
        HttpEntity entity;

        {
            httpclient.execute((HttpUriRequest) any);
            result = response;
            response.getEntity();
            result = entity;
            entity.getContent();
            result = bais;
        }
    };

    new NonStrictExpectations(CurrencyConversion.class) {
        {
            CurrencyConversion.currencySymbols();
            result = mapFrom("USD", "EUR");
        }
    };
    BigDecimal result = CurrencyConversion.convertFromTo("USD", "EUR");
    assertThat(result.subtract(new BigDecimal(2)), is(lessThanOrEqualTo(new BigDecimal(0.001))));
}

On the one hand, this is pretty impressive. We've managed to exercise the code end-to-end without touching it. If we want to write something that uses this class, we now have a way to do it. Often, before trying to touch some code, we need to get it under test so we know if we broke anything after making changes. This is calledCharacterization Testing. Poorly written code like this typically makes doing so very hard. While it is still hard, at least we are able to do so without touching the production code. Having characterization tests around code makes refactoring safer.

So we're done, right?

Wrong.

We've addressed the symptom, not the cause

Notice that JMockIt made it possible to accomplish near black magic, but can we do better? If we try, will the time invested be worth the effort? In this section we start with the same method and make a few so-called legacy refactorings to the code to make it testable using more traditional tools, hand-rolled test doubles in this case. Then we'll compare, make an observation and then look at what would become possible.

Introduce instance delegator

A typical problem with static methods is they cannot be overridden. To fix this, we might simply make the class use all instance methods instead. However, let's assume for this example that we need to maintain backwards compatibility so we need to keep the static methods in place (in my experience this is not contrived).

While I might try to do this test-first, in fact, I have an existing JMockIt test, so instead I'm going to simply make the necessary changes. I'll do this by copying CurrencyConversion into a new package with the name v2 added to it (the source for this blog is generated from source code, so I need to keep the original version around).

To introduce an instance delegator:

• Introduce a static instance of the class.
• Copy the static methods into instance methods (you'll need to create new method names as static methods and instance methods cannot have the same name and signature).
• Change the static methods to call the instance methods on the internal static instance.

Here's one way to do that (the lazy initialization of the internal instance is deliberate and if you're concerned about threading issues, we could use double-checked locking or just make the method synchronized):

private static CurrencyConversion instance;

private static CurrencyConversion getInstance() {
    if (instance == null) {
        instance = new CurrencyConversion();
    }

    return instance;
}

public static BigDecimal convertFromTo(String fromCurrency, String toCurrency) {
    return getInstance().convert(fromCurrency, toCurrency);
}

public static Map<String, String> currencySymbols() {
    return getInstance().getAllCurrencySymbols();
}

Extract a few methods

There are several opportunities to extract some methods, so here's a version of v2/CurrencyConversion after a few method extractions:

public BigDecimal convert(String fromCurrency, String toCurrency) {
    validateCurrencies(fromCurrency, toCurrency);

    try {
        String result = getPage(fromCurrency, toCurrency);
        String value = extractToValue(result);
        return new BigDecimal(value);
    } catch (Exception e) {
        throw new RuntimeException(e);
    }
}

protected void validateCurrencies(String fromCurrency, String toCurrency) {
    Map<String, String> symbolToName = currencySymbols();
    if (!symbolToName.containsKey(fromCurrency))
        throw new IllegalArgumentException(String.format(
                "Invalid from currency: %s", fromCurrency));
    if (!symbolToName.containsKey(toCurrency))
        throw new IllegalArgumentException(String.format(
                "Invalid to currency: %s", toCurrency));
}

protected String extractToValue(String result) {
    String theWholeThing = result;
    int start = theWholeThing.lastIndexOf("<div id=\"converter_results\"><ul><li>");
    String substring = result.substring(start);
    int startOfInterestingStuff = substring.indexOf("<b>") + 3;
    int endOfIntererestingStuff = substring.indexOf("</b>",
            startOfInterestingStuff);
    String interestingStuff = substring.substring(
            startOfInterestingStuff, endOfIntererestingStuff);
    String[] parts = interestingStuff.split("=");
    return parts[1].trim().split(" ")[0];
}

protected String getPage(String fromCurrency, String toCurrency) throws URISyntaxException, IOException, HttpException {
    String url = String.format("http://www.gocurrency.com/v2/dorate.php?inV=1&from=%s&to=%s&Calculate=Convert", toCurrency, fromCurrency);
    HttpClient httpclient = new DefaultHttpClient();
    HttpGet httpget = new HttpGet(url);
    HttpResponse response = httpclient.execute(httpget);
    HttpEntity entity = response.getEntity();
    StringBuffer result = new StringBuffer();
    if (entity != null) {
        InputStream instream = entity.getContent();
        InputStreamReader irs = new InputStreamReader(instream);
        BufferedReader br = new BufferedReader(irs);
        String l;
        while ((l = br.readLine()) != null) {
            result.append(l);
        }
    }
    return result.toString();
}

Here is a version of the last test targeting this class (the one in the v2 package). This test passes:

@Test
public void returnExpectedConversion_v4() throws Exception {
    final ByteArrayInputStream bais = new ByteArrayInputStream(
            "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>"
                    .getBytes());

    new NonStrictExpectations() {
        DefaultHttpClient httpclient;
        HttpResponse response;
        HttpEntity entity;

        {
            httpclient.execute((HttpUriRequest) any);
            result = response;
            response.getEntity();
            result = entity;
            entity.getContent();
            result = bais;
        }
    };

    new NonStrictExpectations(CurrencyConversion.class) {
        {
            CurrencyConversion.currencySymbols();
            result = mapFrom("USD", "EUR");
        }
    };
    BigDecimal result = CurrencyConversion.convertFromTo("USD", "EUR");
    assertThat(result.subtract(new BigDecimal(2)), is(lessThanOrEqualTo(new BigDecimal(0.001))));
}

Testing subclass

Now I'll rewrite this test using hand-written test doubles instead JMockIt. Rather than show all of the intermediate steps, I'll just show a final result:

class CurrencyConversion2_testingSubclass extends CurrencyConversion {
    @Override
    public void validateCurrencies(String fromCurrency, String toCurrency) {
    }

    @Override
    public Map<String, String> getAllCurrencySymbols() {
        return mapFrom("USD", "EUR");
    }

    @Override
    public String getPage(String fromCurrency, String toCurrency) {
        return "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>";
    }
}

@Test
public void returnExpectedConversion_v5() throws Exception {
    CurrencyConversion original = CurrencyConversion.reset(new CurrencyConversion2_testingSubclass());

    BigDecimal result = CurrencyConversion.convertFromTo("USD", "EUR");

    assertThat(result.subtract(new BigDecimal(2)), is(lessThanOrEqualTo(new BigDecimal(0.001))));

    CurrencyConversion.reset(original);
}

This test produces the same result as the JMockIt test doing much of the work by hand.

Note, to make this possible, we need to allow for the new-created Singleton class to be set and reset:

public static CurrencyConversion reset(CurrencyConversion other) {
    CurrencyConversion original = instance;
    instance = other;
    return original;
}

Actual amount of time to do this

This technique of introducing an instance delegator, with an override-able static singleton and several extracted methods might seem like quite a bit. In practice this kind of change is quick. How quick? For this example, it took me 3 minutes using IntelliJ. Eclipse would have taken the same amount of time. In vi, maybe 1 minute (ok, maybe not, but I do use a vi plugin in Eclipse, IntelliJ and even Visual Studio). In any case, once you've practiced this, it's quick. We could have avoided much of this if the class had not used all static methods to begin with, but that's a common problem so knowing how to handle it is a good general technique to know.

Yes, but...

A common concern raised is what about making all of those extracted methods protected? It does not bother me because I believe test-ability is more important than design. That's actually a false dichotomy but it sounds controversial so I like to say it anyway. In fact, many of these “protected methods” are complex enough to warrant individual classes. Next, introduce dependency inversion and suddenly I'm wiring in dependent objects that are under my control, with override-able methods and checking individual parts of this overall flow become a snap. Divide and conquer.

First test versus second test

Here are the two tests again, for comparison:

Using JMockIt

@Test
public void returnExpectedConversion_v4() throws Exception {
    final ByteArrayInputStream bais = new ByteArrayInputStream(
            "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>"
                    .getBytes());

    new NonStrictExpectations() {
        DefaultHttpClient httpclient;
        HttpResponse response;
        HttpEntity entity;

        {
            httpclient.execute((HttpUriRequest) any);
            result = response;
            response.getEntity();
            result = entity;
            entity.getContent();
            result = bais;
        }
    };

    new NonStrictExpectations(CurrencyConversion.class) {
        {
            CurrencyConversion.currencySymbols();
            result = mapFrom("USD", "EUR");
        }
    };
    BigDecimal result = CurrencyConversion.convertFromTo("USD", "EUR");
    assertThat(result.subtract(new BigDecimal(2)), is(lessThanOrEqualTo(new BigDecimal(0.001))));
}

Using Hand-rolled mocks and Refactoring

class CurrencyConversion2_testingSubclass extends CurrencyConversion {
    @Override
    public void validateCurrencies(String fromCurrency, String toCurrency) {
    }

    @Override
    public Map<String, String> getAllCurrencySymbols() {
        return mapFrom("USD", "EUR");
    }

    @Override
    public String getPage(String fromCurrency, String toCurrency) {
        return "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>";
    }
}

@Test
public void returnExpectedConversion_v5() throws Exception {
    CurrencyConversion original = CurrencyConversion.reset(new CurrencyConversion2_testingSubclass());

    BigDecimal result = CurrencyConversion.convertFromTo("USD", "EUR");

    assertThat(result.subtract(new BigDecimal(2)), is(lessThanOrEqualTo(new BigDecimal(0.001))));

    CurrencyConversion.reset(original);
}

If you have to support test code, which version do you prefer? Wait, don't answer yet.

First test still passes

I want to reiterate that even though I made several changes to the production code, the JMockIt test still passes. That's pretty interesting to me. In fact, if you think in terms of how JMockIt manipulates the classloader, it makes sense. Even so, it's still pretty cool.

What if we try with JMockIt again

Why stop here? What happens if we take the time to rewrite the JMockIt test taking into consideration the changes made to the production code?

@Test
public void returnExpectedConversion_final() throws Exception {
    new NonStrictExpectations(CurrencyConversion.class) {
        CurrencyConversion c;
        {
            c.validateCurrencies(anyString, anyString);
            c.getPage(anyString, anyString);
            result = "<div id=\"converter_results\"><ul><li><b>1 USD = 0.98 EUR</b>";
        }
    };
    BigDecimal result = CurrencyConversion.convertFromTo("USD", "EUR");
    assertThat(result.subtract(new BigDecimal(2)), is(lessThanOrEqualTo(new BigDecimal(0.001))));
}

Now which one do you want to maintain?

Notice, a little bit of refactoring makes the final JMockIt test much better. In fact, the amount of refactoring required to write this version of the test is smaller than the amount I did refactor. Simply extracting methods would have been enough to greatly improve the JMockIt test. Notice, however, that JMockIt did not force this. Not using a mocking tool or using a tool like Mockito would have forced me to do some amount of refactoring to get this class under test.