Hamcrest extension for Guava

Introducing the extension

This page describes the Hamcrest extension for Google Guava. The matchers are compatible with JDK7.

How to start

To start using the extension for Guava, simply import the following dependency in your pom.xml.

<dependency>
  <groupId>it.ozimov</groupId>
  <artifactId>guava-hamcrest-matchers</artifactId>
  <version>1.3.0</version>
  <scope>test</scope>
</dependency>

If you don't use Maven, go here to see how to import using another build automation tool (e.g. Gradle, Grape, etc.).

If you prefer, you can directly import the jar from here:

http://search.maven.org/remotecontent?filepath=it/ozimov/guava-hamcrest-matchers/1.2.0/guava-hamcrest-matchers-1.2.0.jar

Once that you have the jar available, in your unit test class you should import all the new matchers as follows:

import static it.ozimov.cirneco.assertions.hamcrest.guava.GuavaMatchers.*;

There may be a clash with the firm of such another statically imported method from another library, in this case proceed as by practice.

Matchers categories

The library provides matchers divided into the following categories

• Base - Basic matchers for Guava base classes.
• Collect - Matchers for some Guava's Iterable implementations, like Multiset and Multimap.

Base Matchers

Guava Optional matcher

The Guava users may take benefit of the emptyGuavaOptional() matcher. Every time that a method returns an com.google.common.base.Optional, it is convenient to check that the returned Optional is or is not empty as follows:

//Act
Optional optional = methodThatReturnsOptional();
//Assert
assertThat("Expected the returned optional not to be empty", 
  optional, not(is(emptyGuavaOptional()));

---

Guava Equivalence matcher

Another matchers based on an useful Guava feature is equivalentTo() matcher. Sometimes is convenient to compare objects based on a subset of the object properties.

E.g., suppose to have an entity from a DB and another that has the same fields except the id. Clearly, the equals() method from Object should return false comparing these two objects. However, you can use com.google.common.base.Equivalence to write down a custom equivalence checker that amends the id from the comparison. The following example shows this use case.

//Arrange
Equivalence<MyEntity> entityEquivalence; //Initialize an Equivalence
MyEntity persistedEntity = DAO.findById(1); //retrieve a MyEntity by id from the DB

//Act
MyEntity nonPersistedEntity = methodThatCreateAnEntityWithoutId();

//Assert
assertThat("Expected the two instances to be equivalent", 
  nonPersistedEntity, equivalentTo(pesistedEntity, entityEquivalence));

Collect Matchers

Multiset element with count matcher

In a Multiset each element has a count. To assert that an element has a given count, the elementWithCount() matcher is provided. A simple example is provided.

//Act
Multiset<String> multiset = methodThatReturnsAMultiset();

//Assert
assertThat("Expected that element \"A\" in the multiset has count 10", multiset, elementWithCount("A", 10));

---

Multimap element with collection size matcher

In a Multimap, each key maps a Collection of objects. To assert that the size of the collection of a map key is a given value, the matcher keyWithSize() is introduced. An examples follows

//Arrange
String key = "AKey";
Collection<Integer> valuesForKey = ImmutableList.of(1, 100, 100_000);
Multimap<String, Integer> multimap = ArrayListMultimap.create();

//Act
multimap.put("AKey", valuesForKey);

//Assert
assertThat(String.format("Expected a collection size for key \"%s\" equals to 3", key), 
  multimap, keyWithSize(key, 3));

---

Multimap with keyset matcher

To assert that a Multimap has a given keyset, the matcher hasSameKeySet() can be used. It works with both another Multimap or with a Set. E.g.

//Arrange
Set<String> expectedKeySet = ImmutableSet.of("A", "B", "C");

//Act
Multimap<String, Integer> multimap = methodReturningMultimap;

//Assert
assertThat("Expected a multimap with keyset [\"A\", \"B\", \"C"\]", 
  multimap, hasSameKeySet(expectedKeySet));

---

Multimap with keyset with size matcher

To deal with the size of the keyset of a Multimap, the matchers emptyKeySet() and keySetWithSize() are provided. An example follows.

//Act
Multimap<String, Integer> multimap = methodReturningMultimap;

//Assert
assertThat("Expected a multimap with non-empty keyset", 
  multimap, not(emptyKeySet()));
assertThat("Expected a multimap with keyset with size 1", 
  multimap, keySetWithSize(1));