Assertion Libraries für Java: AssertJ versus Google Truth

Unit Tests sind ein fundamentales Element im Software Engineering. Sie garantieren die funktionale Korrektheit der Software und helfen dabei, potenzielle Fehler frühzeitig zu identifizieren. Assertions (Behauptungen) spielen dabei eine zentrale Rolle, indem sie sicherstellen, dass die erwarteten Bedingungen während der Testausführung erfüllt sind.

Unit Tests enthalten Assertions, die das verwendete Testframework zum Testzeitpunkt auf Einhaltung prüft. Ein einfaches Beispiel ist die Prüfung, ob der Rückgabewert einer bestimmten Methode true lautet. Falls eine Assertion nicht zutrifft, bricht der Test die Ausführung ab und gilt als fehlgeschlagen. Wenn alle Assertions eingehalten werden, führt das Testframework den Test bis zum Ende aus und dieser gilt als erfolgreich.

Ein Unit Test kann mehrere Assertions enthalten, wobei sie sich typischerweise am Ende der Testmethode befinden. In seltenen Fällen ist es möglich, dass Assertions in der Mitte des Testfalls geprüft werden, um die Einhaltung von Zwischenbedingungen für den Test sicherzustellen.

Assertion-APIs der Testframeworks haben Lücken

Für die Formulierung von Assertions in der jeweiligen Programmiersprache kommt in der Regel die API des Testframeworks zum Einsatz. So bietet etwa JUnit für Java einfache APIs an, um Assertions auszudrücken.

Sie reichen in der Regel für einfache Tests mit wenigen Assertions aus und haben den Vorteil, dass sie direkt im Testframework verfügbar sind. Daher muss man keine zusätzlichen Dependencies in das Softwareprojekt einbinden.

Ist das Projekt jedoch umfangreicher und sind die Tests aufwendiger, stoßen diese APIs an ihre Grenzen. Zunächst sind sie nicht auf Lesbarkeit und Verständlichkeit optimiert. Für kompliziertere Assertions müssen Entwicklerinnen und Entwickler viel Boilerplate-Code schreiben. Darüber hinaus sind die Fehlermeldungen bei nicht eingehaltenen Assertions eher kurz und abstrakt und lassen relevante Details zur Fehlersuche vermissen, beispielsweise über fehlende Elemente in einer Collection. Weiterhin ist die Assertion API von JUnit nicht erweiterbar, lässt sich also nicht um Assertions für die eigene Domänenlogik ergänzen.

Das folgende Listing zeigt ein Beispiel, das die Einschränkungen der JUnit Assertion API demonstriert.

  @Test
  public void testListComparison() {
    List expectedList = Arrays.asList("Apple", "Banana", "Cherry");
    List actualList = Arrays.asList("Apple", "Grape", "Cherry");

    assertEquals(expectedList, actualList, "Die Listen sollten gleich sein");
  }

Zunächst werden zwei Listen, die Strings enthalten, erzeugt. Der Aufruf der Methode assertEquals verlangt, dass die beiden Listen gleich sein sollen. Da die Listen unterschiedliche Elemente enthalten, schlägt der Test mit folgender Meldung fehl:

Die Listen sollten gleich sein ==> expected: <[Apple, Banana, Cherry]> but was: <[Apple, Grape, Cherry]>

Die Meldung verdeutlicht nicht, welche Elemente in den Listen unterschiedlich sind. In diesem stark vereinfachten Beispiel mag das für Developer leicht erkennbar sein, in der Praxis ergeben sich hingegen oft komplexere Fälle. Es wäre hilfreich, wenn die Meldung die konkrete Information enthält, welche Elemente unterschiedlich sind. In diesem Fall: die Strings Banana und Grape.

Eine weitere Assertion könnte darin bestehen, dass ein konkretes Element exakt einmal in einer Liste vorkommt. Mit der API von JUnit lässt sich diese Anforderung nicht unmittelbar umsetzen. Entwickler müssen den dafür notwendigen Code selbst schreiben. Assertion Libraries wie AssertJ oder Google Truth besitzen solche Einschränkungen nicht. Die APIs der beiden Libraries sind auf Lesbarkeit und Verständlichkeit optimiert. Ihre Assertions lesen sich in der Regel wie natürliche Sprache. Insbesondere lassen sich mehrere Assertions in einem Ausdruck verketten, was Boilerplate-Code verringert.

