Skip to content

Latest commit

 

History

History

oleaster-matcher

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
README.md
README.md
 
 
pom.xml
pom.xml
 
 

README.md

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
expect("foobar").toMatch("fo{2}\\w+");

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

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:

<dependency>
	<groupId>com.mscharhag.oleaster</groupId>
	<artifactId>oleaster-matcher</artifactId>
	<version>0.2.0</version>
</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
(see: MatcherExamplesTest.java)

Primitive types

Numbers

The following samples show how numbers can be compared.

int value = 42;

// check for exact value
expect(value).toEqual(42);

// check for greater/smaller values
expect(value).toBeGreaterThan(41);
expect(value).toBeSmallerThan(43);

// 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
expect(value).toEqual(true);

// check if true
expect(value).toBeTrue();

// check if false
value = false;
expect(value).toBeFalse();

For comparing boolean values BooleanMatcher will be used.

Objects

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

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

// check if not null
expect(person).toBeNotNull();

// check if null
person = null;
expect(person).toBeNull();

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

For comparing Objects ObjectMatcher will be used.

Strings

The following samples show how String values can be compared.

// check for exact value
expect("foo").toEqual("foo");

// check string starting/ending
expect("foobar").toStartWith("foo");
expect("foobar").toEndWith("bar");

// check if a String contains a given substring
expect("foobar").toContain("oba");

// check if a String matches a regular expression
expect("foobar").toMatch(Pattern.compile("fo+\\w*"));
expect("foobar").toMatch("fo+\\w*");

For comparing Strings StringMatcher will be used.

Collections

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

// check the size of a collection
expect(myList).toBeEmpty();
expect(mySet).toHaveSize(15);

Maps

// check if a map contains a specific key
expect(myMap).toContainKey("key");

// check if a map contains a specific value
expect(myMap).toContainValue("value");

Date and Time

// check if a date is before or after another date
expect(date).toBeAfter(otherDate);
expect(date).toBeBefore(otherDate);

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

Exceptions

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();
}).toThrow(IllegalArgumentException.class);

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

Licence

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

https://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.