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