001 /*
002 * Created on Oct 10, 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.Fail.failWithMessage;
019 import static org.fest.assertions.Formatting.*;
020
021 /**
022 * Base class for all assertion classes.
023 *
024 * @author Yvonne Wang
025 * @author Alex Ruiz
026 */
027 public abstract class Assert {
028
029 private Description description;
030 private String errorMessage;
031
032 /**
033 * Returns the description of the actual value in this assertion.
034 * @return the description of the actual value in this assertion.
035 */
036 public final String description() {
037 return valueOf(description);
038 }
039
040 /**
041 * Sets the description of the actual value, to be used in as message of any <code>{@link AssertionError}</code>
042 * thrown when an assertion fails.
043 * @param d the new description.
044 */
045 protected final void description(String d) {
046 description(new BasicDescription(d));
047 }
048
049 /**
050 * Sets the description of the actual value, to be used in as message of any <code>{@link AssertionError}</code>
051 * thrown when an assertion fails.
052 * @param d the new description.
053 */
054 protected final void description(Description d) {
055 this.description = d;
056 }
057
058 /**
059 * Returns the description of the actual value in this assertion.
060 * @return the description of the actual value in this assertion.
061 * @since 1.2
062 */
063 protected final Description rawDescription() {
064 return description;
065 }
066
067 /**
068 * Returns the given message formatted as follows:
069 * <pre>
070 * [assertion description] given message.
071 * </pre>
072 * @param message the message to format.
073 * @return the formatted message.
074 */
075 protected final String formattedErrorMessage(String message) {
076 return format(description, message);
077 }
078
079 /**
080 * Specifies the message to use in case of a failure, replacing the default one.
081 * @param message the new error message.
082 */
083 protected final void replaceDefaultErrorMessagesWith(String message) {
084 errorMessage = message;
085 }
086
087 /**
088 * Returns the message to use when a failure occurs, if one has been specified.
089 * @return the message to use when a failure occurs, or {@code null} if none has been specified.
090 */
091 protected final String customErrorMessage() {
092 return errorMessage;
093 }
094
095 /**
096 * Throws an <code>{@link AssertionError}</code> only if the the custom message in this assertion object is not
097 * {@code null}.
098 * @throws AssertionError only if the custom error message in this assertion object is not {@code null}.
099 * @since 1.2
100 */
101 protected final void failIfCustomMessageIsSet() {
102 failWithMessage(customErrorMessage());
103 }
104
105 /**
106 * Throws an <code>{@link AssertionError}</code> only if the the custom message in this assertion object is not
107 * {@code null}.
108 * @param realCause cause of the error.
109 * @throws AssertionError only if the custom error message in this assertion object is not {@code null}.
110 * @since 1.2
111 */
112 protected final void failIfCustomMessageIsSet(Throwable realCause) {
113 failWithMessage(customErrorMessage(), realCause);
114 }
115
116 /**
117 * Fails by throwing an <code>{@link AssertionError}</code>.
118 * @param reason the reason for the failure, used as the message for the thrown exception.
119 * @param cause the root cause of the failure, included in the thrown exception.
120 */
121 protected final void fail(String reason, Throwable cause) {
122 Fail.fail(formattedErrorMessage(reason), cause);
123 }
124
125 /**
126 * Fails by throwing an <code>{@link AssertionError}</code>.
127 * <p>
128 * <strong>Note:</strong> This method appears to return <code>{@link AssertionError}</code>, but it is really not the
129 * case, since the exception is thrown and not returned. In version 2.0 the return type of this method will change
130 * to <code>void</code>. Since we cannot create an overloaded version with return type <code>void</code>, we cannot
131 * deprecate this method. Please pretend this method does not return anything :)
132 * </p>
133 * @param reason the reason for the failure, used as the message for the thrown exception.
134 * @return the thrown <code>AssertionError</code>.
135 * @throws AssertionError using the given reason as the message.
136 * @see #failure(String)
137 */
138 protected final AssertionError fail(String reason) {
139 // TODO in 2.0: change return type to 'void'
140 throw failure(reason);
141 }
142
143 /**
144 * Creates an <code>{@link AssertionError}</code>, adding the description of the actual value to the given message.
145 * @param reason the reason for the failure, used as the message for the thrown exception.
146 * @return the created exception.
147 */
148 protected final AssertionError failure(String reason) {
149 return Fail.failure(formattedErrorMessage(reason));
150 }
151
152 /**
153 * Throws <code>{@link UnsupportedOperationException}</code> if called. It is easy to accidentally call
154 * <code>{@link #equals(Object)}</code> instead of <code>isEqualTo</code>.
155 * @throws UnsupportedOperationException if this method is called.
156 */
157 @Override public final boolean equals(Object obj) {
158 throw new UnsupportedOperationException("'equals' is not supported...maybe you intended to call 'isEqualTo'");
159 }
160
161 /**
162 * Always returns 1.
163 * @return 1.
164 */
165 @Override public final int hashCode() { return 1; }
166 }