Fehlermeldungen bei verletzten Assertions sind bedeutend detaillierter, und erleichtern die Fehlersuche. Daneben gibt es umfangreiche spezialisierte APIs für die Standardtypen in Java, etwa Strings, Listen oder Exceptions.

AssertJ bietet umfangreiche Assertion APIs

AssertJ ist eine quelloffene Java-Bibliothek mit einer umfangreichen Menge an Assertions und hilfreichen Fehlermeldungen. Sie hat vor allem das Ziel, die Lesbarkeit von Testcode zu verbessern. AssertJ Core ist der Kern von AssertJ, daneben gibt es weitere AssertJ-Module für Bibliotheken wie Guava.

Die Library lässt sich als org.assertj:assertj-core über Maven und Gradle in ein Java-Projekt einbinden. Ein Projekt mit Spring Boot verwaltet die AssertJ-Version automatisch. Falls es notwendig ist, lässt sich die AssertJ-Version mit der Property assertj.version überschreiben.

AssertJ bietet eine große Auswahl an verschiedenen Assertion APIs für eine Vielzahl an Java-Standardtypen, darunter gängige Typen wie String, List oder Predicate und primitive Typen wie int oder char. Diese APIs sind auf den jeweiligen Typen spezialisiert und bieten Methoden an, die dabei helfen, das Schreiben von Boilerplate-Code zu vermeiden. Es folgt eine Übersicht:

String-APIs:

• isNotBlank: String ist kein Leerstring
• contains: String enthält einen Substring
• hasSize: String hat eine bestimmte Länge
• isUpperCase: String umfasst nur Großbuchstaben

Listen-/Iterable-APIs:

• contains: Liste enthält Elemente in beliebiger Reihenfolge
• containsOnly: Liste enthält nur bestimmte Elemente in beliebiger Reihenfolge
• containsExactly: Liste enthält nur bestimmte Elemente in gegebener Reihenfolge

Die Vielfalt an Assertions deckt somit viele Anwendungsfälle ab.

Entwicklerinnen und Entwickler können Assertions mit zusätzlicher Semantik versehen, indem sie eine textuelle Beschreibung beim Aufruf mitgeben. Diese ist wiederum Teil der Fehlermeldung, sofern die Assertions nicht eingehalten werden. Über eine Konfiguration lässt sich steuern, ob diese Beschreibungen direkt auf der Standardkonsole ausgegeben oder durch eine eigene Logik in einem sogenannten Description Consumer konsumiert werden sollen, um sie beispielsweise in einer Datei zu speichern.

Der Einstiegspunkt für Developer sind die Assertions-Klasse und die darin enthaltenen Methoden assertThat(…). Die Namensgebung assertThat(…) zeigt, dass Wert auf die Intuitivität und Lesbarkeit der Assertions gelegt wird. Die Assertions lesen sich dadurch wie natürliche Sprache. Zunächst wird assertThat als statischer Import deklariert:

import static org.assertj.core.api.Assertions.assertThat;

Als Nächstes kann man in einer Testmethode assertThat(foo). schreiben, wobei foo sich auf den Wert oder das Objekt bezieht, auf dem die Assertion beruht. Je nachdem, was foo für einen Typ hat, bieten IDEs bei richtig konfigurierter Codevervollständigung die passenden Assertion-APIs an. Übergibt man beispielsweise ein Objekt vom Typ LocalDate als Argument, erhält man Empfehlungen wie hasMonth oder isAfter. Daraus ergibt sich etwa folgende Zusammenstellung der Assertion:

assertThat(date).isNotNull().hasMonth(Month.of(1)).isAfter(beginDate);

Die Assertion lässt sich nun in natürlicher Sprache so lesen: „Stelle sicher, dass date nicht null ist, den Monat 1 (Januar) hat und nach einem anderen Datum beginDate fällt“. Die Verkettung der Methodenaufrufe vermeidet Boilerplate-Code und erhöht die Lesbarkeit. Sobald eine der Assertions fehlschlägt, werden die nachfolgenden nicht mehr überprüft.

Wenn Entwickler alle Assertions prüfen lassen möchten, bevor ein Test abbricht, verwenden sie SoftAssertions. Dafür erzeugen sie ein Objekt vom Typ SoftAssertions, rufen darauf die gewünschten Assertion-Methoden auf und lösen am Ende mit assertAll die finale Überprüfung aus. AssertJ stellt anschließend eine Übersicht aller fehlgeschlagenen Assertions zusammen. Dieser Ansatz eignet sich besonders für komplexe Testfälle, da er einen direkten Überblick über alle Fehler liefert und verhindert, dass der Test nach jeder Fehlerbehebung erneut gestartet werden muss.

