Mockito @Spy Annotation

In my previous post I went over some of the new annotations and annotation features available in Mockito with the 1.8.3 release and promised the following day I would post details on the @Spy annotation. Well, unfortunately practically a month has passed since then! But fear not, here is the overview of the @Spy annotation that I promised.

Using It

Using the @Spy annotation is quite easy… just use the MockitoJunit4Runner and annotate a real object instance as follows:

import java.util.ArrayList;
import java.util.List;

import org.junit.Test;
import org.junit.runner.RunWith;
import org.mockito.Spy;
import org.mockito.runners.MockitoJUnitRunner;
import static org.mockito.Mockito.*;
import static org.junit.Assert.assertThat;
import static org.hamcrest.CoreMatchers.*;

@RunWith(MockitoJUnitRunner.class)
public class SpyExample {
	@Spy
	private List>String< list = new ArrayList>String<();

}

This will essentially proxy the real ArrayList implementation with a CGLib proxy. No big deal there. Let’s try stubbing a call so that it returns “hey” if we request index 32:

        @Test
	public void spyExample(){
		when(list.get(32)).thenReturn("hey");

		assertThat(list.get(32), equalTo("hey"));
	}

This blows up in our face with a big hairy IndexOutOfBoundsException while trying to stub the method call out. Duh… it’s calling the real implementation! Therefore we opt to use doReturn(...) instead as it allows us to stub the method we want without calling the real thing.

@RunWith(MockitoJUnitRunner.class)
public class SpyExample {
	@Spy
	private List>String< list = new ArrayList>String<();
	@Test
	public void spyExample(){
		doReturn("hey").when(list).get(32);

		assertThat(list.get(32), equalTo("hey"));
	}
}

If we rerun the example we will now see green bar rather than IndexOutOfBoundsException. We can still call real methods like add, remove, size, etc and they’ll still behave as expected; only when get(32) is called will it stub the call and return the canned value.

For the most part, I’m not a fan of this technique. In the real world I’d either choose between using the real thing (which I would most certainly ALWAYS do if it were a collection or some other base type) or prefer a wholesome complete stub using @Mock (but adhering to the rule that you only mock/stub objects you actually own).

Sadly there are always weird cases where you need to do it to make something easier to test… a good example was some legacy code I was dealing with where the test interacted with a real object to manipulate graphics in the UI. Those interactions needed to remain intact in order for the existing tests to pass, however one method caused a web service call that made the tests brittle and unpredictable. Spying that object and stubbing out the method that made the web service call was the best way to exercise the different scenarios around what that method returned. “Fixing” the collaborator’s API itself or isolating it from the class under test is a whole separate issue.

Verifying Messages Between Collaborators

A really useful feature I find in using spies is the ability to verify messages passed to a real collaborator in a big ball of mud type of system. Imagine this scenario: you pick up a story that is to just modify some logic in how messages are passed from one object to another. Sounds simple, until you look at the existing unit test:

public class CustomerHandlerBOTest {
	private ComplexClassThatDoesAlot formulator = DumbStaticFactory.create();
	private CustomerHandlerBO bo = new CustomerHandlerBO(formulator);

	....
}

The class names and that static factory are bad enough, but let’s imagine the code has gotten itself to the situation where simply providing complete test double for ComplexClassThatDoesAlot will force you to introduce test doubles for 20 other objects. Or perhaps the method is large and the default behavior of the collaborator allows you to execute the code that needs to execute to get you to where you want. You can simply write a verification of the argument passed to it and then make the modification you need to.

@RunWith(MockitoJUnitRunner.class)
public class CustomerHandlerBOTest {
	@Spy
	private ComplexClassThatDoesAlot formulator = DumbStaticFactory.create();
	@Captor
	private ArgumentCaptor>Item< arg;
	private CustomerHandlerBO bo = new CustomerHandlerBO(formulator);

	@Test
	public void shouldPassItemRequestWithExpectedCalculation(){
		...
		bo.calculate(BULK_ORDER);
		verify(formulator).audit(arg.capture());

		Item actualItemAudited = arg.getValue();
		assertThat(actualItemAudited.getPrice(), equalTo(EXPECTED_CALCULATED_PRICE));
	}

Of course, once the tests pass I might start applying some obvious refactorings starting as renaming away from those hideous names and either eventually get to the point where a @Spy is no longer needed or at least have that piece under test. The good thing about this is you can verify the interaction between these two objects without having to crack open encapsulation through a backdoor default or protected method (something I’ve been guilty of).

You Can Stub Internal Calls

I’ve seen situations where someone was dealing with legacy code and wanted to do this:

doReturn(1).when(bookingSystem).getActiveReservations();

bookingSystem.processReservations();

Where processReservations() makes a call to getActiveReservations() internally. Although this clearly hints at a hidden collaborator that needs to exist or break free from bookingSystem, Mockito apparently will let you get away with this. I seriously wouldn’t suggest it when test driving fresh code, again but there’s always those situations where you have no options.

Hope that is useful for you… overall I find the @Spy annotation to simply be a useful tool for fighting legacy code but should be used with care when specifying fresh code, if at all.