001 package org.junit;
002
003 import static java.util.Arrays.asList;
004 import static org.hamcrest.CoreMatchers.everyItem;
005 import static org.hamcrest.CoreMatchers.is;
006 import static org.hamcrest.CoreMatchers.notNullValue;
007 import static org.hamcrest.CoreMatchers.nullValue;
008
009 import org.hamcrest.Matcher;
010
011 /**
012 * A set of methods useful for stating assumptions about the conditions in which a test is meaningful.
013 * A failed assumption does not mean the code is broken, but that the test provides no useful information. Assume
014 * basically means "don't run this test if these conditions don't apply". The default JUnit runner skips tests with
015 * failing assumptions. Custom runners may behave differently.
016 * <p>
017 * A good example of using assumptions is in <a href="https://github.com/junit-team/junit4/wiki/Theories">Theories</a> where they are needed to exclude certain datapoints that aren't suitable or allowed for a certain test case.
018 * </p>
019 * Failed assumptions are usually not logged, because there may be many tests that don't apply to certain
020 * configurations.
021 *
022 * <p>
023 * These methods can be used directly: <code>Assume.assumeTrue(...)</code>, however, they
024 * read better if they are referenced through static import:<br/>
025 * <pre>
026 * import static org.junit.Assume.*;
027 * ...
028 * assumeTrue(...);
029 * </pre>
030 * </p>
031 *
032 * @see <a href="https://github.com/junit-team/junit4/wiki/Theories">Theories</a>
033 *
034 * @since 4.4
035 */
036 public class Assume {
037
038 /**
039 * Do not instantiate.
040 * @deprecated since 4.13.
041 */
042 @Deprecated
043 public Assume() {
044 }
045
046 /**
047 * If called with an expression evaluating to {@code false}, the test will halt and be ignored.
048 */
049 public static void assumeTrue(boolean b) {
050 assumeThat(b, is(true));
051 }
052
053 /**
054 * The inverse of {@link #assumeTrue(boolean)}.
055 */
056 public static void assumeFalse(boolean b) {
057 assumeTrue(!b);
058 }
059
060 /**
061 * If called with an expression evaluating to {@code false}, the test will halt and be ignored.
062 *
063 * @param b If <code>false</code>, the method will attempt to stop the test and ignore it by
064 * throwing {@link AssumptionViolatedException}.
065 * @param message A message to pass to {@link AssumptionViolatedException}.
066 */
067 public static void assumeTrue(String message, boolean b) {
068 if (!b) throw new AssumptionViolatedException(message);
069 }
070
071 /**
072 * The inverse of {@link #assumeTrue(String, boolean)}.
073 */
074 public static void assumeFalse(String message, boolean b) {
075 assumeTrue(message, !b);
076 }
077
078 /**
079 * If called with a {@code null} array or one or more {@code null} elements in {@code objects},
080 * the test will halt and be ignored.
081 */
082 public static void assumeNotNull(Object... objects) {
083 assumeThat(objects, notNullValue());
084 assumeThat(asList(objects), everyItem(notNullValue()));
085 }
086
087 /**
088 * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>.
089 * If not, the test halts and is ignored.
090 * Example:
091 * <pre>:
092 * assumeThat(1, is(1)); // passes
093 * foo(); // will execute
094 * assumeThat(0, is(1)); // assumption failure! test halts
095 * int x = 1 / 0; // will never execute
096 * </pre>
097 *
098 * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))}
099 * @param actual the computed value being compared
100 * @param matcher an expression, built of {@link Matcher}s, specifying allowed values
101 * @see org.hamcrest.CoreMatchers
102 * @see org.junit.matchers.JUnitMatchers
103 * @deprecated use {@code org.hamcrest.junit.MatcherAssume.assumeThat()}
104 */
105 @Deprecated
106 public static <T> void assumeThat(T actual, Matcher<T> matcher) {
107 if (!matcher.matches(actual)) {
108 throw new AssumptionViolatedException(actual, matcher);
109 }
110 }
111
112 /**
113 * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>.
114 * If not, the test halts and is ignored.
115 * Example:
116 * <pre>:
117 * assumeThat("alwaysPasses", 1, is(1)); // passes
118 * foo(); // will execute
119 * assumeThat("alwaysFails", 0, is(1)); // assumption failure! test halts
120 * int x = 1 / 0; // will never execute
121 * </pre>
122 *
123 * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))}
124 * @param actual the computed value being compared
125 * @param matcher an expression, built of {@link Matcher}s, specifying allowed values
126 * @see org.hamcrest.CoreMatchers
127 * @see org.junit.matchers.JUnitMatchers
128 * @deprecated use {@code org.hamcrest.junit.MatcherAssume.assumeThat()}
129 */
130 @Deprecated
131 public static <T> void assumeThat(String message, T actual, Matcher<T> matcher) {
132 if (!matcher.matches(actual)) {
133 throw new AssumptionViolatedException(message, actual, matcher);
134 }
135 }
136
137 /**
138 * Use to assume that an operation completes normally. If {@code e} is non-null, the test will halt and be ignored.
139 *
140 * For example:
141 * <pre>
142 * \@Test public void parseDataFile() {
143 * DataFile file;
144 * try {
145 * file = DataFile.open("sampledata.txt");
146 * } catch (IOException e) {
147 * // stop test and ignore if data can't be opened
148 * assumeNoException(e);
149 * }
150 * // ...
151 * }
152 * </pre>
153 *
154 * @param e if non-null, the offending exception
155 */
156 public static void assumeNoException(Throwable e) {
157 assumeThat(e, nullValue());
158 }
159
160 /**
161 * Attempts to halt the test and ignore it if Throwable <code>e</code> is
162 * not <code>null</code>. Similar to {@link #assumeNoException(Throwable)},
163 * but provides an additional message that can explain the details
164 * concerning the assumption.
165 *
166 * @param e if non-null, the offending exception
167 * @param message Additional message to pass to {@link AssumptionViolatedException}.
168 * @see #assumeNoException(Throwable)
169 */
170 public static void assumeNoException(String message, Throwable e) {
171 assumeThat(message, e, nullValue());
172 }
173 }