Skip to content


Subversion checkout URL

You can clone with
Download ZIP

New and noteworthy

Joel Costigliola edited this page · 15 revisions

(to main page)

AssertJ core next release

Special thanks to Mariusz Smykula for its contributions.

New and noteworthy

BDD assertions style

Instead of using assertThat use then to start assertions, example:

public void host_dinner_party_where_nobody_dies() {
  Mansion mansion = new Mansion();


  then(mansion.colonel()).isEqualTo("well kempt");
  then(mansion.professor()).isEqualTo("bloodied and disheveled");

AssertJ core 1.5.0 release

Release date : 2013-11-06
Special thanks to William Delanoue, Jean Christophe Gay, Tomasz Bartczak and Michał Piotrkowski for their contributions.

New and noteworthy in 1.5.0

Extracting feature for method calls

Like extracting feature but instead of extracting properties/fields we extract the result of given method invocation on the Iterable's elements under test, put the results into a new Iterable which is becoming the Iterable under test.

It allows you to test the method results of the Iterable's elements instead of testing the elements themselves, it is especially usefull for classes that does not conform to Java Bean's getter specification (i.e. public String toString() or public String status() instead of public String getStatus()).

Let's take an example to make things clearer :

 // Build a array of WesterosHouse, a WesterosHouse has a method: public String sayTheWords()

 List<WesterosHouse> greatHouses = new ArrayList<WesterosHouse>();
 greatHouses.add(new WesterosHouse("Stark", "Winter is Comming"));
 greatHouses.add(new WesterosHouse("Lannister", "Hear Me Roar!"));
 greatHouses.add(new WesterosHouse("Greyjoy", "We Do Not Sow"));
 greatHouses.add(new WesterosHouse("Baratheon", "Our is the Fury"));
 greatHouses.add(new WesterosHouse("Martell", "Unbowed, Unbent, Unbroken"));
 greatHouses.add(new WesterosHouse("Tyrell", "Growing Strong"));

 // let's verify the words of great houses in Westeros:

 assertThat(greatHouses).extractingResultOf("sayTheWords").contains("Winter is Comming", "We Do Not Sow", "Hear Me Roar")
                                                          .doesNotContain("Lannisters always pay their debts");

Thanks to Michał Piotrkowski for this contribution.

Better Date assertions

New Date assertions isEqualToIgnoring<Millis/Seconds/Minutes/Hours> to compare two dates ignoring some fields.

For example, one can compare two dates without minutes, seconds and milliseconds:

Date date1 = parseDatetime("2003-04-26T13:01:35");
Date date2 = parseDatetime("2003-04-26T13:02:00");

// OK : all dates fields are the same if we leave minutesn seconds and milliseconds fields

// KO : fail as minute fields differ

Thanks to William Delanoue for this contribution.

New Date assertions isInSame<Second/Minute/Hour>WindowAs

We want to perform a true chronological comparison and not a field by field comparison like we do in isInSame<Second/Minute/Hour>As.

Let's see that on an example :

Date date1 = parseDatetimeWithMs("2003-04-26T13:01:02.999");
Date date2 = parseDatetimeWithMs("2003-04-26T13:01:03.000");

// succeeds as time difference is 1ms < 1s

// This assertion fails as seconds fields differ.
Ease using date assertions by accepting Date represented as String with various format accepted
// You can use date String representation with various format (we take care of parsing String as Date):
// - yyyy-MM-dd
// - yyyy-MM-dd'T'HH:mm:ss,
// - yyyy-MM-dd'T'HH:mm:ss.SSS,
// Examples:

New Map assertions

Add containsOnly and containsExactly to Map assertions using the same semantics as the one in Iterable assertions:

Map<String, TolkienCharacter> characters = new LinkedHashMap<>();
characters.put(frodo.getName(), frodo);
characters.put(galadriel.getName(), galadriel);
characters.put(gandalf.getName(), gandalf);
characters.put(sam.getName(), sam);

        entry(sam.getName(), sam),
        entry(frodo.getName(), frodo),
        entry(gandalf.getName(), gandalf),
        entry(galadriel.getName(), galadriel));

        entry(frodo.getName(), frodo),
        entry(galadriel.getName(), galadriel),
        entry(gandalf.getName(), gandalf),
        entry(sam.getName(), sam));

