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}