    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    }