001/**
002 * Copyright (C) 2011 rwoo@gmx.de
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *         http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package com.googlecode.catchexception.apis;
017
018import org.hamcrest.Matcher;
019import org.junit.matchers.JUnitMatchers;
020
021import com.googlecode.catchexception.apis.internal.hamcrest.ExceptionMessageMatcher;
022import com.googlecode.catchexception.apis.internal.hamcrest.ExceptionNoCauseMatcher;
023
024/**
025 * Provides some Hamcrest {@link Matcher matchers} to match some
026 * {@link Exception exception} properties.
027 * <p>
028 * EXAMPLE:
029 * <code><pre class="prettyprint lang-java">// given an empty list
030List myList = new ArrayList();
031
032// when we try to get the first element of the list
033catchException(myList).get(1);
034
035// then we expect an IndexOutOfBoundsException with message "Index: 1, Size: 0" 
036assertThat(caughtException(),
037  allOf(
038    is(IndexOutOfBoundsException.class), 
039    hasMessage("Index: 1, Size: 0"),
040    hasNoCause()
041  )
042);</pre></code>
043 * <p>
044 * To combine the standard Hamcrest matchers, your custom matchers, these
045 * matchers, and other matcher collections (as {@link JUnitMatchers}) in a
046 * single class follow the instructions outlined in <a
047 * href="http://code.google.com/p/hamcrest/wiki/Tutorial#Sugar_generation">Sugar
048 * generation</a>.
049 * <p>
050 * Hint: This class might use <a
051 * href="http://code.google.com/p/hamsandwich">hamsandwich</a> in the future but
052 * as long as hamsandwich is not in any public maven repository, this class will
053 * not use hamsandwich.
054 * 
055 * @author rwoo
056 */
057public class CatchExceptionHamcrestMatchers {
058
059    /**
060     * EXAMPLE:
061     * <code><pre class="prettyprint lang-java">assertThat(caughtException(), hasMessage("Index: 9, Size: 9"));</pre></code>
062     * 
063     * @param <T>
064     *            the exception subclass
065     * @param expectedMessage
066     *            the expected exception message
067     * @return Returns a matcher that matches an exception if it has the given
068     *         message.
069     */
070    public static <T extends Exception> org.hamcrest.Matcher<T> hasMessage(
071            String expectedMessage) {
072        return new ExceptionMessageMatcher<T>(expectedMessage);
073    }
074
075    /**
076     * EXAMPLES:
077     * <code><pre class="prettyprint lang-java">assertThat(caughtException(), hasMessageThat(is("Index: 9, Size: 9")));
078assertThat(caughtException(), hasMessageThat(containsString("Index: 9"))); // using JUnitMatchers
079assertThat(caughtException(), hasMessageThat(containsPattern("Index: \\d+"))); // using Mockito's Find</pre></code>
080     * 
081     * @param <T>
082     *            the exception subclass
083     * @param stringMatcher
084     *            a string matcher
085     * @return Returns a matcher that matches an exception if the given string
086     *         matcher matches the exception message.
087     */
088    public static <T extends Exception> org.hamcrest.Matcher<T> hasMessageThat(
089            Matcher<String> stringMatcher) {
090        return new ExceptionMessageMatcher<T>(stringMatcher);
091    }
092
093    /**
094     * EXAMPLE:
095     * <code><pre class="prettyprint lang-java">assertThat(caughtException(), hasNoCause());</pre></code>
096     * 
097     * @param <T>
098     *            the exception subclass
099     * @return Returns a matcher that matches the exception if it does not have
100     *         a {@link Throwable#getCause() cause}.
101     */
102    public static <T extends Exception> org.hamcrest.Matcher<T> hasNoCause() {
103        return new ExceptionNoCauseMatcher<T>();
104    }
105
106}