From Wikipedia, the free encyclopedia
Jump to navigation Jump to search

Hamcrest is a framework that assists writing software tests in the Java programming language. It supports creating customized assertion matchers ('Hamcrest' is an anagram of 'matchers'), allowing match rules to be defined declaratively.[1] These matchers have uses in unit testing frameworks such as JUnit and jMock. Hamcrest has been included in JUnit 4 since 2012,[2] but was omitted from JUnit 5 in 2017.[3]

Hamcrest has been ported to C++, C#,[4] Objective-C, Python,[5] ActionScript 3,[6] PHP,[7] JavaScript,[8] Erlang,[9] R,[10] Rust,[11] and Swift.[12]


"First generation" unit test frameworks provide an 'assert' statement, allowing one to assert during a test that a particular condition must be true. If the condition is false, the test fails. For example:

assert(x == y);

But, in many languages, this syntax fails to produce a sufficiently good error message if 'x' and 'y' are not equal. It would be better if the error message displayed the value of 'x' and 'y'. To solve this problem, "second generation" unit test frameworks provide a family of assertion statements, which produce better error messages. For example,

assert_equal(x, y);
assert_not_equal(x, y);

But this leads to an explosion in the number of assertion macros, as the above set is expanded to support comparisons different from simple equality. So "third generation" unit test frameworks use a library such as Hamcrest to support an 'assert_that' operator that can be combined with 'matcher' objects, leading to syntax like this:

assert_that(x, equal_to(y))
assert_that(x, is_not(equal_to(y)))

The benefit is that there are still fluent error messages when the assertion fails, but with greater extensibility. It is now possible to define operations that take matchers as arguments and return them as results, leading to a grammar that can generate a huge number of possible matcher expressions from a small number of primitive matchers.

These higher-order matcher operations include logical connectives (and, or and not), and operations for iterating over collections. This results in a rich matcher language which allows complex assertions over collections to be written in a declarative style rather than a procedural style.[citation needed]


  1. ^ "The Hamcrest Tutorial".
  2. ^ Marc Philipp (21 Oct 2012). "Summary of Changes in version 4.4". JUnit documentation. Retrieved 20 Sep 2016.
  3. ^ "JUnit 5 User Guide - Third-party Assertion Libraries". Retrieved 11 May 2018.
  4. ^ "NHamcrest". GitHub. 29 July 2021.
  5. ^ "PyHamcrest".
  6. ^ "Hamcrest-AS3". GitHub. 4 July 2020.
  7. ^ "Hamcrest - Google Code".
  8. ^ "Hamcrest4Qunit". GitHub. 22 September 2021.
  9. ^ "Hamcrest Erlang". GitHub. 22 February 2022.
  10. ^ "Hamcrest for Renjin".
  11. ^ "Hamcrest Cargo package".
  12. ^ "Hamcrest for Swift". GitHub. 23 February 2022.

External links[edit]