Java Hamcrest Documentation

If the core Java Hamcrest library does not provide the specific matchers you need, several community projects offer specialized extensions for different data types and testing scenarios:

Specialized Matchers by Domain

• JSON & Data Formats:
  • hamcrest-json: For comparing entire JSON documents.
  • JsonUnit: For comparing JSON structures using jsonEquals and jsonPartEquals.
  • json-path-matchers: For evaluating JSON path expressions.
  • hamcrest-java-extras: Provides JSON matchers.
  • Hamcrest HAR: For HTTP archive files.
• Web & Networking:
  • http-matchers: To test web services via the JAX-RS API.
  • Hamcrest Mail: For comparing javax.mail package types.
• Database & Querying:
  • Hamcrest Querydsl: For checking query results (e.g., hasResultSize, hasColumnRange, hasColumnMax, hasColumnMin, hasColumnContainingAll, hasColumnContainingAny).
  • Hamcrest Result Set Matcher: For comparing JDBC result sets.
• Java Objects & POJOs:
  • Hamcrest 1.3 Utility Matchers: Includes CollectionMatchers, MapMatchers, FieldMatcher, and SerializableMatcher.
  • Hamcrest auto matcher: Uses reflection to automatically match model classes.
  • Hamcrest Composites: For comparing complex Java objects.
  • Shazamcrest: Matchers for beans with custom field matching and improved failure messages.
  • Spotify's hamcrest matchers: Matchers for POJOs, JSON, and Java 8 types.
  • hamcrest-pojo-matcher-generator: An annotation processor to generate feature-matchers from POJOs.
• Filesystem & Dates:
  • Hamcrest Path: For testing path existence and permissions.
  • Hamcrest Date: For comparing dates.

Asynchronous Testing & Polling

• Awaitility: A DSL for expressing expectations of asynchronous systems.
• Proboscis: A library for polling for results in asynchronous systems.

To create a custom matcher, the most convenient approach is to extend TypeSafeMatcher<T>. This handles type casting for you. You must implement two methods:

1. matchesSafely(T item): Contains the actual logic to determine if the item matches.
2. describeTo(Description description): Defines the failure message used when the matcher fails.

Best Practice: Always ensure your custom matcher is stateless so that a single instance can be safely reused across multiple tests. It is common to provide a static factory method for easy use in tests.

package org.hamcrest.examples;

import org.hamcrest.Description; 
import org.hamcrest.Matcher; 
import org.hamcrest.TypeSafeMatcher;

public class IsNotANumber extends TypeSafeMatcher {

  @Override 
  public boolean matchesSafely(Double number) { 
    return number.isNaN(); 
  } 

  public void describeTo(Description description) { 
    description.appendText("not a number"); 
  } 

  public static Matcher notANumber() { 
    return new IsNotANumber(); 
  } 

}