001    /*
002     * Created on Dec 26, 2006
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 @2006-2009 the original author or authors.
015     */
016    package org.fest.assertions;
017    
018    import static org.fest.assertions.Formatting.inBrackets;
019    import static org.fest.util.Strings.concat;
020    
021    import org.fest.util.Strings;
022    
023    /**
024     * Understands assertion methods for <code>String</code>s. To create a new instance of this class use the
025     * method <code>{@link Assertions#assertThat(String)}</code>.
026     *
027     * @author Yvonne Wang
028     * @author David DIDIER
029     */
030    public class StringAssert extends GroupAssert<String> {
031    
032      /**
033       * Creates a new </code>{@link StringAssert}</code>.
034       * @param actual the target to verify.
035       */
036      protected StringAssert(String actual) {
037        super(actual);
038      }
039    
040      /** {@inheritDoc} */
041      public StringAssert as(String description) {
042        description(description);
043        return this;
044      }
045    
046      /** {@inheritDoc} */
047      public StringAssert describedAs(String description) {
048        return as(description);
049      }
050    
051      /** {@inheritDoc} */
052      public StringAssert as(Description description) {
053        description(description);
054        return this;
055      }
056    
057      /** {@inheritDoc} */
058      public StringAssert describedAs(Description description) {
059        return as(description);
060      }
061    
062      /**
063       * Verifies that the actual <code>String</code> satisfies the given condition.
064       * @param condition the given condition.
065       * @return this assertion object.
066       * @throws NullPointerException if the given condition is <code>null</code>.
067       * @throws AssertionError if the actual <code>String</code> does not satisfy the given condition.
068       * @see #is(Condition)
069       */
070      public StringAssert satisfies(Condition<String> condition) {
071        assertSatisfies(condition);
072        return this;
073      }
074    
075      /**
076       * Verifies that the actual <code>String</code> does not satisfy the given condition.
077       * @param condition the given condition.
078       * @return this assertion object.
079       * @throws NullPointerException if the given condition is <code>null</code>.
080       * @throws AssertionError if the actual <code>String</code> satisfies the given condition.
081       * @see #isNot(Condition)
082       */
083      public StringAssert doesNotSatisfy(Condition<String> condition) {
084        assertDoesNotSatisfy(condition);
085        return this;
086      }
087    
088      /**
089       * Alias for <code>{@link #satisfies(Condition)}</code>.
090       * @param condition the given condition.
091       * @return this assertion object.
092       * @throws NullPointerException if the given condition is <code>null</code>.
093       * @throws AssertionError if the actual <code>String</code> does not satisfy the given condition.
094       * @since 1.2
095       */
096      public StringAssert is(Condition<String> condition) {
097        assertIs(condition);
098        return this;
099      }
100    
101      /**
102       * Alias for <code>{@link #doesNotSatisfy(Condition)}</code>.
103       * @param condition the given condition.
104       * @return this assertion object.
105       * @throws NullPointerException if the given condition is <code>null</code>.
106       * @throws AssertionError if the actual <code>String</code> satisfies the given condition.
107       * @since 1.2
108       */
109      public StringAssert isNot(Condition<String> condition) {
110        assertIsNot(condition);
111        return this;
112      }
113    
114      /**
115       * Verifies that the actual <code>String</code> is empty (not <code>null</code> with zero characters.)
116       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
117       * @throws AssertionError if the actual <code>String</code> is not empty.
118       */
119      public void isEmpty() {
120        isNotNull();
121        if (Strings.isEmpty(actual)) return;
122        failIfCustomMessageIsSet();
123        fail(concat("expecting empty String but was:", inBrackets(actual)));
124      }
125    
126      /**
127       * Verifies that the actual <code>String</code> is <code>null</code> or empty.
128       * @throws AssertionError if the actual <code>String</code> is not <code>null</code> or not empty.
129       */
130      public final void isNullOrEmpty() {
131        if (Strings.isEmpty(actual)) return;
132        failIfCustomMessageIsSet();
133        fail(concat("expecting a null or empty String, but was:", inBrackets(actual)));
134      }
135    
136      /**
137       * Verifies that the actual <code>String</code> contains at least on character.
138       * @return this assertion object.
139       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
140       * @throws AssertionError if the actual <code>String</code> is <code>null</code> or empty.
141       */
142      public StringAssert isNotEmpty() {
143        isNotNull();
144        if (!Strings.isEmpty(actual)) return this;
145        failIfCustomMessageIsSet();
146        throw failure(concat("expecting a non-empty String, but it was empty"));
147      }
148    
149      /**
150       * Verifies that the actual <code>String</code> is equal to the given one.
151       * @param expected the given <code>String</code> to compare the actual <code>String</code> to.
152       * @return this assertion object.
153       * @throws AssertionError if the actual <code>String</code> is not equal to the given one.
154       */
155      public StringAssert isEqualTo(String expected) {
156        assertEqualTo(expected);
157        return this;
158      }
159    
160      /**
161       * Verifies that the actual <code>String</code> is not equal to the given one.
162       * @param other the given <code>String</code> to compare the actual <code>String</code> to.
163       * @return this assertion object.
164       * @throws AssertionError if the actual <code>String</code> is equal to the given one.
165       */
166      public StringAssert isNotEqualTo(String other) {
167        assertNotEqualTo(other);
168        return this;
169      }
170    
171      /**
172       * Verifies that the actual <code>String</code> is not <code>null</code>.
173       * @return this assertion object.
174       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
175       */
176      public StringAssert isNotNull() {
177        assertNotNull();
178        return this;
179      }
180    
181      /**
182       * Verifies that the actual <code>String</code> is not the same as the given one.
183       * @param other the given <code>String</code> to compare the actual <code>String</code> to.
184       * @return this assertion object.
185       * @throws AssertionError if the actual <code>String</code> is the same as the given one.
186       */
187      public StringAssert isNotSameAs(String other) {
188        assertNotSameAs(other);
189        return this;
190      }
191    
192      /**
193       * Verifies that the actual <code>String</code> is the same as the given one.
194       * @param expected the given <code>String</code> to compare the actual <code>String</code> to.
195       * @return this assertion object.
196       * @throws AssertionError if the actual <code>String</code> is not the same as the given one.
197       */
198      public StringAssert isSameAs(String expected) {
199        assertSameAs(expected);
200        return this;
201      }
202    
203      /**
204       * Verifies that the number of characters in the actual <code>String</code> is equal to the given one.
205       * @param expected the expected number of characters in the actual <code>String</code>.
206       * @return this assertion object.
207       * @throws AssertionError if the number of characters of the actual <code>String</code> is not equal to the given
208       * one.
209       */
210      public StringAssert hasSize(int expected) {
211        int actualSize = actualGroupSize();
212        if (actualSize == expected) return this;
213        failIfCustomMessageIsSet();
214        throw failure(concat("expected size:", inBrackets(expected)," but was:", inBrackets(actualSize), " for String:", actual()));
215      }
216    
217      /**
218       * Returns the number of elements in the actual <code>String</code>.
219       * @return the number of elements in the actual <code>String</code>.
220       */
221      protected int actualGroupSize() {
222        isNotNull();
223        return actual.length();
224      }
225    
226      /**
227       * Verifies that the actual <code>String</code> contains the given one.
228       * @param expected the given <code>String</code> expected to be contained in the actual one.
229       * @return this assertion object.
230       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
231       * @throws AssertionError if the actual <code>String</code> does not contain the given one.
232       */
233      public StringAssert contains(String expected) {
234        isNotNull();
235        if (actual.indexOf(expected) != -1) return this;
236        failIfCustomMessageIsSet();
237        throw failure(concat(actual(), " should contain the String:", inBrackets(expected)));
238      }
239    
240      /**
241       * Verifies that the actual <code>String</code> ends with the given one.
242       * @param expected the given <code>String</code> expected to be at the end of the actual one.
243       * @return this assertion object.
244       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
245       * @throws AssertionError if the actual <code>String</code> does not end with the given one.
246       */
247      public StringAssert endsWith(String expected) {
248        isNotNull();
249        if (actual.endsWith(expected)) return this;
250        failIfCustomMessageIsSet();
251        throw failure(concat(actual(), " should end with:", inBrackets(expected)));
252      }
253    
254      /**
255       * Verifies that the actual <code>String</code> starts with the given one.
256       * @param expected the given <code>String</code> expected to be at the beginning of the actual one.
257       * @return this assertion object.
258       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
259       * @throws AssertionError if the actual <code>String</code> does not start with the given one.
260       */
261      public StringAssert startsWith(String expected) {
262        isNotNull();
263        if (actual.startsWith(expected)) return this;
264        failIfCustomMessageIsSet();
265        throw failure(concat(actual(), " should start with:", inBrackets(expected)));
266      }
267    
268      /**
269       * Verifies that the actual <code>String</code> does not contains the given one.
270       * @param s the given <code>String</code> expected not to be contained in the actual one.
271       * @return this assertion object.
272       * @throws AssertionError if the actual <code>String</code> is <code>null</code>.
273       * @throws AssertionError if the actual <code>String</code> does contain the given one.
274       */
275      public StringAssert excludes(String s) {
276        isNotNull();
277        if (actual.indexOf(s) == -1) return this;
278        failIfCustomMessageIsSet();
279        throw failure(concat(actual(), " should not contain the String:", inBrackets(s)));
280      }
281    
282      /**
283       * Verifies that the actual <code>String</code> matches the given one.
284       * @param regex the given regular expression expected to be matched by the actual one.
285       * @return this assertion object.
286       * @throws AssertionError if the actual <code>String</code> does not match the given regular expression.
287       */
288      public StringAssert matches(String regex) {
289        isNotNull();
290        if (actual.matches(regex)) return this;
291        failIfCustomMessageIsSet();
292        throw failure(concat(actual(), " should match the regular expression:", inBrackets(regex)));
293      }
294    
295      /**
296       * Verifies that the actual <code>String</code> does not match the given one.
297       * @param regex the given regular expression expected not to be matched by the actual one.
298       * @return this assertion object.
299       * @throws AssertionError if the actual <code>String</code> matches the given regular expression.
300       */
301      public StringAssert doesNotMatch(String regex) {
302        isNotNull();
303        if (!actual.matches(regex)) return this;
304        failIfCustomMessageIsSet();
305        throw failure(concat(actual(), " should not match the regular expression:", inBrackets(regex)));
306      }
307    
308      private String actual() {
309        return inBrackets(actual);
310      }
311    
312      /** {@inheritDoc} */
313      public StringAssert overridingErrorMessage(String message) {
314        replaceDefaultErrorMessagesWith(message);
315        return this;
316      }
317    }