AssertJ Extensions

Table of Contents

• 1. The Convert Assertions Shell Script
• 2. The Conditions adapter
• 3. Maven Dependencies
• 4. Legal Stuff
  • 4.1. License
• 5. Release Notes (using Sonatype OSSRH)

Suppose you have been using Hamcrest for your tests, but would like to move to AssertJ to take advantage of its fluent API and better "discoverability" within an IDE. On the other hand you have a bunch of assertions that need porting over and you don’t much fancy changing them all by hand.

This repo provides two tools, intended to be used together, that can help.

• a shell script to convert (the most common) Hamcrest style assertThat’s into corresponding AssertJ ones.

• an adapter class to allow Hamcrest's Matcher API into AssertJ’s Condition API.

Read on to learn more…​

1. The Convert Assertions Shell Script

The first tool is the convert-hamcrest-assertions-to-assertj.sh script. This is intended to be run against your source code from the command line, replacing the most common assertThat() Hamcrest assertions to their corresponding AssertJ ones.

The script itself can be found here.

Run the script from the root of the source you want to convert. If no arguments are passed, it will search for files names *Test.java. Use -h to see other options.

Tip	the script is adapted from the similar script that AssertJ provides for converting JUnit assertions. It also fixes an issue of using sed -i which seems to be broken on Windows.

2. The Conditions adapter

One of the benefits of Hamcrest, of course, is the extensibility of is Matcher API. So even if most of your assertions are run of the mill simple stuff covered by the conversion script, you are bound to have some more exotic assertions too.

AssertJ itself has an API similar to Hamcrest’s Matcher, called Condition. The Conditions adapter provided by this repo allows you to use Hamcrest Matchers directly within AssertJ. That means you can write things such as:

final int actual = 3;
assertThat(actual).is(matchedBy(Matchers.equalTo(3)));

and

final String actual = "how now brown cow";
assertThat(actual).is(matchedBy(Matchers.containsString("now brown")));

and

final List<String> actual = Arrays.asList("how","now","brown","cow");
assertThat(actual).is(matchedBy(Matchers.containsInAnyOrder("brown", "now", "cow", "how")));

In the above the matchedBy is a factory method that returns the adapter; just add this static import:

import static com.danhaywood.java.assertjext.Conditions.matchedBy;

Going back to the The Convert Assertions Shell Script, if you look at the last substitution you’ll see that the last sed expression actually uses this syntax. Thus, running the script should fully migrate all of your existing Hamcrest style assertions.

At this point you then have a choice: you can either rewrite those Hamcrest assertions to corresponding AssertJ ones, or leave them as is. You can also continue to tap into the power of Hamcrest if and when you find you can better express the intent that way (even Joel, AssertJ’s maintainer, straightforwardly recognizes this, eg as in this Stackoverflow answer.

3. Maven Dependencies

Add the following to the <dependencies> section of your pom.xml:

<dependency>
    <groupId>com.danhaywood.java</groupId>
    <artifactId>danhaywood-java-assertjext</artifactId>
    <version>0.1.0</version>
    <scope>test</scope>
</dependency>

If you want to use the latest SNAPSHOT, change the <version> to 0.1.1-SNAPSHOT.

4. Legal Stuff

4.1. License

Copyright 2015 Dan Haywood

Licensed under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.

5. Release Notes (using Sonatype OSSRH)

The release.sh script automates the release process. It performs the following:

• performs a sanity check (mvn clean install -o) that everything builds ok

• bumps the pom.xml to a specified release version, and tag

• performs a double check (mvn clean install -o) that everything still builds ok

• releases the code using mvn clean deploy

• bumps the pom.xml to a specified snapshot version

For example:

sh release.sh 0.1.0 \
              0.1.1-SNAPSHOT \
              [email protected] \
              "this is not really my passphrase"

where

• $1 is the release version

• $2 is the snapshot version

• $3 is the email of the secret key (~/.gnupg/secring.gpg) to use for signing

• $4 is the corresponding passphrase for that secret key.

Other ways of specifying the key and passphrase are available, see the `pgp-maven-plugin’s documentation.

If the script completes successfully, then push changes:

git push origin master
git push origin 0.1.0

If the script fails to complete, then identify the cause, perform a git reset --hard to start over and fix the issue before trying again. Note that in the dom’s `pom.xml the nexus-staging-maven-plugin has the autoReleaseAfterClose setting set to true (to automatically stage, close and the release the repo). You may want to set this to false if debugging an issue.

According to Sonatype’s guide, it takes about 10 minutes to sync, but up to 2 hours to update [search](http://search.maven.org).