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 }