AssertJ Core overview

AssertJ core is a Java library that provides a fluent interface for writing assertions. Its main goal is to improve test code readability and make maintenance of tests easier.

AssertJ core provides assertions for JDK standard types and can be used with JUnit or TestNG.

Different AssertJ major versions depend on different Java versions :

  • AssertJ 3.x requires Java 8 or higher (use the org.assertj.core.api.Java6Assertions entry point on Android)
  • AssertJ 2.x requires Java 7 or higher (use the org.assertj.core.api.Java6Assertions entry point on Android)
  • AssertJ 1.x requires Java 6 or higher

Note that AssertJ 3.x includes all AssertJ 2.x features and adds Java 8 specific ones (like exception assertions with lambdas).

AssertJ core code and issue tracker are hosted on github.

For a quick start, have a look at our one minute getting started guide.

Convert existing JUnit assertions to AssertJ ones : we have a guide to easily convert JUnit assertions to AssertJ.

If you have any questions, please use stack overflow or the AssertJ google group (with a preference for stack overflow).

You are more than welcome to raise an issue if you need new assertions or see potential improvements.

Working with AssertJ on a daily basis
Extending AssertJ

You can see assertions in action with the assertj examples tests of the assertj-examples project.

Although AssertJ Core can be used with Android, I suggest using AssertJ-Android, a useful extension specifically for Android.

AssertJ is a fork of FEST Assert, a great project I have contributed to for 3 years. So why did I fork it ?

There are two main reasons :

  • FEST 2.0 will only provide a limited set of assertions, far less than Fest 2.0M10 and even less than FEST 1.x.
  • FEST is not open enough to users demands and contributions.

On the contrary AssertJs goal is to provide a rich set of assertions and any reasonable request to enrich AssertJ assertions is welcome. AssertJ is community driven, we listen to our users since AssertJ is built for them.

If you feel that some assertion is missing, please fill a ticket or even better make a contribution !

Joel Costigliola (AssertJ creator) You can ask questions and make suggestions on the AssertJ google group.

Android does not support the java.nio.file.Path class, so the 'regular' AssertJ 3.x/2.x entry point classes can not be used. Instead you can use the Java6XAssertions classes. For example use org.assertj.core.api.Java6Assertions instead of org.assertj.core.api.Assertions.

The following listing contains 'regular' import statements and their android alternative:

// 'regular' assertj
import static org.assertj.core.api.Assertions.*
// assertj on android
import static org.assertj.core.api.Java6Assertions.*

// 'regular' assertj
import static org.assertj.core.api.SoftAssertions.*
// assertj on android
import static org.assertj.core.api.Java6SoftAssertions.*

// 'regular' assertj
import static org.assertj.core.api.JUnitSoftAssertions.*
// assertj on android
import static org.assertj.core.api.Java6JUnitSoftAssertions.*

// 'regular' assertj
import static org.assertj.core.api.BDDAssertions.*
// assertj on android
import static org.assertj.core.api.Java6BDDAssertions.*

// 'regular' assertj
import static org.assertj.core.api.BDDSoftAssertions.*
// assertj on android
import static org.assertj.core.api.Java6BDDSoftAssertions.*

// 'regular' assertj
import static org.assertj.core.api.JUnitBDDSoftAssertions.*
// assertj on android
import static org.assertj.core.api.Java6JUnitBDDSoftAssertions.*

The following examples show incorrect AssertJ API usages:

// BAD USAGE : DON'T DO THIS ! It does not assert anything
assertThat(actual.equals(expected));

// DO THIS :
assertThat(actual).isEqualTo(expected);

// OR THIS (less classy but ok):
assertThat(actual.equals(expected)).isTrue();

// BAD USAGE : DON'T DO THIS ! describedAs has no effect
assertThat(actual).isEqualTo(expected).describedAs("description");

// DO THIS :
assertThat(actual).describedAs("description").isEqualTo(expected);

// BAD USAGE : DON'T DO THIS ! Comparator is not used
assertThat(actual).isEqualTo(expected).usingComparator(new CustomComparator());

// DO THIS :
assertThat(actual).usingComparator(new CustomComparator()).isEqualTo("a");

Static code analysis tools like FindBugs can now detect such problems thanks to the CheckReturnValue annotation introduced in 2.5+ / 3.5+ and improved in 2.7+ / 3.7+.

AssertJ Core is hosted on github : https://github.com/joel-costigliola/assertj-core.

Please report bugs or missing features in the AssertJ Core issue tracker.

AssertJ's Vetinari (ok, maybe not as Machiavellian), enjoy playing basket ball, love Terry Pratchett's disc world (surprised ?), work with linux.

AssertJ collaborator, who loves books, history and books about history.

You are very welcome to contribute, we want to offer the richest and easiest to use assertion API, so ideas from our users are very appreciated.

Contributing is easy and we try to help people contributing. Have a look at the contributor guidelines (these are the same guidelines shown when you create a new issue).

Special thanks assertj-core contributors :

  • Adam Dąbrowski
  • Adam Ruka
  • Alban Dericbourg
  • Alexander Bischof
  • Alexandre Balhier
  • Andrew Gaul
  • Ben Blank
  • Brian Laframboise
  • Brice Dutheil
  • Chris Arnott
  • Clément Cunin
  • Clément Mathieu
  • Cristiano Gavião
  • Dan Corder
  • Daniel Zlotin
  • Dima Gerasimov
  • dmwvr
  • Fabien Duminy
  • Fabien Meurisse
  • Francis Galiegue
  • Filip Hrisafov
  • Gregor Zeitlinger
  • hgcummings
  • James Strachan
  • Jean Christophe Gay
  • Jeremy Landis
  • Johannes Schneider
  • Johannes Brodwall
  • Guillaume Husta
  • Grzegorz Piwowarek
  • Kamil Szymanski
  • Kseniya Panasyuk
  • Kevin Fang
  • Lovro Pandzic
  • Lukasz Kryger
  • Libor Ondrušek
  • Marcin Mikosik
  • Marcus Klimstra
  • Mariusz Smykula
  • Mateusz Haligowski
  • Michael W. Fender
  • Michal Bareja
  • Michal Kordas
  • Michal Lipski
  • Michał Ostruszka
  • Michał Piotrkowski
  • Michaël Bitard
  • Mike Kobit
  • Mike Wilkes
  • Mikhail Mazursky
  • Misha Brukman
  • Nicolai Parlog
  • Nick Stolwijk
  • Paul Doran
  • Pascal Schumacher
  • Paweł Barszcz
  • Peter Phillips
  • Pierre Templier
  • Piotr Betkier
  • Richard Lucas
  • Ted Young
  • Tim Perry
  • timmikk
  • Tobias Bieniek
  • Tobias Liefke
  • Tomasz Bartczak
  • Trond Marius Øvstetun
  • Valeriy Vyrva
  • William Delanoue

AssertJ has its roots in FEST Assert, a project I have contributed to for 3 years, so thanks to Alex Ruiz FEST's creator !

Thanks to SonarQube for providing AssertJ Core quality reports.