Is org.junit.Assert.assertThat better than org.hamcrest.MatcherAssert.assertThat?

Question

I'm new to JUnit and Hamcrest and would like best-practice advice so I can decided which documentation to study first.

For starters, which of these assertThat methods is better?

1. org.junit.Assert.assertThat (from junit-4.11.jar)
2. org.hamcrest.MatcherAssert.assertThat (from hamcrest-core-1.3.jar)

According to one person last year, "JUnit has the assertThat method, but hamcrest has its own assertThat method that does the same thing.".

According to someone earlier this year, Hamcrest "could potentially give better error messages because the matcher is called to describe the mismatch".

It's hard to tell which versions of Junit and Hamcrest were compared in those posts. So I'd like a recommendation based on the most current released versions.

Staphylo

Answer 1

It's almost the exact same thing.

Recent versions of JUnit now include hamcrest.

In fact, org.junit.Assert.assertThat 's method signature is

public static <T> void assertThat(T actual,
                              org.hamcrest.Matcher<T> matcher)

which you will notice uses hamcrest matchers.

You may still want to include your own version of hamcrest because JUnit isn't updated very often and may not always use the latest version of hamcrest.

According to the maven pom, JUnit 4.11 uses hamcrest 1.3 which I believe is the most current as of this writing.

EDIT I've just read your second article http://blog.code-cop.org/2014/02/assert-or-matcherassert.html and it describes 2 slight differences in the hamcrest assertThat that make it more useful:

1. when the match fails, the error message includes what was different instead of "expected X but was Y". custom hamcrest matchers may include more detailed information about what exactly was wrong by implementing describeMismatch().
2. The assertThat signature is different in hamcrest using T actual, Matcher<? super T> matcher which allows matchers to be super types (like Matcher to compare Integers and Doubles). This usually doesn't matter but when you need it this is a nice feature to have.

So use org.hamcrest.MatcherAssert.assertThat.

Lemures

Thank you dkatzel, it was helpful to know that JUnit isn't updated very often so I might want to include my own version of Hamcrest. It's that sort of knowledge I was looking for, so thanks again. – Staphylo

@MichaelOsofsky I've updated my answer which I found that they are slightly different, I now prefer hamcrest. – Lemures

Thanks @dkatzel. Do you know if it's possible to control how Eclipse's content-assist feature resolves which assertThat? I'm using Maven with Eclipse. The Eclipse content-assist feature only tells me about Junit or Hamcrest but not both even though I've imported both import static org.hamcrest.MatcherAssert.* and import static org.junit.Assert.*. – Staphylo

sorry, I don't know. My guess is eclipse is getting confused since both packages have an assertThat. I wouldn't rely on bulk static importing using "*". Instead just import static org.hamcrest.MatcherAssert.assertThat; – Lemures

Thanks @dkatzel, I think that's the way to go. – Staphylo

In JUnit 4.11 it already uses Matcher<? super T> matcher version (junit.org/junit4/javadoc/4.11/org/junit/…). The Matcher<T> matcher) version is used in JUnit 4.10 (junit.org/junit4/javadoc/4.10/org/junit/…) – Baker

Answer 2

An excerpt from JUnit 5's User Guide:

However, JUnit Jupiter’s org.junit.jupiter.Assertions class does not provide an assertThat() method like the one found in JUnit 4’s org.junit.Assert class which accepts a Hamcrest Matcher. Instead, developers are encouraged to use the built-in support for matchers provided by third-party assertion libraries.

I think for JUnit 4, Hamcrest's assertThat is (officially) preferred.

Ruthenium

Answer 3

In junit 4.13 the method org.junit.Assert.assertThat() is marked deprecated and the usage of org.hamcrest.MatcherAssert.assertThat() is recommended.

So better use hamcrest right away even when you use an older version of junit.

Accessary