Implementing Hamcrest custom matcher using java dynamic proxy

Motivation

I was reading the article New Tricks with Dynamic Proxies in Java 8 from Dominic Fox and I thought that could be interesting to implement the code as he suggests.

Source code

The source code used in this post can be found at my GitHub repository:

https://github.com/mroger/hamcrest-proxy-matcher

Model

The Person model class is a very simple POJO to demonstrate the use of the proxy matcher and can be seen below.

	package br.org.roger.model;
	import java.util.List;
	public class Person {
	private String name;
	private int age;
	private List<String> options;
	//Getters and setters ommited
	}

view raw Person.java hosted with ❤ by GitHub

The test

The test method we're interested in uses a custom matcher implemented using dynamic proxy.

	public class PersonTest {
	private Person person;
	@Before
	public void setUp() {
	person = new Person();
	}
	@Test
	public void shouldMatchCriteriaDynamicProxyWay() {
	person.setName("Bruce Wayne");
	person.setAge(15);
	List<String> options = Arrays.asList(new String[] {"1", "2", "3"});
	person.setOptions(options);
	assertThat(person, aPerson()
	.withName("Bruce Wayne")
	.withAge(lessThan(20))
	.withOptions(Arrays.asList(new String[] {"1", "2", "3"})));
	}
	}

view raw PersonTest.java hosted with ❤ by GitHub

The aPerson() method creates a proxy for PersonMatcher and returns its fluent interface as seen below. The interface declares the methods used to setup the matcher.

	public interface PersonMatcher extends Matcher<Person> {
	PersonMatcher withName(String expected);
	PersonMatcher withName(Matcher<? super String> matching);
	PersonMatcher withAge(int expected);
	PersonMatcher withAge(Matcher<Integer> matching);
	PersonMatcher withOptions(List<String> options);
	}

view raw PersonMatcher.java hosted with ❤ by GitHub

The custom matcher

The idea behind this custom matcher proxy is to intercept all the calls to the PersonMatcher interface and provide their implementation on the fly. The custom matcher's users will only have to comply to one little rule: PersonMatcher  interface methods have to start with "with".

The first methods called on PersonMatcher will be the ones defined by the interface. In  the invoke method, those method names and arguments are put in the map for later processing. You can see it below.

	public class MagicMatcher <T> implements InvocationHandler {
	//...
	public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
	if () {
	//...
	} else {
	if (args.length > 1) {
	throw new IllegalArgumentException("Cannot assert more than one argument at once.");
	}
	methodMap.put(method.getName(), args[0]);
	return proxy;
	}
	}
	//...
	}

view raw MagicMatcherElse.java hosted with ❤ by GitHub

Then, Hamcrest calls the custom matcher's matches() method and the proxy intercepts it, using the method names previously stored in the map to extract values from the actual object using reflection and comparing them with the also previously stored values. Note that the "with" prefix is removed from method names to obtain the fields names that, in conjunction with expected and actual values, are used to assemble expectedDescription and mismatchDescription, printed in the last two phases in Hamcrest´s life cycle.

	public class MagicMatcher <T> implements InvocationHandler {
	//...
	public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
	if ("matches".equals(method.getName())) {
	for (Entry<String, Object> entry : methodMap.entrySet()) {
	String field = entry.getKey().substring(entry.getKey().indexOf("with") + 4);
	Object objectValue = extractObjectValue((T) args[0], entry.getKey());
	if (!(entry.getValue() instanceof Matcher)) {
	resultDescription.addExpectedDescription(field, objectValue);
	if (!entry.getValue().equals(objectValue)) {
	resultDescription.addMismatchDescription(field, entry.getValue());
	return new Boolean(false);
	}
	} else {
	Matcher<?> matcher = (Matcher<?>) entry.getValue();
	resultDescription.addExpectedDescription(field, objectValue);
	if (!matcher.matches(objectValue)) {
	resultDescription.addMismatchDescription(field, objectValue);
	return new Boolean(false);
	}
	}
	}
	return new Boolean(true);
	} else if ("describeTo".equals(method.getName())) {
	Description description = (Description) args[0];
	description.appendText(resultDescription.getExpectedDescription());
	return null;
	} else if ("describeMismatch".equals(method.getName())) {
	Description description = (Description) args[1];
	description.appendText(resultDescription.getMismatchDescription());
	return null;
	} else {
	if (args.length > 1) {
	throw new IllegalArgumentException("Cannot assert more than one argument at once.");
	}
	methodMap.put(method.getName(), args[0]);
	return proxy;
	}
	}
	//...
	}

view raw MagicMatcher.java hosted with ❤ by GitHub

Lastly, if any of the values doesn't match, then Hamcrest also calls the Matcher's describeTo() and describeMismatch() method, to give the custom matcher a chance to explain, as a formatted description, what values diverge, using descriptions stored previously.

As we can see, using dynamic proxy is a great way to create semantics and DSLs for your tests. It also helps to avoid tedious implementations.

Wanna share your thoughts? I´d like very much to know your opinions about this and if it helped you in any way.