1package org.junit;
2
3import static java.util.Arrays.asList;
4import static org.hamcrest.CoreMatchers.is;
5import static org.hamcrest.CoreMatchers.notNullValue;
6import static org.hamcrest.CoreMatchers.nullValue;
7import org.hamcrest.Matcher;
8import org.junit.internal.AssumptionViolatedException;
9import 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 */
33public class Assume {
34	/**
35	 * If called with an expression evaluating to {@code false}, the test will halt and be ignored.
36	 * @param b
37	 */
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	 */
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	     */
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	 */
91	public static void assumeNoException(Throwable t) {
92		assumeThat(t, nullValue());
93	}
94}
95