Complete release notes

New features

  • add isInSame<Second/Minute/Hour>WindowAs assertions
  • add isEqualToIgnoring<Millis/Seconds/Minutes/Hours> assertions (William Delanoue)
  • New Iterable assertion feature: extractingResultOf (Michał Piotrkowski)
  • New Map assertions: containsExactly and containsOnly (already existed for iterables) (Jean Christophe Gay)


  • Various Javadoc API improvements (have a look at date assertions)


  • AbstractIterableAssert.containsOnlyOnce() should not require objects to implement Comparable (Tomasz Bartczak)
  • hasSameSizeAs() was not working with primitive arrays

AssertJ core 1.4.0 release

Release date : 2013-09-15
Special thanks to Brian Laframboise, William Delanoue, Marcus Klimstra, Ted Young, Piotr Betkier, Marcin Mikosik and Jean Christophe Gay for their contributions.

New and noteworthy in 1.4.0

XML assertions

String based XML assertions have been added, it allows you to compare a String representing an XML document with another one (whatever how formatted the XML is).

Let's see that with some examples :

String expectedXml = "<rings>\n" +
                      "  <bearer>\n" +
                      "    <name>Frodo</name>\n" +
                      "    <ring>\n" +
                      "      <name>one ring</name>\n" +
                      "      <createdBy>Sauron</createdBy>\n" +
                      "    </ring>\n" +
                      "  </bearer>\n" +

// XML String don't need to be formatted, AssertJ will format both actual and expected string before comparison.
// Whatever how formatted your xml string is, isXmlEqualTo assertion is able to compare it with another xml String.
String oneLineXml = "<rings><bearer><name>Frodo</name><ring><name>one ring</name><createdBy>Sauron</createdBy></ring></bearer></rings>";

Since both actual and expected XML String are formatted the same way, it's easy to see what was different in case of error.

You can also easily compare your XML String to the content of an XML file, e.g:

assertThat(xmlString).isXmlEqualToContentOf(new File("expected.xml"));

Soft assertions

Using soft assertions, AssertJ collects all assertion errors instead of stopping at the first one.

So, assuming something goes awry at your dinner party, when using "standard" assertions, this test:

  public void host_dinner_party_where_nobody_dies() {
    Mansion mansion = new Mansion();
    assertThat(mansion.guests()).as("Living Guests").isEqualTo(7);
    assertThat(mansion.revolverAmmo()).as("Revolver Ammo").isEqualTo(6);
    assertThat(mansion.colonel()).as("Colonel").isEqualTo("well kempt");
    assertThat(mansion.professor()).as("Professor").isEqualTo("well kempt");

will yield the less-than-ideal exception message of org.junit.ComparisonFailure: [Living Guests] expected:<[7]> but was<[6]>.

Using soft assertions you can collect all the failed assertions together like so:

  public void host_dinner_party_where_nobody_dies() {
    Mansion mansion = new Mansion();
    SoftAssertions softly = new SoftAssertions();
    softly.assertThat(mansion.guests()).as("Living Guests").isEqualTo(7);
    softly.assertThat(mansion.revolverAmmo()).as("Revolver Ammo").isEqualTo(6);
    softly.assertThat(mansion.colonel()).as("Colonel").isEqualTo("well kempt");
    softly.assertThat(mansion.professor()).as("Professor").isEqualTo("well kempt");

When the collected assertions are all asserted together they yield a more descriptive error message:

The following 4 assertions failed:
 1) [Living Guests] expected:<[7]> but was:<[6]>
 2) [Library] expected:<'[clean]'> but was:<'[messy]'>
 3) [Candlestick] expected:<'[pristine]'> but was:<'[bent]'>
 4) [Professor] expected:<'[well kempt]'> but was:<'[bloodied and disheveled]'>

Thanks to Brian Laframboise for this contribution.

