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/junit4/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/junit4/wiki/Theories">Theories</a>
33  *
34  * @since 4.4
35  */
36 public class Assume {
37 
38     /**
39      * Do not instantiate.
40      * @deprecated since 4.13.
41      */
42     @Deprecated
Assume()43     public Assume() {
44     }
45 
46     /**
47      * If called with an expression evaluating to {@code false}, the test will halt and be ignored.
48      */
assumeTrue(boolean b)49     public static void assumeTrue(boolean b) {
50         assumeThat(b, is(true));
51     }
52 
53     /**
54      * The inverse of {@link #assumeTrue(boolean)}.
55      */
assumeFalse(boolean b)56     public static void assumeFalse(boolean b) {
57         assumeThat(b, is(false));
58     }
59 
60     /**
61      * If called with an expression evaluating to {@code false}, the test will halt and be ignored.
62      *
63      * @param b If <code>false</code>, the method will attempt to stop the test and ignore it by
64      * throwing {@link AssumptionViolatedException}.
65      * @param message A message to pass to {@link AssumptionViolatedException}.
66      */
assumeTrue(String message, boolean b)67     public static void assumeTrue(String message, boolean b) {
68         if (!b) throw new AssumptionViolatedException(message);
69     }
70 
71     /**
72      * The inverse of {@link #assumeTrue(String, boolean)}.
73      */
assumeFalse(String message, boolean b)74     public static void assumeFalse(String message, boolean b) {
75         assumeTrue(message, !b);
76     }
77 
78     /**
79      * If called with a {@code null} array or one or more {@code null} elements in {@code objects},
80      * the test will halt and be ignored.
81      */
assumeNotNull(Object... objects)82     public static void assumeNotNull(Object... objects) {
83         assumeThat(objects, notNullValue());
84         assumeThat(asList(objects), everyItem(notNullValue()));
85     }
86 
87     /**
88      * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>.
89      * If not, the test halts and is ignored.
90      * Example:
91      * <pre>:
92      *   assumeThat(1, is(1)); // passes
93      *   foo(); // will execute
94      *   assumeThat(0, is(1)); // assumption failure! test halts
95      *   int x = 1 / 0; // will never execute
96      * </pre>
97      *
98      * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))}
99      * @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      */
assumeThat(T actual, Matcher<T> matcher)104     public static <T> void assumeThat(T actual, Matcher<T> matcher) {
105         if (!matcher.matches(actual)) {
106             throw new AssumptionViolatedException(actual, matcher);
107         }
108     }
109 
110     /**
111      * Call to assume that <code>actual</code> satisfies the condition specified by <code>matcher</code>.
112      * If not, the test halts and is ignored.
113      * Example:
114      * <pre>:
115      *   assumeThat("alwaysPasses", 1, is(1)); // passes
116      *   foo(); // will execute
117      *   assumeThat("alwaysFails", 0, is(1)); // assumption failure! test halts
118      *   int x = 1 / 0; // will never execute
119      * </pre>
120      *
121      * @param <T> the static type accepted by the matcher (this can flag obvious compile-time problems such as {@code assumeThat(1, is("a"))}
122      * @param actual the computed value being compared
123      * @param matcher an expression, built of {@link Matcher}s, specifying allowed values
124      * @see org.hamcrest.CoreMatchers
125      * @see org.junit.matchers.JUnitMatchers
126      */
assumeThat(String message, T actual, Matcher<T> matcher)127     public static <T> void assumeThat(String message, T actual, Matcher<T> matcher) {
128         if (!matcher.matches(actual)) {
129             throw new AssumptionViolatedException(message, actual, matcher);
130         }
131     }
132 
133     /**
134      * Use to assume that an operation completes normally.  If {@code e} is non-null, the test will halt and be ignored.
135      *
136      * For example:
137      * <pre>
138      * \@Test public void parseDataFile() {
139      *   DataFile file;
140      *   try {
141      *     file = DataFile.open("sampledata.txt");
142      *   } catch (IOException e) {
143      *     // stop test and ignore if data can't be opened
144      *     assumeNoException(e);
145      *   }
146      *   // ...
147      * }
148      * </pre>
149      *
150      * @param e if non-null, the offending exception
151      */
assumeNoException(Throwable e)152     public static void assumeNoException(Throwable e) {
153         assumeThat(e, nullValue());
154     }
155 
156     /**
157      * Attempts to halt the test and ignore it if Throwable <code>e</code> is
158      * not <code>null</code>. Similar to {@link #assumeNoException(Throwable)},
159      * but provides an additional message that can explain the details
160      * concerning the assumption.
161      *
162      * @param e if non-null, the offending exception
163      * @param message Additional message to pass to {@link AssumptionViolatedException}.
164      * @see #assumeNoException(Throwable)
165      */
assumeNoException(String message, Throwable e)166     public static void assumeNoException(String message, Throwable e) {
167         assumeThat(message, e, nullValue());
168     }
169 }
170