1 package org.junit;
2 
3 import static java.util.Arrays.asList;
4 import static org.hamcrest.CoreMatchers.is;
5 import static org.hamcrest.CoreMatchers.notNullValue;
6 import static org.hamcrest.CoreMatchers.nullValue;
7 import org.hamcrest.Matcher;
8 import org.junit.internal.AssumptionViolatedException;
9 import org.junit.internal.matchers.Each;
10 
11 /**
12  * A set of methods useful for stating assumptions about the conditions in which a test is meaningful.
13  * A failed assumption does not mean the code is broken, but that the test provides no useful information.
14  * The default JUnit runner treats tests with failing assumptions as ignored.  Custom runners may behave differently.
15  *
16  * For example:
17  * <pre>
18  * // only provides information if database is reachable.
19  * \@Test public void calculateTotalSalary() {
20  *    DBConnection dbc = Database.connect();
21  *    assumeNotNull(dbc);
22  *    // ...
23  * }
24  * </pre>
25  * These methods can be used directly: <code>Assume.assumeTrue(...)</code>, however, they
26  * read better if they are referenced through static import:<br/>
27  * <pre>
28  * import static org.junit.Assume.*;
29  *    ...
30  *    assumeTrue(...);
31  * </pre>
32  */
33 public class Assume {
34 	/**
35 	 * If called with an expression evaluating to {@code false}, the test will halt and be ignored.
36 	 * @param b
37 	 */
assumeTrue(boolean b)38 	public static void assumeTrue(boolean b) {
39 		assumeThat(b, is(true));
40 	}
41 
42 	/**
43 	 * If called with one or more null elements in <code>objects</code>, the test will halt and be ignored.
44 	 * @param objects
45 	 */
assumeNotNull(Object... objects)46 		public static void assumeNotNull(Object... objects) {
47 		assumeThat(asList(objects), Each.each(notNullValue()));
48 	}
49 
50 	    /**
51 	     * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>.
52 	     * If not, the test halts and is ignored.
53 	     * Example:
54 	     * <pre>:
55 	     *   assumeThat(1, is(1)); // passes
56 	     *   foo(); // will execute
57 	     *   assumeThat(0, is(1)); // assumption failure! test halts
58 	     *   int x = 1 / 0; // will never execute
59 	     * </pre>
60 	     *
61 	     * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))}
62 	     * @param actual the computed value being compared
63 	     * @param matcher an expression, built of {@link Matcher}s, specifying allowed values
64 	     *
65 	     * @see org.hamcrest.CoreMatchers
66 	     * @see org.junit.matchers.JUnitMatchers
67 	     */
assumeThat(T actual, Matcher<T> matcher)68 	public static <T> void assumeThat(T actual, Matcher<T> matcher) {
69 		if (!matcher.matches(actual))
70 			throw new AssumptionViolatedException(actual, matcher);
71 	}
72 
73     /**
74 	 * Use to assume that an operation completes normally.  If {@code t} is non-null, the test will halt and be ignored.
75 	 *
76 	 * For example:
77 	 * <pre>
78 	 * \@Test public void parseDataFile() {
79 	 *   DataFile file;
80 	 *   try {
81 	 *     file = DataFile.open("sampledata.txt");
82 	 *   } catch (IOException e) {
83 	 *     // stop test and ignore if data can't be opened
84 	 *     assumeNoException(e);
85 	 *   }
86 	 *   // ...
87 	 * }
88 	 * </pre>
89 	 * @param t if non-null, the offending exception
90 	 */
assumeNoException(Throwable t)91 	public static void assumeNoException(Throwable t) {
92 		assumeThat(t, nullValue());
93 	}
94 }
95