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            assumeThat(b, is(false));
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         */
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         */
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         */
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         */
166        public static void assumeNoException(String message, Throwable e) {
167            assumeThat(message, e, nullValue());
168        }
169    }