Hamcrest Mail

Hamcrest Mail is an extension library for the Java Hamcrest matcher library.
It provides matchers for types from the javax.mail and jakarta.mail packages.

The assertj-mail sister project provides a set of AssertJ assertions with similar features.

Usage

To use Hamcrest Mail in a Maven project add a dependency on org.devopsix:hamcrest-mail (for Java EE 8 / javax.mail) or org.devopsix:hamcrest-mail-jakarta (for Jakarta EE 9+ / jakarta.mail) to the pom.xml file.

<!-- Maven coordinates for Java EE 8 / javax.mail -->
<dependency>
    <groupId>org.devopsix</groupId>
    <artifactId>hamcrest-mail</artifactId>
    <version>2.0.8</version>
    <scope>test</scope>
</dependency>
<!-- Maven coordinates for Jakarta EE 9+ / jakarta.mail -->
<dependency>
    <groupId>org.devopsix</groupId>
    <artifactId>hamcrest-mail-jakarta</artifactId>
    <version>2.0.8</version>
    <scope>test</scope>
</dependency>

The matchers are available as static methods on the MailMatchers class.

Here are a few examples:

Message message;
Assert.assertThat(message, MailMatchers.hasFrom("anna@example.com"));
Assert.assertThat(message, MailMatchers.hasTo("bob@example.com"));
Assert.assertThat(message, MailMatchers.hasRecipients(Matchers.iterableWithSize(1)));
Assert.assertThat(message, MailMatchers.hasSubject("Message from Anna"));
Assert.assertThat(message, MailMatchers.hasHeader("Return-Path", Matchers.notNullValue()));
Assert.assertThat(message, MailMatchers.hasDateHeader("Resent-Date", Matchers.isA(OffsetDateTime.class)));
// OffsetDateTimeMatchers is from eXparity/hamcrest-date:
// https://github.com/eXparity/hamcrest-date
Assert.assertThat(message, MailMatchers.hasDate(OffsetDateTimeMatchers.within(1, MINUTES, now())));
// Casting to Matcher is required when a matcher's signature is
// Matcher<Iterable<? extends T>> or Matcher<Iterable<? super T>>
Assert.assertThat(message, MailMatchers.hasHeaders("Received", (Matcher)Matchers.hasItems(
        Matchers.containsString("host1"), Matchers.containsString("host2"))));

More example can be found in the examples directory (for Java EE 8 / javax.mail) and in the examples-jakarta directory (for Jakarta EE 9+ / jakarta.mail).

Matchers

• hasDate - Tests the “Date” header against a given date or matcher
• hasFrom - Tests the “From” header against a given string or matcher
• hasSender - Tests the “Sender” header against a given string or matcher
• hasReplyTo - Tests the “Reply-To” header against a given string or matcher
• hasTo - Tests the “To” header against a given string or matcher
• hasCc - Tests the “Cc” header against a given string or matcher
• hasBcc - Tests the “Bcc” header against a given string or matcher
• hasRecipients - Tests a message’s recipients against a given matcher
• hasAddress - Tests an InternetAddress’ address against a given matcher
• hasPersonal - Tests an InternetAddress’ personal name against a given matcher
• hasSubject - Tests the “Subject” header against a given string or matcher
• hasHeader - Tests a named header against a given string or matcher
• hasHeaders - Tests a named header which may occur multiple times against a given matcher
• hasDateHeader - Tests a named date header against a given date or matcher
• hasDateHeaders - Tests a named date header which may occur multiple times against a given matcher
• hasValidDkimSignature - Tests a message for having a valid DKIM signature
• hasTextContent - Tests a message or a part of a multipart message for having plain text content matching a given matcher
• hasBinaryContent - Tests a message or a part of a multipart message for having binary content matching a given matcher
• hasMultipartContent - Tests a message or a part of a multipart message for having multipart content matching a given matcher
• hasMultipartContentRecursive - Tests a message or a part of a multipart message and recursively all child parts thereof for having at least one part with multipart content matching a given matcher
• multipartMixed - Tests a multipart for having “multipart/mixed” content type
• multipartAlternative - Tests a multipart for having “multipart/alternative” content type
• multipartRelated - Tests a multipart for having “multipart/related” content type
• multipartContentType - Tests a multipart’s content type against a given matcher
• hasPart - Tests a multipart for having at least one part matching a given matcher
• hasParts - Tests a multipart for having parts matching a given matcher