Ralph’s Blog

Hamcrest liefert zwar schon eine Menge an Matchern mit, aber nicht immer findet man das Gewünschte und man benötigt einen eigenen Matcher.

In diesem Beispiel schreiben wir einen Matcher der überprüft ob eine Zeichenkette mit A, B oder C beginnt und darauf drei Zahlen folgen. Da wir diese Prüfung in vielen verschiedenen Unit Tests durchführen müssen, schreiben wir einen eigenen Matcher.

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

public class IsAbcNumber extends TypeSafeMatcher {

  @Override
  public boolean matchesSafely(String aString) {
    return aString != null && aString.matches("[A,B,C]\\d{3}");
  }

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

  @Factory
  public static  Matcher abcNumber() {
    return new IsAbcNumber();
  }

}

Unser Matcher ist eine Subklasse von TypeSafeMatcher und implementiert die beiden Methoden matchesSafely und describeTo. In machesSafely wird die eigentliche Prüfung durchgeführt und true oder false zurückgegeben. describeTo ist zuständig für den Text der ausgegeben wird wenn die Behauptung nicht zutrifft.

Die statische Methode abcNumber können wir nun in unsere Testklasse importieren und den Matcher benutzen.

import static IsAbcNumber.abcNumber;
import org.junit.Test;

public class MyUnitTest {
  @Test
  public void testSomething() {
    String aNumber = "notvalid";
    assertThat(aNumber, is(abcNumber()));
  }
}

Die Fehlermeldung zeigt nun genau an wieso die Behauptung nicht zutrifft.

java.lang.AssertionError:
Expected: is not a valid ABC number
     got: "notvalid"

Folgender Test dagegen würde anstandslos durchlaufen.

  @Test
  public void testSomething() {
    assertThat("A120", is(abcNumber()));
    assertThat("B130", is(abcNumber()));
    assertThat("C140", is(abcNumber()));
  }	 

Weitere Links:
Hamcrest Tutorial
Meine vorherigen Blogposts über: Teil 1 und Teil 2

Hier einige weitere Beispiele von Hamcrest Matchern.

import static org.hamcrest.Matchers.*;
import static org.junit.Assert.*;
import java.util.Arrays;
import java.util.List;
import org.junit.Test;

public class MyUnitTest {

  @Test
  public void testSomething() {
    List list = Arrays.asList("one", "two");

    assertThat(list, hasItems(equalTo("one"), equalTo("two")));

    assertThat(list, hasItems(equalToIgnoringCase("ONE"), equalToIgnoringWhiteSpace("  two  ")));

    assertThat(list, hasItems(anyOf(equalTo("one"), equalTo("three")), not(equalTo("four")), equalTo("two")));
  }

}

Mit der hasItems lässt sich sehr einfach überprüfen ob Elemente in einer Collection vorhanden sind. In Kombination mit anyOf und not lassen sich komplizierte Behauptungen schreiben. Das letzte Beispiel prüft ob in der Liste die Elemente “one” oder “three” UND nicht “four” UND “two” enthalten sind.

Um Behauptungen für Strings zu schreiben bietet Hamcrest auch einige Matchers

  @Test
  public void testSomething() {
    String string = "a string";

    assertThat(string, equalToIgnoringCase("A STRING"));
    assertThat(string, containsString("str"));
    assertThat(string, startsWith("a "));
    assertThat(string, endsWith("inga"));
  }

Und wie immer erhält man kostenlos eine ansprechende Fehlermeldung. Hier die Fehlermeldung für das letzte assertThat

java.lang.AssertionError:
Expected: a string ending with "inga"
     got: "a string"

Beispiele mit Zahlen haben wir bereits im ersten Teil besprochen. Methoden für Numbers sind greaterThan, greaterThanOrEqualTo, lessThan, lessThanOrEqualTo und closeTo für Fliesskommazahlen.

Um Objekte zu vergleichen wird die equalTo Methode verwendet, die intern die Object.equals Methode benutzt.

Hamcrest bietet viele weitere nützliche Matchers an. Ein Blick in die Klasse org.hamcrest.Matchers zeigt alle an.

Für den Start mit Hamcrest sollte man sich auch mal das Tutorial auf der Projektseite durchlesen.

Siehe auch das erste Post über JUnit und Hamcrest

