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 }