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