001    /*
002     * Created on Sep 30, 2010
003     * 
004     * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
005     * 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 is distributed on
010     * an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
011     * specific language governing permissions and limitations under the License.
012     * 
013     * Copyright @2010-2011 the original author or authors.
014     */
015    package org.fest.assertions.api;
016    
017    import java.awt.image.BufferedImage;
018    import java.io.File;
019    import java.io.InputStream;
020    import java.math.BigDecimal;
021    import java.util.Collection;
022    import java.util.Date;
023    import java.util.List;
024    import java.util.Map;
025    
026    import org.fest.assertions.api.filter.Filters;
027    import org.fest.assertions.condition.AnyOf;
028    import org.fest.assertions.core.Condition;
029    import org.fest.assertions.data.Index;
030    import org.fest.assertions.data.MapEntry;
031    import org.fest.assertions.data.Offset;
032    import org.fest.assertions.groups.Properties;
033    import org.fest.assertions.util.ImageReader;
034    
035    /**
036     * Entry point for assertion methods for different data types. Each method in this class is a static factory for the
037     * type-specific assertion objects. The purpose of this class is to make test code more readable.
038     * <p>
039     * For example:
040     * 
041     * <pre>
042     * int removed = employees.removeFired();
043     * {@link Assertions#assertThat(int) assertThat}(removed).{@link IntegerAssert#isZero isZero}();
044     *
045     * List&lt;Employee&gt; newEmployees = employees.hired(TODAY);
046     * {@link Assertions#assertThat(Iterable) assertThat}(newEmployees).{@link IterableAssert#hasSize(int) hasSize}(6);
047     * </pre>
048     * </p>
049     * 
050     * @author Alex Ruiz
051     * @author Yvonne Wang
052     * @author David DIDIER
053     * @author Ted Young
054     * @author Joel Costigliola
055     * @author Matthieu Baechler
056     * @author Mikhail Mazursky
057     */
058    public class Assertions {
059    
060      /**
061       * Creates a new instance of <code>{@link BigDecimalAssert}</code>.
062       * @param actual the actual value.
063       * @return the created assertion object.
064       */
065      public static BigDecimalAssert assertThat(BigDecimal actual) {
066        return new BigDecimalAssert(actual);
067      }
068    
069      /**
070       * Creates a new instance of <code>{@link BooleanAssert}</code>.
071       * @param actual the actual value.
072       * @return the created assertion object.
073       */
074      public static BooleanAssert assertThat(boolean actual) {
075        return new BooleanAssert(actual);
076      }
077    
078      /**
079       * Creates a new instance of <code>{@link BooleanAssert}</code>.
080       * @param actual the actual value.
081       * @return the created assertion object.
082       */
083      public static BooleanAssert assertThat(Boolean actual) {
084        return new BooleanAssert(actual);
085      }
086    
087      /**
088       * Creates a new instance of <code>{@link BooleanArrayAssert}</code>.
089       * @param actual the actual value.
090       * @return the created assertion object.
091       */
092      public static BooleanArrayAssert assertThat(boolean[] actual) {
093        return new BooleanArrayAssert(actual);
094      }
095    
096      /**
097       * Creates a new instance of <code>{@link ImageAssert}</code>. To read an image from the file system use
098       * <code>{@link ImageReader#readImageFrom(String)}</code>.
099       * @param actual the actual value.
100       * @return the created assertion object.
101       */
102      public static ImageAssert assertThat(BufferedImage actual) {
103        return new ImageAssert(actual);
104      }
105    
106      /**
107       * Creates a new instance of <code>{@link ByteAssert}</code>.
108       * @param actual the actual value.
109       * @return the created assertion object.
110       */
111      public static ByteAssert assertThat(byte actual) {
112        return new ByteAssert(actual);
113      }
114    
115      /**
116       * Creates a new instance of <code>{@link ByteAssert}</code>.
117       * @param actual the actual value.
118       * @return the created assertion object.
119       */
120      public static ByteAssert assertThat(Byte actual) {
121        return new ByteAssert(actual);
122      }
123    
124      /**
125       * Creates a new instance of <code>{@link ByteArrayAssert}</code>.
126       * @param actual the actual value.
127       * @return the created assertion object.
128       */
129      public static ByteArrayAssert assertThat(byte[] actual) {
130        return new ByteArrayAssert(actual);
131      }
132    
133      /**
134       * Creates a new instance of <code>{@link CharacterAssert}</code>.
135       * @param actual the actual value.
136       * @return the created assertion object.
137       */
138      public static CharacterAssert assertThat(char actual) {
139        return new CharacterAssert(actual);
140      }
141    
142      /**
143       * Creates a new instance of <code>{@link CharArrayAssert}</code>.
144       * @param actual the actual value.
145       * @return the created assertion object.
146       */
147      public static CharArrayAssert assertThat(char[] actual) {
148        return new CharArrayAssert(actual);
149      }
150    
151      /**
152       * Creates a new instance of <code>{@link CharacterAssert}</code>.
153       * @param actual the actual value.
154       * @return the created assertion object.
155       */
156      public static CharacterAssert assertThat(Character actual) {
157        return new CharacterAssert(actual);
158      }
159    
160      /**
161       * Creates a new instance of <code>{@link IterableAssert}</code>.
162       * @param actual the actual value.
163       * @return the created assertion object.
164       */
165      public static <T> IterableAssert<T> assertThat(Iterable<T> actual) {
166        return new IterableAssert<T>(actual);
167      }
168    
169      /**
170       * Creates a new instance of <code>{@link DoubleAssert}</code>.
171       * @param actual the actual value.
172       * @return the created assertion object.
173       */
174      public static DoubleAssert assertThat(double actual) {
175        return new DoubleAssert(actual);
176      }
177    
178      /**
179       * Creates a new instance of <code>{@link DoubleAssert}</code>.
180       * @param actual the actual value.
181       * @return the created assertion object.
182       */
183      public static DoubleAssert assertThat(Double actual) {
184        return new DoubleAssert(actual);
185      }
186    
187      /**
188       * Creates a new instance of <code>{@link DoubleArrayAssert}</code>.
189       * @param actual the actual value.
190       * @return the created assertion object.
191       */
192      public static DoubleArrayAssert assertThat(double[] actual) {
193        return new DoubleArrayAssert(actual);
194      }
195    
196      /**
197       * Creates a new instance of <code>{@link FileAssert}</code>.
198       * @param actual the actual value.
199       * @return the created assertion object.
200       */
201      public static FileAssert assertThat(File actual) {
202        return new FileAssert(actual);
203      }
204    
205      /**
206       * Creates a new instance of <code>{@link InputStreamAssert}</code>.
207       * @param actual the actual value.
208       * @return the created assertion object.
209       */
210      public static InputStreamAssert assertThat(InputStream actual) {
211        return new InputStreamAssert(actual);
212      }
213    
214      /**
215       * Creates a new instance of <code>{@link FloatAssert}</code>.
216       * @param actual the actual value.
217       * @return the created assertion object.
218       */
219      public static FloatAssert assertThat(float actual) {
220        return new FloatAssert(actual);
221      }
222    
223      /**
224       * Creates a new instance of <code>{@link FloatAssert}</code>.
225       * @param actual the actual value.
226       * @return the created assertion object.
227       */
228      public static FloatAssert assertThat(Float actual) {
229        return new FloatAssert(actual);
230      }
231    
232      /**
233       * Creates a new instance of <code>{@link FloatArrayAssert}</code>.
234       * @param actual the actual value.
235       * @return the created assertion object.
236       */
237      public static FloatArrayAssert assertThat(float[] actual) {
238        return new FloatArrayAssert(actual);
239      }
240    
241      /**
242       * Creates a new instance of <code>{@link IntegerAssert}</code>.
243       * @param actual the actual value.
244       * @return the created assertion object.
245       */
246      public static IntegerAssert assertThat(int actual) {
247        return new IntegerAssert(actual);
248      }
249    
250      /**
251       * Creates a new instance of <code>{@link IntArrayAssert}</code>.
252       * @param actual the actual value.
253       * @return the created assertion object.
254       */
255      public static IntArrayAssert assertThat(int[] actual) {
256        return new IntArrayAssert(actual);
257      }
258    
259      /**
260       * Creates a new instance of <code>{@link IntegerAssert}</code>.
261       * @param actual the actual value.
262       * @return the created assertion object.
263       */
264      public static IntegerAssert assertThat(Integer actual) {
265        return new IntegerAssert(actual);
266      }
267    
268      /**
269       * Creates a new instance of <code>{@link ListAssert}</code>.
270       * @param actual the actual value.
271       * @return the created assertion object.
272       */
273      public static <T> ListAssert<T> assertThat(List<T> actual) {
274        return new ListAssert<T>(actual);
275      }
276    
277      /**
278       * Creates a new instance of <code>{@link LongAssert}</code>.
279       * @param actual the actual value.
280       * @return the created assertion object.
281       */
282      public static LongAssert assertThat(long actual) {
283        return new LongAssert(actual);
284      }
285    
286      /**
287       * Creates a new instance of <code>{@link LongAssert}</code>.
288       * @param actual the actual value.
289       * @return the created assertion object.
290       */
291      public static LongAssert assertThat(Long actual) {
292        return new LongAssert(actual);
293      }
294    
295      /**
296       * Creates a new instance of <code>{@link LongArrayAssert}</code>.
297       * @param actual the actual value.
298       * @return the created assertion object.
299       */
300      public static LongArrayAssert assertThat(long[] actual) {
301        return new LongArrayAssert(actual);
302      }
303    
304      /**
305       * Creates a new instance of <code>{@link ObjectAssert}</code>.
306       * @param actual the actual value.
307       * @return the created assertion object.
308       */
309      public static <T> ObjectAssert<T> assertThat(T actual) {
310        return new ObjectAssert<T>(actual);
311      }
312    
313      /**
314       * Creates a new instance of <code>{@link ObjectArrayAssert}</code>.
315       * @param actual the actual value.
316       * @return the created assertion object.
317       */
318      public static <T> ObjectArrayAssert<T> assertThat(T[] actual) {
319        return new ObjectArrayAssert<T>(actual);
320      }
321    
322      /**
323       * Creates a new instance of <code>{@link MapAssert}</code>.
324       * @param actual the actual value.
325       * @return the created assertion object.
326       */
327      public static MapAssert assertThat(Map<?, ?> actual) {
328        return new MapAssert(actual);
329      }
330    
331      /**
332       * Creates a new instance of <code>{@link ShortAssert}</code>.
333       * @param actual the actual value.
334       * @return the created assertion object.
335       */
336      public static ShortAssert assertThat(short actual) {
337        return new ShortAssert(actual);
338      }
339    
340      /**
341       * Creates a new instance of <code>{@link ShortAssert}</code>.
342       * @param actual the actual value.
343       * @return the created assertion object.
344       */
345      public static ShortAssert assertThat(Short actual) {
346        return new ShortAssert(actual);
347      }
348    
349      /**
350       * Creates a new instance of <code>{@link ShortArrayAssert}</code>.
351       * @param actual the actual value.
352       * @return the created assertion object.
353       */
354      public static ShortArrayAssert assertThat(short[] actual) {
355        return new ShortArrayAssert(actual);
356      }
357    
358      /**
359       * Creates a new instance of <code>{@link StringAssert}</code>.
360       * @param actual the actual value.
361       * @return the created assertion object.
362       */
363      public static StringAssert assertThat(String actual) {
364        return new StringAssert(actual);
365      }
366    
367      /**
368       * Creates a new instance of <code>{@link DateAssert}</code>.
369       * @param actual the actual value.
370       * @return the created assertion object.
371       */
372      public static DateAssert assertThat(Date actual) {
373        return new DateAssert(actual);
374      }
375    
376      /**
377       * Creates a new instance of <code>{@link ThrowableAssert}</code>.
378       * @param actual the actual value.
379       * @return the created assertion Throwable.
380       */
381      public static ThrowableAssert assertThat(Throwable actual) {
382        return new ThrowableAssert(actual);
383      }
384    
385      // -------------------------------------------------------------------------------------------------
386      // fail methods : not assertions but here to have a single entry point to all Fest Assert features.
387      // -------------------------------------------------------------------------------------------------
388    
389      /**
390       * Only delegate to {@link Fail#setRemoveFestRelatedElementsFromStackTrace(boolean)} so that Assertions offers a full
391       * feature entry point to all Fest Assert features (but you can use {@link Fail} if you prefer).
392       */
393      public static void setRemoveFestRelatedElementsFromStackTrace(boolean removeFestRelatedElementsFromStackTrace) {
394        Fail.setRemoveFestRelatedElementsFromStackTrace(removeFestRelatedElementsFromStackTrace);
395      }
396    
397      /**
398       * Only delegate to {@link Fail#fail(String)} so that Assertions offers a full feature entry point to all Fest Assert
399       * features (but you can use Fail if you prefer).
400       */
401      public static void fail(String failureMessage) {
402        Fail.fail(failureMessage);
403      }
404    
405      /**
406       * Only delegate to {@link Fail#fail(String, Throwable)} so that Assertions offers a full feature entry point to all
407       * Fest Assert features (but you can use Fail if you prefer).
408       */
409      public static void fail(String failureMessage, Throwable realCause) {
410        Fail.fail(failureMessage, realCause);
411      }
412    
413      /**
414       * Only delegate to {@link Fail#failBecauseExceptionWasNotThrown(Class)} so that Assertions offers a full feature
415       * entry point to all Fest Assert features (but you can use Fail if you prefer).
416       */
417      public static void failBecauseExceptionWasNotThrown(Class<? extends Exception> exceptionClass) {
418        Fail.failBecauseExceptionWasNotThrown(exceptionClass);
419      }
420    
421      // ------------------------------------------------------------------------------------------------------
422      // properties methods : not assertions but here to have a single entry point to all Fest Assert features.
423      // ------------------------------------------------------------------------------------------------------
424    
425      /**
426       * Only delegate to {@link Properties#extractProperty(String)} so that Assertions offers a full feature entry point to
427       * all Fest Assert features (but you can use {@link Properties} if you prefer).
428       * <p>
429       * Typical usage is to chain <code>extractProperty</code> with <code>from</code> method, see examples below :
430       * 
431       * <pre>
432       * // extract simple property values having a java standard type (here String)
433       * assertThat(extractProperty("name", String.class).from(fellowshipOfTheRing))
434       *           .contains("Boromir", "Gandalf", "Frodo", "Legolas")
435       *           .doesNotContain("Sauron", "Elrond");
436       *                                                              
437       * // extracting property works also with user's types (here Race)
438       * assertThat(extractProperty("race", String.class).from(fellowshipOfTheRing))
439       *           .contains(HOBBIT, ELF)
440       *           .doesNotContain(ORC);
441       * 
442       * // extract nested property on Race
443       * assertThat(extractProperty("race.name", String.class).from(fellowshipOfTheRing))
444       *           .contains("Hobbit", "Elf")
445       *           .doesNotContain("Orc");
446       * </pre>
447       */
448      public static <T> Properties<T> extractProperty(String propertyName, Class<T> propertyType) {
449        return Properties.extractProperty(propertyName, propertyType);
450      }
451    
452      /**
453       * Only delegate to {@link Properties#extractProperty(String)} so that Assertions offers a full feature entry point to
454       * all Fest Assert features (but you can use {@link Properties} if you prefer).
455       * <p>
456       * Typical usage is to chain <code>extractProperty</code> with <code>from</code> method, see examples below :
457       * 
458       * <pre>
459       * // extract simple property values, as no type has been defined the extracted property will be considered as Object 
460       * // to define the real property type (here String) use extractProperty("name", String.class) instead. 
461       * assertThat(extractProperty("name").from(fellowshipOfTheRing))
462       *           .contains("Boromir", "Gandalf", "Frodo", "Legolas")
463       *           .doesNotContain("Sauron", "Elrond");
464       *                                                              
465       * // extracting property works also with user's types (here Race), even though it will be considered as Object
466       * // to define the real property type (here String) use extractProperty("name", Race.class) instead. 
467       * assertThat(extractProperty("race").from(fellowshipOfTheRing)).contains(HOBBIT, ELF).doesNotContain(ORC);
468       * 
469       * // extract nested property on Race
470       * assertThat(extractProperty("race.name").from(fellowshipOfTheRing)).contains("Hobbit", "Elf").doesNotContain("Orc");
471       * </pre>
472       */
473      public static Properties<Object> extractProperty(String propertyName) {
474        return Properties.extractProperty(propertyName);
475      }
476      
477      // ------------------------------------------------------------------------------------------------------
478      // Data utility methods : not assertions but here to have a single entry point to all Fest Assert features.
479      // ------------------------------------------------------------------------------------------------------
480    
481      /**
482       * Only delegate to {@link MapEntry#entry(Object, Object)} so that Assertions offers a full feature entry point to all
483       * Fest Assert features (but you can use {@link MapEntry} if you prefer).
484       * <p>
485       * Typical usage is to call <code>entry</code> in MapAssert <code>contains</code> assertion, see examples below :
486       * 
487       * <pre>
488       * assertThat(ringBearers).contains(entry(oneRing, frodo), entry(nenya, galadriel));
489       * </pre>
490       */
491      public static MapEntry entry(Object key, Object value) {
492        return MapEntry.entry(key, value);
493      }
494    
495      /**
496       * Only delegate to {@link Index#atIndex(int)} so that Assertions offers a full feature entry point to all Fest
497       * Assert features (but you can use {@link Index} if you prefer).
498       * <p>
499       * Typical usage :
500       * 
501       * <pre>
502       * List<Ring> elvesRings = list(vilya, nenya, narya);
503       * assertThat(elvesRings).contains(vilya, atIndex(0)).contains(nenya, atIndex(1)).contains(narya, atIndex(2));
504       * </pre>
505       */
506      public static Index atIndex(int index) {
507        return Index.atIndex(index);
508      }
509    
510      /**
511       * Only delegate to {@link Offset#offset(Double)} so that Assertions offers a full feature entry point to all Fest
512       * Assert features (but you can use {@link Offset} if you prefer).
513       * <p>
514       * Typical usage :
515       * 
516       * <pre>
517       * assertThat(8.1).isEqualTo(8.0, offset(0.1));
518       * </pre>
519       */
520      public static Offset<Double> offset(Double value) {
521        return Offset.offset(value);
522      }
523    
524      /**
525       * Only delegate to {@link Offset#offset(Float)} so that Assertions offers a full feature entry point to all Fest
526       * Assert features (but you can use {@link Offset} if you prefer).
527       * <p>
528       * Typical usage :
529       * 
530       * <pre>
531       * assertThat(8.2f).isEqualTo(8.0f, offset(0.2f));
532       * </pre>
533       */
534      public static Offset<Float> offset(Float value) {
535        return Offset.offset(value);
536      }
537      
538      
539      // ------------------------------------------------------------------------------------------------------
540      // Condition methods : not assertions but here to have a single entry point to all Fest Assert features.
541      // ------------------------------------------------------------------------------------------------------
542      
543      /**
544       * Only delegate to {@link AnyOf#anyOf(Condition...)} so that Assertions offers a full feature entry point to all Fest
545       * Assert features (but you can use {@link AnyOf} if you prefer).
546       * <p>
547       * Typical usage (<code>jedi</code> and <code>sith</code> are {@link Condition}) :
548       * 
549       * <pre>
550       * assertThat("Vader").is(anyOf(jedi, sith));
551       * </pre>
552       */
553      public static <T> Condition<T> anyOf(Condition<T>... conditions) {
554        return AnyOf.anyOf(conditions);
555      }
556    
557      /**
558       * Creates a new <code>{@link AnyOf}</code>
559       * @param <T> the type of object the given condition accept.
560       * @param conditions the conditions to evaluate.
561       * @return the created {@code AnyOf}.
562       * @throws NullPointerException if the given collection is {@code null}.
563       * @throws NullPointerException if any of the elements in the given collection is {@code null}.
564       */
565      public static <T> Condition<T> anyOf(Collection<Condition<T>> conditions) {
566        return AnyOf.anyOf(conditions);
567      }  
568    
569      // --------------------------------------------------------------------------------------------------
570      // Filter methods : not assertions but here to have a single entry point to all Fest Assert features.
571      // --------------------------------------------------------------------------------------------------
572    
573      /**
574       * Only delegate to {@link Filters#filter(Object[])} so that Assertions offers a full feature entry point to all Fest
575       * Assert features (but you can use {@link Filters} if you prefer).
576       * <p>
577       * Note that the given array is not modified, the filters are performed on an {@link Iterable} copy of the array.
578       * <p>
579       * Typical usage with {@link Condition} :
580       * 
581       * <pre>
582       * assertThat(filter(players).being(potentialMVP).get()).containsOnly(james, rose);</pre>
583       * and with filter language based on java bean property :
584       * <pre>
585       * assertThat(filter(players).with("pointsPerGame").greaterThan(20)
586       *                           .and("assistsPerGame").greaterThan(7)
587       *                           .get()).containsOnly(james, rose);</pre>
588       */
589      public static <E> Filters<E> filter(E[] array) {
590        return Filters.filter(array);
591      }
592      
593      /**
594       * Only delegate to {@link Filters#filter(Object[])} so that Assertions offers a full feature entry point to all Fest
595       * Assert features (but you can use {@link Filters} if you prefer).
596       * <p>
597       * Note that the given {@link Iterable} is not modified, the filters are performed on a copy.
598       * <p>
599       * Typical usage with {@link Condition} :
600       * 
601       * <pre>
602       * assertThat(filter(players).being(potentialMVP).get()).containsOnly(james, rose);</pre>
603       * and with filter language based on java bean property :
604       * <pre>
605       * assertThat(filter(players).with("pointsPerGame").greaterThan(20)
606       *                           .and("assistsPerGame").greaterThan(7)
607       *                           .get()).containsOnly(james, rose);</pre>
608       */
609      public static <E> Filters<E> filter(Iterable<E> iterableToFilter) {
610        return Filters.filter(iterableToFilter);
611      }
612      
613      /** Creates a new </code>{@link Assertions}</code>. */
614      protected Assertions() {}
615    }