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