1 package org.junit; 2 3 import static java.util.Arrays.asList; 4 import static org.hamcrest.CoreMatchers.everyItem; 5 import static org.hamcrest.CoreMatchers.is; 6 import static org.hamcrest.CoreMatchers.notNullValue; 7 import static org.hamcrest.CoreMatchers.nullValue; 8 9 import org.hamcrest.Matcher; 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. Assume 14 * basically means "don't run this test if these conditions don't apply". The default JUnit runner skips tests with 15 * failing assumptions. Custom runners may behave differently. 16 * <p> 17 * A good example of using assumptions is in <a href="https://github.com/junit-team/junit/wiki/Theories">Theories</a> where they are needed to exclude certain datapoints that aren't suitable or allowed for a certain test case. 18 * </p> 19 * Failed assumptions are usually not logged, because there may be many tests that don't apply to certain 20 * configurations. 21 * 22 * <p> 23 * These methods can be used directly: <code>Assume.assumeTrue(...)</code>, however, they 24 * read better if they are referenced through static import:<br/> 25 * <pre> 26 * import static org.junit.Assume.*; 27 * ... 28 * assumeTrue(...); 29 * </pre> 30 * </p> 31 * 32 * @see <a href="https://github.com/junit-team/junit/wiki/Theories">Theories</a> 33 * 34 * @since 4.4 35 */ 36 public class Assume { 37 /** 38 * If called with an expression evaluating to {@code false}, the test will halt and be ignored. 39 */ assumeTrue(boolean b)40 public static void assumeTrue(boolean b) { 41 assumeThat(b, is(true)); 42 } 43 44 /** 45 * The inverse of {@link #assumeTrue(boolean)}. 46 */ assumeFalse(boolean b)47 public static void assumeFalse(boolean b) { 48 assumeTrue(!b); 49 } 50 51 /** 52 * If called with an expression evaluating to {@code false}, the test will halt and be ignored. 53 * 54 * @param b If <code>false</code>, the method will attempt to stop the test and ignore it by 55 * throwing {@link AssumptionViolatedException}. 56 * @param message A message to pass to {@link AssumptionViolatedException}. 57 */ assumeTrue(String message, boolean b)58 public static void assumeTrue(String message, boolean b) { 59 if (!b) throw new AssumptionViolatedException(message); 60 } 61 62 /** 63 * The inverse of {@link #assumeTrue(String, boolean)}. 64 */ assumeFalse(String message, boolean b)65 public static void assumeFalse(String message, boolean b) { 66 assumeTrue(message, !b); 67 } 68 69 /** 70 * If called with one or more null elements in <code>objects</code>, the test will halt and be ignored. 71 */ assumeNotNull(Object... objects)72 public static void assumeNotNull(Object... objects) { 73 assumeThat(asList(objects), everyItem(notNullValue())); 74 } 75 76 /** 77 * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>. 78 * If not, the test halts and is ignored. 79 * Example: 80 * <pre>: 81 * assumeThat(1, is(1)); // passes 82 * foo(); // will execute 83 * assumeThat(0, is(1)); // assumption failure! test halts 84 * int x = 1 / 0; // will never execute 85 * </pre> 86 * 87 * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))} 88 * @param actual the computed value being compared 89 * @param matcher an expression, built of {@link Matcher}s, specifying allowed values 90 * @see org.hamcrest.CoreMatchers 91 * @see org.junit.matchers.JUnitMatchers 92 */ assumeThat(T actual, Matcher<T> matcher)93 public static <T> void assumeThat(T actual, Matcher<T> matcher) { 94 if (!matcher.matches(actual)) { 95 throw new AssumptionViolatedException(actual, matcher); 96 } 97 } 98 99 /** 100 * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>. 101 * If not, the test halts and is ignored. 102 * Example: 103 * <pre>: 104 * assumeThat("alwaysPasses", 1, is(1)); // passes 105 * foo(); // will execute 106 * assumeThat("alwaysFails", 0, is(1)); // assumption failure! test halts 107 * int x = 1 / 0; // will never execute 108 * </pre> 109 * 110 * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))} 111 * @param actual the computed value being compared 112 * @param matcher an expression, built of {@link Matcher}s, specifying allowed values 113 * @see org.hamcrest.CoreMatchers 114 * @see org.junit.matchers.JUnitMatchers 115 */ assumeThat(String message, T actual, Matcher<T> matcher)116 public static <T> void assumeThat(String message, T actual, Matcher<T> matcher) { 117 if (!matcher.matches(actual)) { 118 throw new AssumptionViolatedException(message, actual, matcher); 119 } 120 } 121 122 /** 123 * Use to assume that an operation completes normally. If {@code e} is non-null, the test will halt and be ignored. 124 * 125 * For example: 126 * <pre> 127 * \@Test public void parseDataFile() { 128 * DataFile file; 129 * try { 130 * file = DataFile.open("sampledata.txt"); 131 * } catch (IOException e) { 132 * // stop test and ignore if data can't be opened 133 * assumeNoException(e); 134 * } 135 * // ... 136 * } 137 * </pre> 138 * 139 * @param e if non-null, the offending exception 140 */ assumeNoException(Throwable e)141 public static void assumeNoException(Throwable e) { 142 assumeThat(e, nullValue()); 143 } 144 145 /** 146 * Attempts to halt the test and ignore it if Throwable <code>e</code> is 147 * not <code>null</code>. Similar to {@link #assumeNoException(Throwable)}, 148 * but provides an additional message that can explain the details 149 * concerning the assumption. 150 * 151 * @param e if non-null, the offending exception 152 * @param message Additional message to pass to {@link AssumptionViolatedException}. 153 * @see #assumeNoException(Throwable) 154 */ assumeNoException(String message, Throwable e)155 public static void assumeNoException(String message, Throwable e) { 156 assumeThat(message, e, nullValue()); 157 } 158 } 159