Converting your JUnit 3 & 4 assertions to AssertJ

This page will help you converting your existing JUnit assertions to AssertJ ones. Note that both types of assertions can coexist, you don't have to migrate all at once.

The idea is to convert code like :

assertEquals(expected, actual);
to :

assertThat(actual).isEqualTo(expected);

If you use JUnit 5 then check the JUnit 5 Assertions Migration Guide.

There are several ways to perform the conversion :

  • automatically with a shell script.
  • manually using the regexps described in this page.
  • With IntelliJ IDEA, using the Assertions2Assertj plugin.
  • With IntelliJ IDEA, using the Structural Search and Replace (SSR) feature.

Automatically converting your JUnit assertions to AssertJ

It is simple : use the proper script depending on your OS :

Each shell scripts is based on the sed stream editor and regexps. It recursively looks at all *Test.java files and performs search and replace to convert JUnit assertions to AssertJ ones (if the *Test.java file pattern does not suit you, just change the script according to your needs).

The script works on windows within a bash console like git bash (tested) or cygwin (not tested). I haven't tested the OSX script since I don't own a mac.

Usage : On windows or unix execute the script in the base directory containing the test files :

# in the directory containing the test files
convert-junit-assertions-to-assertj.sh

Usage : On OSX execute the script in the base directory containing the test files :

# in the directory containing the test files
convert-junit-assertions-to-assertj-on-osx.sh

It is not perfect but should do most of the job. After executing it, you will need to :

  • optimize imports with your IDE to remove unused imports.
  • if you were using assertEquals with a delta to compare numbers, you will need to statically import org.assertj.core.api.Assertions.offset which is how you express deltas in AssertJ (see the number_assertions_with_offset_examples() test at the end of NumberAssertionsExamples for an example).

The script handles the cases where you use an assertion description, for example :

assertEquals("test context", "a", "a");
will be replaced by :

assertThat("a").as("test context").isEqualTo("a");

See below the output of the script execution :

Converting JUnit assertions to AssertJ assertions on files matching pattern : *Test.java

 1 - Replacing : assertEquals(0, myList.size()) ............... by : assertThat(myList).isEmpty()
 2 - Replacing : assertEquals(expectedSize, myList.size()) .... by : assertThat(myList).hasSize(expectedSize)
 3 - Replacing : assertEquals(expectedDouble, actual, delta) .. by : assertThat(actual).isCloseTo(expectedDouble, within(delta))
 4 - Replacing : assertEquals(expected, actual) ............... by : assertThat(actual).isEqualTo(expected)
 5 - Replacing : assertArrayEquals(expectedArray, actual) ..... by : assertThat(actual).isEqualTo(expectedArray)
 6 - Replacing : assertNull(actual) ........................... by : assertThat(actual).isNull()
 7 - Replacing : assertNotNull(actual) ........................ by : assertThat(actual).isNotNull()
 8 - Replacing : assertTrue(logicalCondition) ................. by : assertThat(logicalCondition).isTrue()
 9 - Replacing : assertFalse(logicalCondition) ................ by : assertThat(logicalCondition).isFalse()
10 - Replacing : assertSame(expected, actual) ................. by : assertThat(actual).isSameAs(expected)
11 - Replacing : assertNotSame(expected, actual) .............. by : assertThat(actual).isNotSameAs(expected)

12 - Replacing JUnit static imports by AssertJ ones, at this point you will probably need to :
12 --- optimize imports with your IDE to remove unused imports
12 --- add "import static org.assertj.core.api.Assertions.within;" if you were using JUnit number assertions with deltas

On windows you might have permission problems as sed creates temp files. If you get this error, you have to grant write permissions to the current user for the folder where your test files live.

Converting JUnit assertions to AssertJ assertions on files matching pattern : *Test.java

 1 - Replacing : assertEquals(0, myList.size()) ................. by : assertThat(myList).isEmpty()
sed: preserving permissions for `./sed005904': Permission denied
sed: preserving permissions for `./sed004220': Permission denied

Converting your JUnit assertions to AssertJ with regexp

Here's a list of find/replace expressions that allow to change JUnit assertions into AssertJ assertions (don't forget to check the regexp mode in your editor replace window).

The order of find/replace is important, so that you can benefit from the most relevant AssertJ assertions. For example you should convert assertEquals(0, myList.size()) to assertThat(myList).isEmpty() instead of assertThat(myList.size()).isEqualTo(0)

1 - Converting assertEquals(0, myList.size()) to assertThat(myList).isEmpty()

Find/replace Regexp :

assertEquals\(0,(.*).size\(\)\); -> assertThat(\1).isEmpty();

It's important to run this one before the assertEquals -> isEqualTo conversion to avoid ending with : assertThat(myList.size()).isEqualTo(0)

2 - Converting assertEquals(expectedSize, myList.size()) to assertThat(myList).hasSize(expectedSize)

Find/replace Regexp :

assertEquals\((.*),(.*).size\(\)\); -> assertThat(\2).hasSize(\1);

It's important to run this one before the assertEquals -> isEqualTo conversion to avoid ending with : assertThat(myList.size()).isEqualTo(expectedSize)

3 - Converting assertEquals(value, valueUnderTest) to assertThat(valueUnderTest).isEqualTo(value)

Find/replace Regexp :

assertEquals\((.*),(.*)\); -> assertThat(\2).isEqualTo(\1);
4 - Converting assertNull(objectUnderTest) to assertThat(objectUnderTest).isNull()

Find/replace Regexp :

assertNull\((.*)\); -> assertThat(\1).isNull();
5 - Converting assertNotNull(objectUnderTest) to assertThat(objectUnderTest).isNotNull()

Find/replace Regexp :

assertNotNull\((.*)\); -> assertThat(\1).isNotNull();
6 - Converting assertTrue(logicalCondition) to assertThat(logicalCondition).isTrue()

Find/replace Regexp :

assertTrue\((.*)\); -> assertThat(\1).isTrue();
7 - Converting assertFalse(logicalCondition) to assertThat(logicalCondition).isFalse()

Find/replace Regexp :

assertFalse\((.*)\); -> assertThat(\1).isFalse();