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 com.googlecode.catchexception.CatchException;
019import com.googlecode.catchexception.ExceptionNotThrownAssertionError;
020
021/**
022 * Supports <a
023 * href="http://en.wikipedia.org/wiki/Behavior_Driven_Development">BDD</a>-like
024 * approach to catch and verify exceptions (<i>given/when/then</i>).
025 * <p>
026 * EXAMPLE:
027 * <code><pre class="prettyprint lang-java">import static org.assertj.core.api.BDDAssertions.then;
028
029// given an empty list
030List myList = new ArrayList();
031
032// when we try to get the first element of the list
033when(myList).get(1);
034
035// then we expect an IndexOutOfBoundsException
036then(caughtException())
037        .isInstanceOf(IndexOutOfBoundsException.class)
038        .hasMessage("Index: 1, Size: 0") 
039        .hasNoCause();
040        
041// then we expect an IndexOutOfBoundsException (alternatively)
042thenThrown(IndexOutOfBoundsException.class);
043</pre></code>
044 * <p>
045 * The Method {@link org.assertj.core.api.BDDAssertions#then(Throwable)} is originated from <a
046 * href="http://assertj.org">AssertJ</a>. You can also use method <code>assertThat</code>:
047 * <code><pre class="prettyprint lang-java">// import static org.assertj.core.api.Assertions.assertThat;
048
049// then we expect an IndexOutOfBoundsException
050assertThat(caughtException())
051        .isInstanceOf(IndexOutOfBoundsException.class)
052        .hasMessage("Index: 1, Size: 0") 
053        .hasMessageStartingWith("Index: 1") 
054        .hasMessageEndingWith("Size: 0") 
055        .hasMessageContaining("Size") 
056        .hasNoCause();
057</pre></code>
058 * 
059 * @author rwoo
060 * @author mariuszs
061 * @since 1.3.0
062 */
063public class BDDCatchException {
064
065    /**
066     * @param <T>
067     *            The type of the given <code>obj</code>.
068     *
069     * @param obj
070     *            The instance that shall be proxied. Must not be
071     *            <code>null</code>.
072     * @return Returns a proxy for the given object. The proxy catches
073     *         exceptions of the given type when a method on the proxy is
074     *         called.
075     * @see com.googlecode.catchexception.CatchException#catchException(Object)
076     */
077    public static <T> T when(T obj) {
078        return CatchException.catchException(obj);
079    }
080
081    /**
082     * Throws an assertion if no exception is thrown or if an exception of an
083     * unexpected type is thrown.
084     * <p>
085     * EXAMPLE:
086     * <code><pre class="prettyprint lang-java">// given a list with nine members
087List myList = Arrays.asList(1, 2, 3, 4, 5, 6, 7, 8, 9);
088
089// when we try to get the 500th member of the fellowship
090when(myList).get(500);
091
092// then we expect an IndexOutOfBoundsException
093thenThrown(IndexOutOfBoundsException.class);
094</pre></code>
095     * 
096     * @param actualExceptionClazz
097     *            the expected type of the caught exception.
098     */
099    @SuppressWarnings({ "unchecked", "rawtypes" })
100    public static void thenThrown(Class actualExceptionClazz) {
101        Exception e = CatchException.caughtException();
102        if (e == null) {
103            // no exception caught -> assertion failed
104            throw new ExceptionNotThrownAssertionError(actualExceptionClazz);
105        } else if (!actualExceptionClazz.isAssignableFrom(CatchException
106                .caughtException().getClass())) {
107            // caught exception is of wrong type -> assertion failed
108            throw new ExceptionNotThrownAssertionError(actualExceptionClazz, e);
109        } else {
110            // the caught exception is of the expected type -> nothing to do :-)
111        }
112    }
113
114}