001    /*
002     * Created on Mar 19, 2007
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
005     * in compliance with the License. You may obtain a copy of the License at
006     *
007     * http://www.apache.org/licenses/LICENSE-2.0
008     *
009     * Unless required by applicable law or agreed to in writing, software distributed under the License
010     * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
011     * or implied. See the License for the specific language governing permissions and limitations under
012     * the License.
013     *
014     * Copyright @2007-2009 the original author or authors.
015     */
016    package org.fest.assertions;
017    
018    import static org.fest.assertions.ComparisonFailureFactory.comparisonFailure;
019    import static org.fest.assertions.ErrorMessages.unexpectedEqual;
020    import static org.fest.assertions.ErrorMessages.unexpectedNotEqual;
021    import static org.fest.assertions.Formatting.*;
022    import static org.fest.util.Arrays.array;
023    import static org.fest.util.Objects.areEqual;
024    
025    /**
026     * Understands failure methods.
027     *
028     * @author Alex Ruiz
029     * @author Yvonne Wang
030     */
031    public final class Fail {
032    
033      /**
034       * Fails with no message.
035       * @throws AssertionError without any message.
036       */
037      public static void fail() {
038        fail(null);
039      }
040    
041      /**
042       * Throws an <code>{@link AssertionError}</code> if the given objects are equal.
043       * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
044       * custom message) is not <code>null</code>.
045       * @param descriptionOfActual the description of the actual value.
046       * @param actual the actual object.
047       * @param other the object to compare to.
048       * @throws AssertionError if the given objects are equal.
049       * @since 1.2
050       */
051      protected static void failIfEqual(String customErrorMessage, Description descriptionOfActual, Object actual, Object other) {
052        if (!areEqual(actual, other)) return;
053        failWithMessage(customErrorMessage);
054        fail(format(descriptionOfActual, unexpectedEqual(actual, other)));
055      }
056    
057      /**
058       * Throws an <code>{@link AssertionError}</code> if 'actual' is not equal to 'expected'. If JUnit 4 (or greater) is
059       * in the classpath, this method will throw a <code>ComparisonFailure</code> instead. More details about this feature
060       * can be found <a href="http://docs.codehaus.org/display/FEST/JUnit-Specific+Features">here</a>.
061       * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
062       * custom message) is not <code>null</code>.
063       * @param descriptionOfActual the description of the actual value.
064       * @param actual the actual object.
065       * @param expected the expected object.
066       * @throws AssertionError if the given objects are not equal.
067       * @since 1.2
068       */
069      protected static void failIfNotEqual(String customErrorMessage, Description descriptionOfActual, Object actual, Object expected) {
070        if (areEqual(actual, expected)) return;
071        failWithMessage(customErrorMessage);
072        failWhenNotEqual(descriptionOfActual, actual, expected);
073      }
074    
075      private static void failWhenNotEqual(Description description, Object actual, Object expected) {
076        AssertionError comparisonFailure = comparisonFailure(valueOf(description), expected, actual);
077        if (comparisonFailure != null) throw comparisonFailure;
078        fail(format(description, unexpectedNotEqual(actual, expected)));
079      }
080    
081      /**
082       * Throws an <code>{@link AssertionError}</code> if the given object is <code>null</code>.
083       * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
084       * custom message) is not <code>null</code>.
085       * @param description the description of the given object.
086       * @param o the given object.
087       * @throws AssertionError if the given object is <code>null</code>.
088       * @since 1.2
089       */
090      protected static void failIfNull(String customErrorMessage, Description description, Object o) {
091        if (o != null) return;
092        failWithMessage(customErrorMessage);
093        fail(description, array("expecting a non-null object, but it was null"));
094      }
095    
096      /**
097       * Throws an <code>{@link AssertionError}</code> if the given object is not <code>null</code>.
098       * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
099       * custom message) is not <code>null</code>.
100       * @param description the description of the given object.
101       * @param o the given object.
102       * @throws AssertionError if the given object is not <code>null</code>.
103       * @since 1.2
104       */
105      protected static void failIfNotNull(String customErrorMessage, Description description, Object o) {
106        if (o == null) return;
107        failWithMessage(customErrorMessage);
108        fail(description, array(inBrackets(o), " should be null"));
109      }
110    
111      /**
112       * Throws an <code>{@link AssertionError}</code> if the given objects are the same.
113       * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
114       * custom message) is not <code>null</code>.
115       * @param descriptionOfActual the description of the actual value.
116       * @param actual the actual object.
117       * @param other the object to compare to.
118       * @throws AssertionError if the given objects are the same.
119       * @since 1.2
120       */
121      protected static void failIfSame(String customErrorMessage, Description descriptionOfActual, Object actual, Object other) {
122        if (actual != other) return;
123        failWithMessage(customErrorMessage);
124        fail(descriptionOfActual, array("given objects are same:", inBrackets(actual)));
125      }
126    
127      /**
128       * Throws an <code>{@link AssertionError}</code> if the given objects are not the same.
129       * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
130       * custom message) is not <code>null</code>.
131       * @param descriptionOfActual the description of the actual value.
132       * @param actual the actual object.
133       * @param other the object to compare to.
134       * @throws AssertionError if the given objects are not the same.
135       * @since 1.2
136       */
137      protected static void failIfNotSame(String customErrorMessage, Description descriptionOfActual, Object actual, Object other) {
138        if (actual == other) return;
139        failWithMessage(customErrorMessage);
140        fail(descriptionOfActual,
141            array("expected same instance but found:", inBrackets(actual), " and:", inBrackets(other)));
142      }
143    
144      private static void fail(Description description, Object[] message) {
145        throw failure(createMessageFrom(description, message));
146      }
147    
148      /**
149       * Throws an <code>{@link AssertionError}</code> only if the given custom message is not <code>null</code>.
150       * @param customErrorMessage the custom error message.
151       * @throws AssertionError only if the custom error message is not <code>null</code>.
152       * @since 1.2
153       */
154      protected static void failWithMessage(String customErrorMessage) {
155        if (customErrorMessage != null) fail(customErrorMessage);
156      }
157    
158      /**
159       * Throws an <code>{@link AssertionError}</code> only if the given custom message is not <code>null</code>.
160       * @param customErrorMessage the custom error message.
161       * @param realCause cause of the error.
162       * @throws AssertionError only if the custom error message is not <code>null</code>.
163       * @since 1.2
164       */
165      protected static void failWithMessage(String customErrorMessage, Throwable realCause) {
166        if (customErrorMessage != null) fail(customErrorMessage, realCause);
167      }
168    
169      /**
170       * Throws an <code>{@link AssertionError}</code> with the given message and with the <code>{@link Throwable}</code>
171       * that caused the failure.
172       * @param description the description of the failed assertion. It can be <code>null</code>.
173       * @param realCause cause of the error.
174       */
175      public static void fail(String description, Throwable realCause) {
176        AssertionError error = failure(description);
177        error.initCause(realCause);
178        throw error;
179      }
180    
181      /**
182       * Fails with the given message.
183       * <p>
184       * <strong>Note:</strong> This method appears to return <code>{@link AssertionError}</code>, but it is really not the
185       * case, since the exception is thrown and not returned. In version 2.0 the return type of this method will change
186       * to <code>void</code>. Since we cannot create an overloaded version with return type <code>void</code>, we cannot
187       * deprecate this method. Please pretend this method does not return anything :)
188       * </p>
189       * @param message error message.
190       * @return the thrown <code>AssertionError</code>.
191       * @throws AssertionError with the given message.
192       * @see #failure(String)
193       */
194      public static AssertionError fail(String message) {
195        // TODO in 2.0: change return type to 'void'
196        throw failure(message);
197      }
198    
199      /**
200       * Creates a <code>{@link AssertionError}</code> with the given message.
201       * @param message the message of the exception to create.
202       * @return the created exception.
203       * @since 1.2
204       */
205      public static AssertionError failure(String message) {
206        return new AssertionError(message);
207      }
208    
209      /**
210       * This constructor is protected to make it possible to subclass this class. Since all its methods are static, there
211       * is no point on creating a new instance of it.
212       */
213      protected Fail() {}
214    }