Complete release notes

Breaking changes

  • isLenientEqualsToByIgnoringFields renamed to isEqualToIgnoringGivenFields
  • isLenientEqualsToByAcceptingFields renamed to isEqualToComparingOnlyGivenFields
  • isLenientEqualsToByIgnoringNullFields renamed to isEqualToIgnoringNullFields
  • isEqualsToByComparingFields renamed to isEqualToComparingFieldByField

New features

  • New Iterable assertion : containsExactlyElementsOf (Jean Christophe Gay)
  • New Iterable assertion : containsSubsequence (Marcin Mikosik)
  • Assertion file template for IntelliJ (Piotr Betkier)


  • Test description (i.e. as() method) now supports String.format (William Delanoue)
  • Added Javadoc for String assertions and cleaned up English in (Ted Young)
  • Various Javadoc API improvements

New and noteworthy in 1.3.0

AssertJ core 1.3.0 release

Release date : 2013-06-30
Special thanks to William Delanoue, Jean Christophe Gay, Ted M. Young and Mikhail Mazursky for their contributions.

Breaking changes

The following assertions that were deprecated since the first version (and coming from Fest Assert) have been removed, we thought that they were very unclear :

  • areNotAtLeast, areNotAtMost, areNotExactly
  • haveNotAtLeast, haveNotAtMost, haveNotExactly

Class assertions

Class assertions have been added, let's see that with some examples :



// You can check Class fields with :
// - hasFields for public fields
// - hasDeclaredFields for all declared fields (whatever field's visibility)
assertThat(TolkienCharacter.class).hasDeclaredFields("name", "race");

Complete release notes

Breaking changes

  • Removing assertions : areNotAtLeast, areNotAtMost, areNotExactly, haveNotAtLeast, haveNotAtMost, haveNotExactly

New features

  • Introduce Class assertions (William Delanoue)
  • New Throwables assertions : hasCauseInstanceOf, hasCauseExactlyInstanceOf, hasRootCauseInstanceOf and hasRootCauseExactlyInstanceOf (Jean Christophe Gay)
  • Add containsExactly assertion for arrays (already existed for iterables) (Jean Christophe Gay)
  • Add containsOnlyOnce assertion for arrays and iterables (William Delanoue)


  • Javadoc API improvements
  • Provide a way to extend AssertJ existing assertions that does not break assertion chaining, see issue 9 for a detailed explanation (Mikhail Mazursky)
  • Make isNotEqualTo, isIn and isNotIn assertions more flexible by not using generics in "expected" parameter (Mikhail Mazursky)
  • Allow defining the extracted type of extracted values from array in extracting feature (William Delanoue)
  • assertDoesNotMatch() String assertion should not allow object to check to be null (Mikhail Mazursky)


  • Fix IterableAssert.startsWith infinite loop for inifinite iterables

AssertJ core 1.2.0 release

Release date : 2013-05-12
Special thanks to William Delanoue and Mikhail Mazursky for their contributions to assertj-core 1.2.0.

New and noteworthy in 1.2.0

Improved Map assertions

The First improvement is related to map entries, often testing map entries looks like :

Map<String, String> address = ....
                        MapAssert.entry("zip", "43865"),
                        MapAssert.entry("lastName", "Frazier"),
                        MapAssert.entry("state", "IA"),
                        MapAssert.entry("city", "Culloden")

We can simplify this by getting rid of the repeated MapAssert.entry calls:

 assertThat(address).containsEntry("zip", "43865")
                    .containsEntry("lastName", "Frazier")
                    .containsEntry("state", "IA")
                    .containsEntry("city", "Culloden");

Same thing has been done with doesNotContainEntry.

The second improvement is to allow checking that a Map contains multiple keys at once, so instead of :


you can now write :

assertThat(elvesRingBearers).containsKeys(nenya, narya, vilya);

More flexible assertions

Make isEqualTo, isSameAs and isNotSameAs assertions more flexible by not using generics in "expected" parameter.
It solves the following problem where an Employee class inherits from Person :

