001package org.junit; 002 003import static java.util.Arrays.asList; 004import static org.hamcrest.CoreMatchers.everyItem; 005import static org.hamcrest.CoreMatchers.is; 006import static org.hamcrest.CoreMatchers.notNullValue; 007import static org.hamcrest.CoreMatchers.nullValue; 008 009import org.hamcrest.Matcher; 010import org.junit.internal.AssumptionViolatedException; 011 012/** 013 * A set of methods useful for stating assumptions about the conditions in which a test is meaningful. 014 * A failed assumption does not mean the code is broken, but that the test provides no useful information. 015 * The default JUnit runner treats tests with failing assumptions as ignored. Custom runners may behave differently. 016 * 017 * For example: 018 * <pre> 019 * // only provides information if database is reachable. 020 * \@Test public void calculateTotalSalary() { 021 * DBConnection dbc = Database.connect(); 022 * assumeNotNull(dbc); 023 * // ... 024 * } 025 * </pre> 026 * These methods can be used directly: <code>Assume.assumeTrue(...)</code>, however, they 027 * read better if they are referenced through static import:<br/> 028 * <pre> 029 * import static org.junit.Assume.*; 030 * ... 031 * assumeTrue(...); 032 * </pre> 033 * 034 * @since 4.4 035 */ 036public class Assume { 037 /** 038 * If called with an expression evaluating to {@code false}, the test will halt and be ignored. 039 */ 040 public static void assumeTrue(boolean b) { 041 assumeThat(b, is(true)); 042 } 043 044 /** 045 * The inverse of {@link #assumeTrue(boolean)}. 046 */ 047 public static void assumeFalse(boolean b) { 048 assumeTrue(!b); 049 } 050 051 /** 052 * If called with an expression evaluating to {@code false}, the test will halt and be ignored. 053 * 054 * @param b If <code>false</code>, the method will attempt to stop the test and ignore it by 055 * throwing {@link AssumptionViolatedException}. 056 * @param message A message to pass to {@link AssumptionViolatedException}. 057 */ 058 public static void assumeTrue(String message, boolean b) { 059 if (!b) throw new AssumptionViolatedException(message); 060 } 061 062 /** 063 * The inverse of {@link #assumeTrue(String, boolean)}. 064 */ 065 public static void assumeFalse(String message, boolean b) { 066 assumeTrue(message, !b); 067 } 068 069 /** 070 * If called with one or more null elements in <code>objects</code>, the test will halt and be ignored. 071 */ 072 public static void assumeNotNull(Object... objects) { 073 assumeThat(asList(objects), everyItem(notNullValue())); 074 } 075 076 /** 077 * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>. 078 * If not, the test halts and is ignored. 079 * Example: 080 * <pre>: 081 * assumeThat(1, is(1)); // passes 082 * foo(); // will execute 083 * assumeThat(0, is(1)); // assumption failure! test halts 084 * int x = 1 / 0; // will never execute 085 * </pre> 086 * 087 * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))} 088 * @param actual the computed value being compared 089 * @param matcher an expression, built of {@link Matcher}s, specifying allowed values 090 * @see org.hamcrest.CoreMatchers 091 * @see org.junit.matchers.JUnitMatchers 092 */ 093 public static <T> void assumeThat(T actual, Matcher<T> matcher) { 094 if (!matcher.matches(actual)) { 095 throw new AssumptionViolatedException(actual, matcher); 096 } 097 } 098 099 /** 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(1, is(1)); // passes 105 * foo(); // will execute 106 * assumeThat(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 */ 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 t} 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 t if non-null, the offending exception 140 */ 141 public static void assumeNoException(Throwable t) { 142 assumeThat(t, nullValue()); 143 } 144 145 /** 146 * Attempts to halt the test and ignore it if Throwable <code>t</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 t if non-null, the offending exception 152 * @param message Additional message to pass to {@link AssumptionViolatedException}. 153 * @see #assumeNoException(Throwable) 154 */ 155 public static void assumeNoException(String message, Throwable t) { 156 assumeThat(message, t, nullValue()); 157 } 158}