Feature of IsThrowable Hamcrest' Matcher

[Tibor17]

This matcher is requested from practical needs, when trying to solve the following test scenario. It is currently implemented out of JUnit, and working fine against tests.

The test case is testing code statements, where their call sequences matter a lot and some of them throw exception.
Which exception is expected, and where in the call sequence, all depends on the test code itself.

Thus suppose this formal test case:

@test(expected = SomeException.class)
public void myTest() {
statement
statement

This block must not throw SomeException
{
    statement
    statement
    statement
}

statement
statement

}

In this particular scenarion the developer dos not want to encapsulate the middle part into an ugly and dangerous try-catch block.
Here the test hehaviour wants to say that all statements are supposed to throw SomeException, except the middle part. This means that we want to keep Hamcrest in use with assertThat() and keep the tests as much verbose as possible.

The IsThrowable Matcher has four variations, where the last two are able to put the stack trace from the failing block to description (output) stream:

throwing(Class<? extends Throwable>... ): Matcher<IsThrowable.IBlock>
notThrowing(Class<? extends Throwable>... ): Matcher<IsThrowable.IBlock>
throwingDeeply(Class<? extends Throwable>... ): Matcher<IsThrowable.IBlock>
notThrowingDeeply(Class<? extends Throwable>... ): Matcher<IsThrowable.IBlock>

The form of is(not(throwing(...))) is equivalent to the form is(notThrowing(...)).
Similar with the form of is(not(throwingDeeply(...))) which is again equivalent to is(notThrowingDeeply(...)).
Once you use the 'Deeply', you can see the stack trace of failed block.
The allOf/anyOf, and/or combination forms of multiple Matchers would not be much readable, however still correct.

[dsaff]

Tibor,

Have you seen this?

http://thomasmueller.github.com/junit.contrib/

[Tibor17]

The block which is subject to the matcher must be encapsulated within run method of

public interface IsThrowable.IBlock {

void run() throws java.lang.Throwable;

}

Then we simply pass the instance of the block to the first parameter of assertThat() and call it 'block' underneath.

Now i am going to show you all use cases of the IsThrowable matcher.

assertThat(block, is(throwing()))
the 'block' is expected to throw any exception

assertThat(block, is(throwingDeeply()))
the 'block' is expected to throw any exception with block's stack trace (not an errorin 'block')

assertThat(block, is(notThrowing())) or assertThat(block, is(not(throwing())))
the 'block' is expected not to throw exceptions at all

assertThat(block, is(notThrowingDeeply())) or assertThat(block, is(not(throwingDeeply())))
the 'block' is expected not to throw exceptions at all (including block's stack trace if failure in it)

assertThat(block, is(throwing(ArrayIndexOutOfBoundsException.class, IndexOutOfBoundsException.class)))
the 'block' is expected to throw all assignable exceptions to java.lang.ArrayIndexOutOfBoundsException and
java.lang.IndexOutOfBoundsException

assertThat(block, is(throwingDeeply(ArrayIndexOutOfBoundsException.class, IndexOutOfBoundsException.class)))
the 'block' is expected to throw all assignable exceptions to java.lang.ArrayIndexOutOfBoundsException and
java.lang.IndexOutOfBoundsException (including block's stack trace if other failure in it).
If other exception is thrown, the deep stack trace appears an error in the 'block'.

assertThat(block, is(notThrowing(ArrayIndexOutOfBoundsException.class, IndexOutOfBoundsException.class))) or assertThat(block, is(not(throwing(ArrayIndexOutOfBoundsException.class, IndexOutOfBoundsException.class))))
the 'block' is expected to throw all exceptions except for those which are assignable to
java.lang.ArrayIndexOutOfBoundsException or java.lang.IndexOutOfBoundsException

assertThat(block, is(notThrowingDeeply(ArrayIndexOutOfBoundsException.class, IndexOutOfBoundsException.class))) or assertThat(block, is(not(throwingDeeply(ArrayIndexOutOfBoundsException.class, IndexOutOfBoundsException.class))))
the 'block' is expected to throw all exceptions except for those which are assignable to
java.lang.ArrayIndexOutOfBoundsException or java.lang.IndexOutOfBoundsException;
Otherwise a stack trace appears from the 'block'

Assignable exceptions means all specified and their sub-types.

[Tibor17]

I'll have a look, and we can discuss it tomorrow again.

Shortly, the assertThat() becomes modern style nowadays, and somehow a standard because Hamcrest matchers are verbose when designed properly.

But more tomorrow...

[Tibor17]

Hi David,

We have in my project several reasons to use the matchers.
First, putting messages to junit asserts was annoying. On the other side, the matchers are used to be self descriptive.
All of them are very verbose and easy to read without use of assertTrue, assertEquals, etc. So we have decided to accept the Hamcrest matchers.
Regarding this particular matcher, we use this form of IsThrowable, however we would appreciated if those could be already in the JUnit without any use of dependency. Means one library which has all we need for testing. No need to remember and maintain more dependencies.

I see other advantages using this matcher, like in this form:

expected = {IndexOutOfBoundsException.class, ArrayStoreException.class};
assertThat(block, describedAs("\n%0 ...,\n%1 ...", is(throwingDeeply(expected)), expected))

(no need to use the first String param in assertThat)

, or reusing mutual block several times (without extra method, and without copying to identical blocks of code).
This block is running twice and modifies status.

@Test(expected = ClassCastException.class)

List list = Collections.checkedList(Arrays.asList("b", "c"), String.class);
final ListIterator it = list.listIterator();
IBlock block = new IBlock() {
@Override public void run() throws Throwable {
it.next();
it.next();
it.set("a");
}
};
assertThat(block, both(is(throwingDeeply(NoSuchElementException.class))).and(is(notThrowing())));
list.set(0, new Object());


Just simple examples, but for us it is very useful and the way where we want to go - means matchers.
The tests, I have designed, declare bullet-proof implementation, thus so minimum effort on your side. The Java Doc is in the matcher's code. We can maybe put those four static methods to org.junit.matchers.JUnitMatchers as well in order to make it complete.

T

[dsaff]

Tibor17,

This seems like a great project for junit.contrib: if it sees high usage there, we'd reconsider it as a feature for JUnit core. What do you think?

David

[Tibor17]

ok, yes of course, it seems it's an internal process, I agree with you.
Is the junit.contrib project only downloadable, or i can submit my new changes there as well?

[dsaff]

junit.contrib is open for pull requests!

https://github.com/junit-team/junit.contrib

[Tibor17]

I have pulled the request with code changes to
junit-team/junit.contrib#7

Would the community proceed with a discussions and a commit?

[dsaff]

Closing here, redirecting to discussion in junit-team/junit.contrib#7