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, TestNG or any other test framework.
Different AssertJ major versions depend on different Java versions :
Note that AssertJ 3.x includes all AssertJ 2.x features and adds Java 8 specific ones (like exception assertions with lambdas).
Soft assertions are not supported in Android, this is due the internal use of Byte Buddy that does not support Android.
AssertJ core code and issue tracker are hosted on github.
AssertJ is a fork of FEST Assert, a great project I have contributed to for 3 years. Many thanks to Alex Ruiz Fest Assert creator!
We are trying hard to make AssertJ a community driven project that is listening to users and trying to help them. It turns out that most of the new features and improvements ideas come from users and that's great because it means it is providing value. If you have an idea to improve AssertJ, please don't hesitate to create an issue to let us know.
AssertJ is not a complex project so don't be afraid to contribute, we will be here to help you especially if it is your first open source contribution. Documentation improvements are welcome, we value them a lot.
AssertJ is built on our spare time, although we are doing our best to give quick feedback sometimes we won't be able to, be patient, be nice, be cool, we all have life to live, families to take care of and time consuming hobbies (pen and paper RPG and basketball for me!).
Joel Costigliola (AssertJ creator)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.
You can see assertions in action with the assertj examples tests of the assertj-examples project.
The best way to get help is to ask your question on stackoverflow (assertj tag).
F.A.Q:
The erroneous code probably looks like this:
protected static <T extends Date> T getDate() {
return (T) new Date();
}
@Test public void doesNotCompile()
// Error: reference to assertThat is ambiguous
Assertions.assertThat(getDate()).isEqualTo(getDate());
}The error is due to a combination of things:
This makes the compiler confused whether to use assertThat(Date) or assertThat(I), a complete explanation is given here.
Workaround 1:
Cast the object to a concrete type:
@Test public void doesCompile()
Assertions.assertThat((Date) getDate()).isEqualTo(getDate());
}Workaround 2:
For any AssertJ 3.x version except 3.9.0 (sigh), use AssertionsForClassTypes.assertThat as it does not provide any assertThat methods taking an interface.
@Test public void doesCompile()
AssertionsForClassTypes.assertThat((Date) getDate()).isEqualTo(getDate());
}AssertJ 3.9.0: Unfortunately you can't use this workaround since we wrongly added assertThat(CompletionStage) in AssertionsForClassTypes (CompletionStage is an interface). This has been fixed in 3.9.1.
The following examples show incorrect AssertJ API usage:
// 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 ! It does not assert anything and passes
assertThat(1 == 2);
// DO THIS: (fails as expected)
assertThat(1).isEqualTo(2);
// OR THIS (less classy but ok):
assertThat(1 == 2).isTrue();// BAD USAGE: DON'T DO THIS ! as/describedAs have no effect after the assertion
assertThat(actual).isEqualTo(expected).as("description");
assertThat(actual).isEqualTo(expected).describedAs("description");
// DO THIS: use as/describedAs before the assertion
assertThat(actual).as("description").isEqualTo(expected);
assertThat(actual).describedAs("description").isEqualTo(expected);// BAD USAGE: DON'T DO THIS ! overridingErrorMessage/withFailMessage have no effect after the assertion
assertThat(actual).isEqualTo(expected).overridingErrorMessage("custom error message");
assertThat(actual).isEqualTo(expected).withFailMessage("custom error message");
// DO THIS: use overridingErrorMessage/withFailMessage before the assertion
assertThat(actual).overridingErrorMessage("custom error message").isEqualTo(expected);
assertThat(actual).withFailMessage("custom error message").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");You can encounter errors similar to the one below when using AssertJ features requiring private fields introspection in Java 9+:
java.lang.reflect.InaccessibleObjectException:
Unable to make field private transient long java.util.Date.fastTime accessible:
module java.base does not "opens java.util" to unnamed module @66b72664Java 9 is much more restrictive concerning reflective access to non-public fields/methods, you need to open all required packages for AssertJ as follows (in particular it opens java.util):
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/java.util=ALL-UNNAMED
--add-opens java.base/java.io=ALL-UNNAMED
--add-opens java.base/java.math=ALL-UNNAMEDA nice article on the topic: https://blog.codefx.org/java/five-command-line-options-to-hack-the-java-9-module-system/#Reflectively-Accessing-Internal-APIs-With--add-opens
Android versions before 8.0.0 (API level 26) do 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.
Please note that soft assertions are not supported in Android, this is due the internal use of Byte Buddy that does not support Android.
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.BDDAssertions.*
// assertj on android
import static org.assertj.core.api.Java6BDDAssertions.*
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), enjoys playing basket ball, loves Terry Pratchett's disc world (surprised ?) and works 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 :
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.