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.
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.7</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.7</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).
- 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