Employee bill = new Employee("Bill", 50, "micro$oft");
assertThat(bill).isEqualTo(bill); // OK
// now let's view billou as a Person and not an Employee anymore
Person billou = bill;
// Before 1.2.0 version, the next line used led to a compile error as
// parameter expected type is Employee (although bill and billou are identical).

The only drawback is less strongly type checking but we think flexibility was more important that type checks. Note that this is the beginning of making AssertJ more flexible, there is still work to be done in this area.

Complete release notes

New features

  • Introduce CharSequenceAssert to support StringBuffer, StringBuilder and all subtypes of CharSequence assertions (Mikhail Mazursky)
  • New Iterable assertion : doesNotContainAnyElementsOf(Iterable) (William Delanoue)
  • New Number assertions : isBetween and isStrictlyBetween (William Delanoue)


  • Code coverage improvements
  • Make isEqualTo, isSameAs and isNotSameAs assertions more flexible by not using generics in "expected" parameter (William Delanoue, Mikhail Mazursky)
  • IterableAssert doesNotHaveDuplicates performance enhancement (~500x faster)
  • Improve Map assertions related to entries (William Delanoue)
  • Improve Map assertions when checking several keys presence (William Delanoue)
  • Deprecate methods that are useless to avoid misleading users (Mikhail Mazursky)
  • Javadoc API improvements (still a lot to do ...)


  • Fix containsSequence assertion that stopped after first partial match

AssertJ core 1.1.0 release

Release date : 2013-04-15

New and noteworthy in 1.1.0

Extracting feature

With extracting you can extract values from an array/iterable elements and perform assertions on those extracted values.
It is similar to extractProperty feature but is easier to use (I think), it is also able to extract properties as well as public fields while extractProperty can only extract properties (as its name suggests).
Last but not least, you can extract several public fields and properties at once, the extracted values corresponding to the same element being grouped in a tuple.

Simple example showing how to check the names of TolkienCharacter elements in fellowshipOfTheRing list :

// "name" need to be either a property or a public field of TolkienCharacter class.
                               .contains("Boromir", "Gandalf", "Frodo", "Legolas")
                               .doesNotContain("Sauron", "Elrond");

Example showing how to check the name, age and race's name of each TolkienCharacter elements :
the extracted name, age and race's name values corresponding to the same element are grouped in a tuple, thus you need to use tuples for expected values.

// tuple comes from : import static org.assertj.core.api.Assertions.tuple;
assertThat(fellowshipOfTheRing).extracting("name", "age", "")
                               .contains(tuple("Boromir", 37, "Man"),
                                         tuple("Sam", 38, "Hobbit"),
                                         tuple("Legolas", 1000, "Elf"));

This feature is a much more powerful version of onProperty that was introduced in Fest 1.4.

Error messages improvement

Error messages are now multiline to ease comparing the actual value to the expected one.

Here an example with a failing Date assertion :

// failing assertion ! 

In assertj-core 1.0.0, it produces this error message :

expected:<2013-01-01T00:00:00> to be strictly before:<2000-01-01T00:00:00>

In assertj-core 1.1.0 the error message is now :

to be strictly before:

Note that involved objects are aligned to the same column to ease comparing them.

Complete release notes

New features

  • reintroduce onProperty feature but named it extracting
  • extracting() method should be able to extract fields
  • allow extracting several fields or properties in iterable or array assertions


  • Assertions error messages should be multiline for better readability


  • Problem with AbstractAssert.overridingErrorMessage(String newErrorMessage, Object[] args)
  • All contains assertions should not throw an exception if 'actual' and 'values' are empty

AssertJ core 1.0.0 release

Release date : 2013-03-26

1.0.0 version is the first AssertJ release after the fork from FEST 2.0M10, here are the changes compared to FEST 2.0M10 :

New features

  • github #5 Add StringAssert.containsSequence


  • github #2 Make custom assertions easier to write
  • github #6 Varargs for StringAssert::contains() to avoid repeating contains several times
  • github #10 Add osgi metadata to MANIFEST
  • github #16 assertThat() should accept an Iterator
Something went wrong with that request. Please try again.