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-2011 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.*;
020 import static org.fest.assertions.Formatting.*;
021 import static org.fest.util.Arrays.array;
022 import static org.fest.util.Objects.areEqual;
023
024 /**
025 * Common failures.
026 *
027 * @author Alex Ruiz
028 * @author Yvonne Wang
029 */
030 public final class Fail {
031
032 /**
033 * Fails with no message.
034 * @throws AssertionError without any message.
035 */
036 public static void fail() {
037 fail(null);
038 }
039
040 /**
041 * Throws an <code>{@link AssertionError}</code> if the given objects are equal.
042 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
043 * custom message) is not {@code null}.
044 * @param descriptionOfActual the description of the actual value.
045 * @param actual the actual object.
046 * @param other the object to compare to.
047 * @throws AssertionError if the given objects are equal.
048 * @since 1.2
049 */
050 protected static void failIfEqual(String customErrorMessage, Description descriptionOfActual, Object actual, Object other) {
051 if (!areEqual(actual, other)) return;
052 failWithMessage(customErrorMessage);
053 fail(format(descriptionOfActual, unexpectedEqual(actual, other)));
054 }
055
056 /**
057 * Throws an <code>{@link AssertionError}</code> if 'actual' is not equal to 'expected'. If JUnit 4 (or greater) is
058 * in the classpath, this method will throw a <code>ComparisonFailure</code> instead. More details about this feature
059 * can be found <a href="http://docs.codehaus.org/display/FEST/JUnit-Specific+Features">here</a>.
060 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
061 * custom message) is not {@code null}.
062 * @param descriptionOfActual the description of the actual value.
063 * @param actual the actual object.
064 * @param expected the expected object.
065 * @throws AssertionError if the given objects are not equal.
066 * @since 1.2
067 */
068 protected static void failIfNotEqual(String customErrorMessage, Description descriptionOfActual, Object actual, Object expected) {
069 if (areEqual(actual, expected)) return;
070 failWithMessage(customErrorMessage);
071 throw comparisonFailed(descriptionOfActual, actual, expected);
072 }
073
074 /**
075 * Returns a <code>{@link AssertionError}</code> describing a comparison failure.
076 * @param description the description of the comparison.
077 * @param actual the actual value.
078 * @param expected the expected value.
079 * @return a {@code AssertionError} describing the comparison failure.
080 * @since 1.3
081 */
082 protected static AssertionError comparisonFailed(Description description, Object actual, Object expected) {
083 AssertionError comparisonFailure = comparisonFailure(valueOf(description), expected, actual);
084 if (comparisonFailure != null) return comparisonFailure;
085 return failure(format(description, unexpectedNotEqual(actual, expected)));
086 }
087
088 /**
089 * Throws an <code>{@link AssertionError}</code> if the actual value is {@code null}.
090 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
091 * custom message) is not {@code null}.
092 * @param description the description of the actual value.
093 * @param actual the actual value.
094 * @throws AssertionError if the actual value is {@code null}.
095 * @since 1.3
096 */
097 protected static void failIfActualIsNull(String customErrorMessage, Description description, Object actual) {
098 if (actual != null) return;
099 failWithMessage(customErrorMessage);
100 fail(description, array("expecting actual value not to be null"));
101 }
102
103 /**
104 * Throws an <code>{@link AssertionError}</code> if the given object is {@code null}.
105 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
106 * custom message) is not {@code null}.
107 * @param description the description of the given object.
108 * @param o the given object.
109 * @throws AssertionError if the given object is {@code null}.
110 * @since 1.2
111 */
112 protected static void failIfNull(String customErrorMessage, Description description, Object o) {
113 if (o != null) return;
114 failWithMessage(customErrorMessage);
115 fail(description, array("expecting a non-null object, but it was null"));
116 }
117
118 /**
119 * Throws an <code>{@link AssertionError}</code> if the given object is not {@code null}.
120 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
121 * custom message) is not {@code null}.
122 * @param description the description of the given object.
123 * @param o the given object.
124 * @throws AssertionError if the given object is not {@code null}.
125 * @since 1.2
126 */
127 protected static void failIfNotNull(String customErrorMessage, Description description, Object o) {
128 if (o == null) return;
129 failWithMessage(customErrorMessage);
130 fail(description, array(inBrackets(o), " should be null"));
131 }
132
133 /**
134 * Throws an <code>{@link AssertionError}</code> if the given objects are the same.
135 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
136 * custom message) is not {@code null}.
137 * @param descriptionOfActual the description of the actual value.
138 * @param actual the actual object.
139 * @param other the object to compare to.
140 * @throws AssertionError if the given objects are the same.
141 * @since 1.2
142 */
143 protected static void failIfSame(String customErrorMessage, Description descriptionOfActual, Object actual, Object other) {
144 if (actual != other) return;
145 failWithMessage(customErrorMessage);
146 fail(descriptionOfActual, array("given objects are same:", inBrackets(actual)));
147 }
148
149 /**
150 * Throws an <code>{@link AssertionError}</code> if the given objects are not the same.
151 * @param customErrorMessage any custom error message. This message will replace the default one only if it (the
152 * custom message) is not {@code null}.
153 * @param descriptionOfActual the description of the actual value.
154 * @param actual the actual object.
155 * @param other the object to compare to.
156 * @throws AssertionError if the given objects are not the same.
157 * @since 1.2
158 */
159 protected static void failIfNotSame(String customErrorMessage, Description descriptionOfActual, Object actual, Object other) {
160 if (actual == other) return;
161 failWithMessage(customErrorMessage);
162 fail(descriptionOfActual,
163 array("expected same instance but found:", inBrackets(actual), " and:", inBrackets(other)));
164 }
165
166 private static void fail(Description description, Object[] message) {
167 throw failure(createMessageFrom(description, message));
168 }
169
170 /**
171 * Throws an <code>{@link AssertionError}</code> only if the given custom message is not {@code null}.
172 * @param customErrorMessage the custom error message.
173 * @throws AssertionError only if the custom error message is not {@code null}.
174 * @since 1.2
175 */
176 protected static void failWithMessage(String customErrorMessage) {
177 if (customErrorMessage != null) fail(customErrorMessage);
178 }
179
180 /**
181 * Throws an <code>{@link AssertionError}</code> only if the given custom message is not {@code null}.
182 * @param customErrorMessage the custom error message.
183 * @param realCause cause of the error.
184 * @throws AssertionError only if the custom error message is not {@code null}.
185 * @since 1.2
186 */
187 protected static void failWithMessage(String customErrorMessage, Throwable realCause) {
188 if (customErrorMessage != null) fail(customErrorMessage, realCause);
189 }
190
191 /**
192 * Throws an <code>{@link AssertionError}</code> with the given message and with the <code>{@link Throwable}</code>
193 * that caused the failure.
194 * @param description the description of the failed assertion. It can be {@code null}.
195 * @param realCause cause of the error.
196 */
197 public static void fail(String description, Throwable realCause) {
198 AssertionError error = failure(description);
199 error.initCause(realCause);
200 throw error;
201 }
202
203 /**
204 * Fails with the given message.
205 * <p>
206 * <strong>Note:</strong> This method appears to return <code>{@link AssertionError}</code>, but it is really not the
207 * case, since the exception is thrown and not returned. In version 2.0 the return type of this method will change
208 * to <code>void</code>. Since we cannot create an overloaded version with return type <code>void</code>, we cannot
209 * deprecate this method. Please pretend this method does not return anything :)
210 * </p>
211 * @param message error message.
212 * @return the thrown <code>AssertionError</code>.
213 * @throws AssertionError with the given message.
214 * @see #failure(String)
215 */
216 public static AssertionError fail(String message) {
217 // TODO in 2.0: change return type to 'void'
218 throw failure(message);
219 }
220
221 /**
222 * Creates a <code>{@link AssertionError}</code> with the given message.
223 * @param message the message of the exception to create.
224 * @return the created exception.
225 * @since 1.2
226 */
227 public static AssertionError failure(String message) {
228 return new AssertionError(message);
229 }
230
231 /**
232 * This constructor is protected to make it possible to subclass this class. Since all its methods are static, there
233 * is no point on creating a new instance of it.
234 */
235 protected Fail() {}
236 }