Skip to content
Branch: master
Find file History
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.

Oleaster Matcher

Oleaster Matcher is a small library that provides Jasmine-like Matchers for Java. Oleaster Matchers can be used as a replacement (or extension) for standard JUnit assertions.

Expectations written with Oleaster Matchers look like this:

import static com.mscharhag.oleaster.matcher.Matchers.*;

// same as JUnit's assertEquals(40 + 2, 42)
expect(40 + 2).toEqual(42);

// see if a String matches a regular expression

// test exceptions with Java 8 Lambdas
expect(() -> {
	// code that throws IllegalArgumentException
	throw new IllegalArgumentException();

Oleaster Matchers do not depend on the Oleaster JUnit Runner. You can use Oleaster Matchers without using the Oleaster JUnit Runner.

Getting started

To use Oleaster Matchers you need oleaster-matcher.jar in your classpath. If you are using Maven you just have to add the following dependency:


Matcher objects can be created using one the various static expect() methods of the Matchers class. To improve readability it is recommended to statically import Matchers.*

import static com.mscharhag.oleaster.matcher.Matchers.*;

Note: You can find the source of all examples shown here in the oleaster-examples module

Primitive types


The following samples show how numbers can be compared.

int value = 42;

// check for exact value

// check for greater/smaller values

// check for range
expect(value).toBeBetween(40, 45);

// floating point number can often not be precisely represented by float/double values.
// So make sure to compare them with an absolute error (delta)
expect(42.0000001).toBeCloseTo(42); // uses default delta of 0.00001
expect(42.0000001).toBeCloseTo(42, 0.000001);

For Numbers two different matcher classes are available:

Boolean values

The following samples show how boolean values can be compared.

boolean value = true;

// check for a given parameter

// check if true

// check if false
value = false;

For comparing boolean values BooleanMatcher will be used.


Person person = new Person("John", "Smith");

// check for equality, delegates to Person.equals()
expect(person).toEqual(new Person("John", "Smith"));

// check if not null

// check if null
person = null;

// check if instance of
expect("Hello World!").toBeInstanceOf(String.class);

For comparing Objects ObjectMatcher will be used.


The following samples show how String values can be compared.

// check for exact value

// check string starting/ending

// check if a String contains a given substring

// check if a String matches a regular expression

For comparing Strings StringMatcher will be used.


// check if a collection contains a specific item
expect(myList).toContain("my item");

// check the size of a collection


// check if a map contains a specific key

// check if a map contains a specific value

Date and Time

// check if a date is before or after another date

// check if a date is between two other dates
expect(date).toBeBetween(firstDate, otherDate);

// check if a date is close to another date
expect(date).toBeCloseTo(otherDate, deltaInMillis );


To test exceptions you just have to wrap the code that throws the expected exception into a lambda expression and pass it to expect(). The lambda expression will be executed and thrown exceptions will be caught. The thrown exception can be checked with toThrow() as shown bellow:

// check if an exception is thrown
expect(() -> {
	// code that throws IllegalArgumentException
	throw new IllegalArgumentException();

// with exception message
expect(() -> {
	// code that throws IllegalArgumentException
	throw new IllegalArgumentException("An argument is invalid");
}).toThrow(IllegalArgumentException.class, "An argument is invalid");

For testing exceptions ExceptionMatcher will be used.


This software is licensed under the Apache 2 license, quoted below.

Copyright 2014 Michael Scharhag

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

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.

You can’t perform that action at this time.