Darüber hinaus lässt sich AssertJ um Assertions für die eigene Anwendungsdomäne erweitern. Das Schreiben von Custom Assertions erlaubt das Entwickeln von Assertion-Methoden, die auf das eigene Datenmodell zugeschnitten sind. Im Falle einer Terminverwaltungssoftware könnte man sich etwa folgende Assertions überlegen:

• assertThat(appointment).isDue()
• assertThat(appointment).isCancelled()

Appointment wäre eine Klasse aus dem eigenen Domänenmodell und isDue sowie isCancelled wären selbst entwickelte Assertion-Methoden. Dieses Vorgehen erhöht die Lesbarkeit sowie die Verständlichkeit von Unit Tests, indem sich die eigene Anwendungsdomäne aus dem Produktivcode auch in den Tests widerspiegelt. Um eine Custom Assertion umzusetzen, müssen Entwicklerinnen und Entwickler eine neue Klasse von der abstrakten Klasse AbstractAssert ableiten, einen Konstruktor und eine statische assertThat-Methode und weiterhin alle erforderlichen Assertion-Methoden (wie isDue, isCancelled usw.) implementieren.

Google Truth setzt auf nachvollziehbare und übersichtliche APIs

Eine weitere Assertion Library für Java ist Google Truth, entwickelt und gewartet von Googles Guava-Team. Sie kommt in der Mehrheit aller Tests in der Google-Codebasis zum Einsatz. Der inhaltliche Fokus liegt auf lesbaren Assertions und Fehlermeldungen. Truth unterstützt viele Java-Standardtypen und Typen aus der Guava-Library. Die Einbindung von Truth in Maven- oder Gradle-Projekte erfolgt über das Artefakt com.google.truth:truth.

Um Truth in einem Test einzusetzen, braucht es zunächst die Methode assertThat, bereitgestellt über einen statischen Import:

import static com.google.common.truth.Truth.assertThat;

Ähnlich wie bei AssertJ lässt sich ein Objekt als Argument an assertThat übergeben, woraufhin sich des Typen des Arguments entsprechende Assertion-APIs ergeben. Ein einfaches Beispiel aus der Truth-Dokumentation ist der Check, ob ein String mit einem bestimmten Teilstring beginnt:

String string = "awesome";
assertThat(string).startsWith("awe");

Um den Fehlermeldungen bei verletzten Assertions mehr Semantik zu verleihen, können Entwicklerinnen und Entwickler eine passende Beschreibung mitgeben. Dazu importieren sie die Methode assertWithMessage und rufen sie auf:

import static com.google.common.truth.Truth.assertWithMessage;

assertWithMessage("Without me, it's just aweso")
    .that(string)
    .contains("me");

Auch Truth erlaubt das Erweitern um eigene Custom Assertions. Im Truth-Datenmodell schreibt man dafür ein eigenes Custom Subject. Die eigene Subject-Klasse muss von der Klasse Subject abgeleitet sein. Zusätzlich braucht es eine statische Hilfsmethode und einen Konstruktor. Außerdem mussen spezifische Assertion-Methoden ergänzt werden. Die Truth-Dokumentation verweist auf das Referenzbeispiel des EmployeeSubject.

Bei umfangreichen Tests mit vielen Assertions, bei denen eine vollständige Überprüfung aller Assertions hilfreich ist, kommt in Truth die Klasse Expect zum Einsatz, initialisiert über eine JUnit-Rule-Annotation:

@Rule public final Expect expect = Expect.create();

Auf dem Objekt Expect kann man dann ähnlich wie bei assertThat ein Argument übergeben und passende Assertions formulieren. Leider zeigt sich, dass dieser Ansatz nur bis JUnit 4 unterstützt wird. Ab JUnit 5 ist die Rule-Annotation nicht mehr möglich und Truth bietet bisher (Stand April 2026) keine alternative Implementierung dafür an. Da im September 2025 JUnit 6 erschienen ist, ist die Verwendung von JUnit 4 nicht zu empfehlen. Folglich lässt sich Expect nicht mehr sinnvoll einsetzen.