JUnit liefert zwar viele assertXY Methoden mit, wie z.B. assertEquals, assertTrue, assertNotNull, assertArrayEquals. Sobald aber die Behauptungen komplizierter werden muss man sich oft mit assertTrue oder assertFalse behelfen. Zum Beispiel wird hier in einem Test geprüft ob eine Liste ein bestimmtes Element enthält.

  @Test
  public void testList() {
    List<String> aList = Arrays.asList("one", "two");
    assertTrue(aList.contains("three"));
  }

Das Problem mit diesen Tests ist das folgende Fehlermeldung ausgegeben wird.

java.lang.AssertionError:

Aufgrund der Fehlermeldung wird nicht klar wieso der Test nicht lief. Man kann die Situation verbessern indem man die assertTrue Methode mit dem zusätzlichen message Parameter verwendet.

  @Test
  public void testList() {
    List<String> aList = Arrays.asList("one", "two");
    assertTrue("aList should contain three, but contains: " + aList, aList.contains("three"));
  }

java.lang.AssertionError: aList should contain three, but contains: [one, two]

Die Fehlermeldung zeigt nun an was nicht funktionierte. Diese Methode wird natürlich sehr aufwändig wen man hunderte solcher Testfälle programmieren muss.

Aus diesem Grund haben die Programmierer der JUnit Library in Version 4.4 die assertThat Methode eingebaut die zusammen mit den Hamcrest Matchern einen einfachen Aufbau von Behauptungen erlaubt.

Unser Beispiel würde mit einem Hamcrest Matcher so aussehen.

import static org.hamcrest.CoreMatchers.*;
import static org.junit.Assert.*;
import static org.junit.matchers.JUnitMatchers.*;

public class MyUnitTest {

  @Test
  public void testList() {
    List<String> aList = Arrays.asList("one", "two");

    assertThat(aList, hasItem(equalTo("three")));
  }
}

Als ersten Parameter wird das Objekt übergeben das geprüft werden soll. Der zweite Parameter ist ein Matcher.

java.lang.AssertionError:
Expected: a collection containing "three"
     got: <[one, two]>

Die Fehlermeldung zeigt nun genau an was nicht funktioniert hat ohne das wir selber eine Message erfassen mussten.

JUnit liefert bereits einige Matchers in den Klassen CoreMatchers und JUnitMatchers mit. Für das Beispiel genügt es also nur die JUnit Library als Dependency hinzuzufügen.

Um Zugriff auf alle verfügbaren Hamcrest Matchers zu haben muss zusätzlich folgende Library mit als Dependency angegeben werden.

    <dependency>
      <groupId>org.hamcrest</groupId>
      <artifactId>hamcrest-library</artifactId>
      <version>1.1</version>
      <scope>test</scope>
    </dependency>

In diesem zweiten Beispiel wird geprüft ob eine Zahl grösser als 5 und kleiner als 10 ist. Ohne Hamcrest und Matcher könnte dies so aussehen.

  @Test
  public void testSomething() {
    int aValue = 10;
    assertTrue(aValue > 5 && aValue < 10);
  }

Mit der nichtsagenden Fehlermeldung.

java.lang.AssertionError:

Der gleiche Test mit Hamcrest

import static org.hamcrest.Matchers.*;
import static org.junit.Assert.*;
import org.junit.Test;

public class MyUnitTest {

  @Test
  public void testSomething() {
    int aValue = 10;
    assertThat(aValue, allOf(greaterThan(5), lessThan(10)));
  }
}

java.lang.AssertionError:
Expected: (a value greater than <5> and a value less than <10>)
     got: <10>

Und wiederum zeigt die Fehlermeldung genau an was erwartet wurde und was der aktuelle Wert ist. allOf() prüft ob alle übergebenen Matcher passen. Die Methode fungiert also als Und Verknüpfung. Eine Oder Verknüpfung erstellt man mit anyOf().

Man kann den Ausdruck auch noch mit is() “verschönern”. Die is() Method existiert um die Lesbarkeit zu erhöhen hat aber sonst keine Wirkung. Die Behauptung und die Fehlermeldung lesen sich nun aber fast wie ein Satz.

  @Test
  public void testSomething() {
    int aValue = 10;
    assertThat(aValue, is(allOf(greaterThan(5), lessThan(10))));
  }

  java.lang.AssertionError:
Expected: is (a value greater than <5> and a value less than <10>)
     got: <10>