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