Java tutorial
/* * Licensed to the Apache Software Foundation (ASF) under one * or more contributor license agreements. See the NOTICE file * distributed with this work for additional information * regarding copyright ownership. The ASF licenses this file * to you under the Apache License, Version 2.0 (the * "License"); you may not use this file except in compliance * with the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, * software distributed under the License is distributed on an * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY * KIND, either express or implied. See the License for the * specific language governing permissions and limitations * under the License. */ package org.apache.brooklyn.test; import groovy.lang.Closure; import java.lang.reflect.Array; import java.util.Arrays; import java.util.Collection; import java.util.Enumeration; import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.Set; import java.util.concurrent.Callable; import java.util.concurrent.ExecutionException; import java.util.concurrent.TimeoutException; import java.util.concurrent.atomic.AtomicReference; import org.apache.brooklyn.util.collections.MutableList; import org.apache.brooklyn.util.collections.MutableSet; import org.apache.brooklyn.util.exceptions.Exceptions; import org.apache.brooklyn.util.javalang.JavaClassNames; import org.apache.brooklyn.util.repeat.Repeater; import org.apache.brooklyn.util.text.StringPredicates; import org.apache.brooklyn.util.time.CountdownTimer; import org.apache.brooklyn.util.time.Duration; import org.slf4j.Logger; import org.slf4j.LoggerFactory; import com.google.common.annotations.Beta; import com.google.common.base.Predicate; import com.google.common.base.Predicates; import com.google.common.base.Supplier; import com.google.common.base.Suppliers; import com.google.common.collect.ImmutableList; import com.google.common.collect.ImmutableMap; import com.google.common.collect.Iterables; import com.google.common.collect.Lists; import com.google.common.collect.Sets; /** * TODO should move this to new package brooklyn.util.assertions * and TODO should add a repeating() method which returns an AssertingRepeater extending Repeater * and: * <ul> * <li> adds support for requireAllIterationsTrue * <li> convenience run methods equivalent to succeedsEventually and succeedsContinually * </ul> * <p> * NOTE Selected routines in this class are originally copied from <a href="http://testng.org">TestNG</a>, to allow us to make assertions without having to * introduce a runtime dependency on TestNG. * </p> */ @Beta public class Asserts { /** * Timeout for use when something should happen within several seconds, * but there might be network calls or computation so {@link #DEFAULT_SHORT_TIMEOUT} is not applicable. */ public static final Duration DEFAULT_LONG_TIMEOUT = Duration.THIRTY_SECONDS; /** * Timeout for use when waiting for other threads to finish. * <p> * Long enough for parallel execution to catch up, * even on overloaded mediocre test boxes most of the time, * but short enough not to irritate you when your test is failing. */ public static final Duration DEFAULT_SHORT_TIMEOUT = Duration.ONE_SECOND; /** @deprecated since 0.9.0 use {@link #DEFAULT_LONG_TIMEOUT} */ @Deprecated public static final Duration DEFAULT_TIMEOUT = DEFAULT_LONG_TIMEOUT; private static final Duration DEFAULT_SHORT_PERIOD = Repeater.DEFAULT_REAL_QUICK_PERIOD; private static final Logger log = LoggerFactory.getLogger(Asserts.class); private Asserts() { } private static final Character OPENING_CHARACTER = '['; private static final Character CLOSING_CHARACTER = ']'; private static final String ASSERT_LEFT = "expected " + OPENING_CHARACTER; private static final String ASSERT_MIDDLE = CLOSING_CHARACTER + " but found " + OPENING_CHARACTER; private static final String ASSERT_RIGHT = Character.toString(CLOSING_CHARACTER); static String format(Object actual, Object expected, String message) { String formatted = ""; if (null != message) { formatted = message + " "; } return formatted + ASSERT_LEFT + expected + ASSERT_MIDDLE + actual + ASSERT_RIGHT; } static private void failNotEquals(Object actual, Object expected, String message) { fail(format(actual, expected, message)); } /** * Assert that an object reference is null. * * @param object The object reference. * * @throws AssertionError if the assertion fails. */ static public void assertNull(final Object object) { assertNull(object, null); } /** * Assert that an object reference is not null. * * @param object The object reference. * * @throws AssertionError if the assertion fails. */ static public void assertNotNull(final Object object) { assertNotNull(object, null); } /** * Assert that an object reference is null. * * @param object The object reference. * @param message The assertion error message. * * @throws AssertionError if the assertion fails. */ static public void assertNull(final Object object, final String message) { if (null != object) { throw new AssertionError(message == null ? "object reference is not null" : message); } } /** * Assert that an object reference is not null. * * @param object The object reference. * @param message The assertion error message. * * @throws AssertionError if the assertion fails. */ static public void assertNotNull(final Object object, final String message) { if (null == object) { throw new AssertionError(message == null ? "object reference is null" : message); } } /** * Asserts that two collections contain the same elements in the same order. If they do not, * an AssertionError is thrown. * * @param actual the actual value * @param expected the expected value */ static public void assertEquals(Collection<?> actual, Collection<?> expected) { assertEquals(actual, expected, null); } /** * Asserts that two collections contain the same elements in the same order. If they do not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(Collection<?> actual, Collection<?> expected, String message) { if (actual == expected) { return; } if (actual == null || expected == null) { if (message != null) { fail(message); } else { fail("Collections not equal: expected: " + expected + " and actual: " + actual); } } assertEquals(actual.size(), expected.size(), message + ": lists don't have the same size"); Iterator<?> actIt = actual.iterator(); Iterator<?> expIt = expected.iterator(); int i = -1; while (actIt.hasNext() && expIt.hasNext()) { i++; Object e = expIt.next(); Object a = actIt.next(); String explanation = "Lists differ at element [" + i + "]: " + e + " != " + a; String errorMessage = message == null ? explanation : message + ": " + explanation; assertEquals(a, e, errorMessage); } } /** Asserts that two iterators return the same elements in the same order. If they do not, * an AssertionError is thrown. * Please note that this assert iterates over the elements and modifies the state of the iterators. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(Iterator<?> actual, Iterator<?> expected) { assertEquals(actual, expected, null); } /** Asserts that two iterators return the same elements in the same order. If they do not, * an AssertionError, with the given message, is thrown. * Please note that this assert iterates over the elements and modifies the state of the iterators. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(Iterator<?> actual, Iterator<?> expected, String message) { if (actual == expected) { return; } if (actual == null || expected == null) { if (message != null) { fail(message); } else { fail("Iterators not equal: expected: " + expected + " and actual: " + actual); } } int i = -1; while (actual.hasNext() && expected.hasNext()) { i++; Object e = expected.next(); Object a = actual.next(); String explanation = "Iterators differ at element [" + i + "]: " + e + " != " + a; String errorMessage = message == null ? explanation : message + ": " + explanation; assertEquals(a, e, errorMessage); } if (actual.hasNext()) { String explanation = "Actual iterator returned more elements than the expected iterator."; String errorMessage = message == null ? explanation : message + ": " + explanation; fail(errorMessage); } else if (expected.hasNext()) { String explanation = "Expected iterator returned more elements than the actual iterator."; String errorMessage = message == null ? explanation : message + ": " + explanation; fail(errorMessage); } } /** Asserts that two iterables return iterators with the same elements in the same order. If they do not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(Iterable<?> actual, Iterable<?> expected) { assertEquals(actual, expected, null); } /** Asserts that two iterables return iterators with the same elements in the same order. If they do not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(Iterable<?> actual, Iterable<?> expected, String message) { if (actual == expected) { return; } if (actual == null || expected == null) { if (message != null) { fail(message); } else { fail("Iterables not equal: expected: " + expected + " and actual: " + actual); } } Iterator<?> actIt = actual.iterator(); Iterator<?> expIt = expected.iterator(); assertEquals(actIt, expIt, message); } /** * Asserts that two sets are equal. */ static public void assertEquals(Set<?> actual, Set<?> expected) { assertEquals(actual, expected, null); } /** * Assert set equals */ static public void assertEquals(Set<?> actual, Set<?> expected, String message) { if (actual == expected) { return; } if (actual == null || expected == null) { // Keep the back compatible if (message == null) { fail("Sets not equal: expected: " + expected + " and actual: " + actual); } else { failNotEquals(actual, expected, message); } } if (!actual.equals(expected)) { if (message == null) { fail("Sets differ: expected " + expected + " but got " + actual); } else { failNotEquals(actual, expected, message); } } } /** * Asserts that two maps are equal. */ static public void assertEquals(Map<?, ?> actual, Map<?, ?> expected) { if (actual == expected) { return; } if (actual == null || expected == null) { fail("Maps not equal: expected: " + expected + " and actual: " + actual); } if (actual.size() != expected.size()) { fail("Maps do not have the same size:" + actual.size() + " != " + expected.size()); } Set<?> entrySet = actual.entrySet(); for (Iterator<?> iterator = entrySet.iterator(); iterator.hasNext();) { Map.Entry<?, ?> entry = (Map.Entry<?, ?>) iterator.next(); Object key = entry.getKey(); Object value = entry.getValue(); Object expectedValue = expected.get(key); assertEquals(value, expectedValue, "Maps do not match for key:" + key + " actual:" + value + " expected:" + expectedValue); } } /** * Asserts that two arrays contain the same elements in the same order. If they do not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(Object[] actual, Object[] expected, String message) { if (actual == expected) { return; } if ((actual == null && expected != null) || (actual != null && expected == null)) { if (message != null) { fail(message); } else { fail("Arrays not equal: " + Arrays.toString(expected) + " and " + Arrays.toString(actual)); } } assertEquals(Arrays.asList(actual), Arrays.asList(expected), message); } /** * Asserts that two arrays contain the same elements in the same order. If they do not, * an AssertionError is thrown. * * @param actual the actual value * @param expected the expected value */ static public void assertEquals(Object[] actual, Object[] expected) { assertEquals(actual, expected, null); } /** * Asserts that two objects are equal. * @param actual the actual value * @param expected the expected value * * @throws AssertionError if the values are not equal. */ static public void assertEquals(Object actual, Object expected) { assertEquals(actual, expected, null); } /** * Asserts that two objects are equal. * * @param actual the actual value * @param expected the expected value * @param message the assertion error message * * @throws AssertionError if the values are not equal. */ static public void assertEquals(Object actual, Object expected, String message) { if ((expected == null) && (actual == null)) { return; } if (expected != null) { if (expected.getClass().isArray()) { assertArrayEquals(actual, expected, message); return; } else if (expected.equals(actual)) { return; } } failNotEquals(actual, expected, message); } /** * Asserts that two objects are equal. It they are not, an AssertionError, * with given message, is thrown. * @param actual the actual value * @param expected the expected value (should be an non-null array value) * @param message the assertion error message */ private static void assertArrayEquals(Object actual, Object expected, String message) { //is called only when expected is an array if (actual.getClass().isArray()) { int expectedLength = Array.getLength(expected); if (expectedLength == Array.getLength(actual)) { for (int i = 0; i < expectedLength; i++) { Object _actual = Array.get(actual, i); Object _expected = Array.get(expected, i); try { assertEquals(_actual, _expected); } catch (AssertionError ae) { failNotEquals(actual, expected, message == null ? "" : message + " (values at index " + i + " are not the same)"); } } //array values matched return; } else { failNotEquals(Array.getLength(actual), expectedLength, message == null ? "" : message + " (Array lengths are not the same)"); } } failNotEquals(actual, expected, message); } /** * Asserts that two Strings are equal. If they are not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(String actual, String expected, String message) { assertEquals((Object) actual, (Object) expected, message); } /** * Asserts that two Strings are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(String actual, String expected) { assertEquals(actual, expected, null); } /** * Asserts that two doubles are equal within a delta. If they are not, * an AssertionError, with the given message, is thrown. If the expected * value is infinity then the delta value is ignored. * @param actual the actual value * @param expected the expected value * @param delta the absolute tolerable difference between the actual and expected values * @param message the assertion error message */ static public void assertEquals(double actual, double expected, double delta, String message) { // handle infinity specially since subtracting to infinite values gives NaN and the // the following test fails if (Double.isInfinite(expected)) { if (!(expected == actual)) { failNotEquals(new Double(actual), new Double(expected), message); } } else if (!(Math.abs(expected - actual) <= delta)) { // Because comparison with NaN always returns false failNotEquals(new Double(actual), new Double(expected), message); } } /** * Asserts that two doubles are equal within a delta. If they are not, * an AssertionError is thrown. If the expected value is infinity then the * delta value is ignored. * @param actual the actual value * @param expected the expected value * @param delta the absolute tolerable difference between the actual and expected values */ static public void assertEquals(double actual, double expected, double delta) { assertEquals(actual, expected, delta, null); } /** * Asserts that two floats are equal within a delta. If they are not, * an AssertionError, with the given message, is thrown. If the expected * value is infinity then the delta value is ignored. * @param actual the actual value * @param expected the expected value * @param delta the absolute tolerable difference between the actual and expected values * @param message the assertion error message */ static public void assertEquals(float actual, float expected, float delta, String message) { // handle infinity specially since subtracting to infinite values gives NaN and the // the following test fails if (Float.isInfinite(expected)) { if (!(expected == actual)) { failNotEquals(new Float(actual), new Float(expected), message); } } else if (!(Math.abs(expected - actual) <= delta)) { failNotEquals(new Float(actual), new Float(expected), message); } } /** * Asserts that two floats are equal within a delta. If they are not, * an AssertionError is thrown. If the expected * value is infinity then the delta value is ignored. * @param actual the actual value * @param expected the expected value * @param delta the absolute tolerable difference between the actual and expected values */ static public void assertEquals(float actual, float expected, float delta) { assertEquals(actual, expected, delta, null); } /** * Asserts that two longs are equal. If they are not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(long actual, long expected, String message) { assertEquals(Long.valueOf(actual), Long.valueOf(expected), message); } /** * Asserts that two longs are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(long actual, long expected) { assertEquals(actual, expected, null); } /** * Asserts that two booleans are equal. If they are not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(boolean actual, boolean expected, String message) { assertEquals(Boolean.valueOf(actual), Boolean.valueOf(expected), message); } /** * Asserts that two booleans are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(boolean actual, boolean expected) { assertEquals(actual, expected, null); } /** * Asserts that two bytes are equal. If they are not, * an AssertionError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(byte actual, byte expected, String message) { assertEquals(Byte.valueOf(actual), Byte.valueOf(expected), message); } /** * Asserts that two bytes are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(byte actual, byte expected) { assertEquals(actual, expected, null); } /** * Asserts that two chars are equal. If they are not, * an AssertionFailedError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(char actual, char expected, String message) { assertEquals(Character.valueOf(actual), Character.valueOf(expected), message); } /** * Asserts that two chars are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(char actual, char expected) { assertEquals(actual, expected, null); } /** * Asserts that two shorts are equal. If they are not, * an AssertionFailedError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(short actual, short expected, String message) { assertEquals(Short.valueOf(actual), Short.valueOf(expected), message); } /** * Asserts that two shorts are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(short actual, short expected) { assertEquals(actual, expected, null); } /** * Asserts that two ints are equal. If they are not, * an AssertionFailedError, with the given message, is thrown. * @param actual the actual value * @param expected the expected value * @param message the assertion error message */ static public void assertEquals(int actual, int expected, String message) { assertEquals(Integer.valueOf(actual), Integer.valueOf(expected), message); } /** * Asserts that two ints are equal. If they are not, * an AssertionError is thrown. * @param actual the actual value * @param expected the expected value */ static public void assertEquals(int actual, int expected) { assertEquals(actual, expected, null); } /** * Asserts that a condition is true. If it isn't, an AssertionError is thrown. * @param condition the condition to evaluate */ public static void assertTrue(boolean condition) { if (!condition) fail(null); } /** * Asserts that a condition is true. If it isn't, * an AssertionError, with the given message, is thrown. * @param condition the condition to evaluate * @param message the assertion error message */ public static void assertTrue(boolean condition, String message) { if (!condition) fail(message); } /** * Asserts that a condition is false. If it isn't, * an AssertionError, with the given message, is thrown. * @param condition the condition to evaluate * @param message the assertion error message */ public static void assertFalse(boolean condition, String message) { if (condition) fail(message); } /** * Fails a test with the given message. * @param message the assertion error message */ public static AssertionError fail(String message) { throw new AssertionError(message); } public static void assertEqualsIgnoringOrder(Iterable<?> actual, Iterable<?> expected) { assertEqualsIgnoringOrder(actual, expected, false, null); } public static void assertEqualsIgnoringOrder(Iterable<?> actual, Iterable<?> expected, boolean logDuplicates, String errmsg) { Set<?> actualSet = Sets.newLinkedHashSet(actual); Set<?> expectedSet = Sets.newLinkedHashSet(expected); Set<?> extras = Sets.difference(actualSet, expectedSet); Set<?> missing = Sets.difference(expectedSet, actualSet); List<Object> duplicates = Lists.newArrayList(actual); for (Object a : actualSet) { duplicates.remove(a); } String fullErrmsg = "extras=" + extras + "; missing=" + missing + (logDuplicates ? "; duplicates=" + MutableSet.copyOf(duplicates) : "") + "; actualSize=" + Iterables.size(actual) + "; expectedSize=" + Iterables.size(expected) + "; actual=" + actual + "; expected=" + expected + "; " + errmsg; assertTrue(extras.isEmpty(), fullErrmsg); assertTrue(missing.isEmpty(), fullErrmsg); assertTrue(Iterables.size(actual) == Iterables.size(expected), fullErrmsg); assertTrue(actualSet.equals(expectedSet), fullErrmsg); // should be covered by extras/missing/size test } // --- new routines /** As {@link #eventually(Supplier, Predicate, Duration, Duration, String)} with defaults. */ public static <T> void eventually(Supplier<? extends T> supplier, Predicate<T> predicate) { eventually(supplier, predicate, null, null, null); } /** @deprecated since 0.9.0 use {@link #eventually(Supplier, Predicate, Duration, Duration, String)} */ @Deprecated public static <T> void eventually(Map<String, ?> flags, Supplier<? extends T> supplier, Predicate<T> predicate) { eventually(flags, supplier, predicate, (String) null); } /** @deprecated since 0.9.0 use {@link #eventually(Supplier, Predicate, Duration, Duration, String)} */ @Deprecated public static <T> void eventually(Map<String, ?> flags, Supplier<? extends T> supplier, Predicate<T> predicate, String errMsg) { eventually(supplier, predicate, toDuration(flags.get("timeout"), null), toDuration(flags.get("period"), null), errMsg); } /** As {@link #eventually(Supplier, Predicate, Duration, Duration, String)} with default. */ public static <T> void eventually(Supplier<? extends T> supplier, Predicate<T> predicate, Duration timeout) { eventually(supplier, predicate, timeout, null, null); } /** Asserts that eventually the supplier gives a value accepted by the predicate. * Tests periodically and succeeds as soon as the supplier gives an allowed value. * Other arguments can be null. * * @param supplier supplies the value to test, such as {@link Suppliers#ofInstance(Object)} for a constant * @param predicate the {@link Predicate} to apply to each value given by the supplier * @param timeout how long to wait, default {@link #DEFAULT_SHORT_TIMEOUT} * @param period how often to check, default quite often so you won't notice but letting the CPU do work * @param errMsg an error message to display if not satisfied, in addition to the last-tested supplied value and the predicate */ public static <T> void eventually(Supplier<? extends T> supplier, Predicate<T> predicate, Duration timeout, Duration period, String errMsg) { if (timeout == null) timeout = DEFAULT_SHORT_TIMEOUT; if (period == null) period = DEFAULT_SHORT_PERIOD; CountdownTimer timeleft = timeout.countdownTimer(); T supplied; int count = 0; do { if (count++ > 0) Duration.sleep(period); supplied = supplier.get(); if (predicate.apply(supplied)) return; } while (timeleft.isNotExpired()); fail("Expected: eventually " + predicate + "; got most recently: " + supplied + " (waited " + timeleft.getDurationElapsed() + ", checked " + count + ")" + (errMsg != null ? "; " + errMsg : "")); } /** As {@link #continually(Supplier, Predicate, Duration, Duration, String)} with defaults. */ public static <T> void continually(Supplier<? extends T> supplier, Predicate<T> predicate) { continually(ImmutableMap.<String, Object>of(), supplier, predicate); } /** @deprecated since 0.9.0 use {@link #eventually(Supplier, Predicate, Duration, Duration, String)} */ @Deprecated public static <T> void continually(Map<String, ?> flags, Supplier<? extends T> supplier, Predicate<? super T> predicate) { continually(flags, supplier, predicate, null); } /** @deprecated since 0.9.0 use {@link #eventually(Supplier, Predicate, Duration, Duration, String)} */ @Deprecated public static <T> void continually(Map<String, ?> flags, Supplier<? extends T> supplier, Predicate<T> predicate, String errMsg) { continually(supplier, predicate, toDuration(flags.get("timeout"), toDuration(flags.get("duration"), null)), toDuration(flags.get("period"), null), null); } /** * Asserts that continually the supplier gives a value accepted by the predicate. * Tests periodically and fails if the supplier gives a disallowed value. * Other arguments can be null. * * @param supplier supplies the value to test, such as {@link Suppliers#ofInstance(Object)} for a constant * @param predicate the {@link Predicate} to apply to each value given by the supplier * @param duration how long to test for, default {@link #DEFAULT_SHORT_TIMEOUT} * @param period how often to check, default quite often to minimise chance of missing a flashing violation but letting the CPU do work * @param errMsg an error message to display if not satisfied, in addition to the last-tested supplied value and the predicate */ public static <T> void continually(Supplier<? extends T> supplier, Predicate<T> predicate, Duration duration, Duration period, String errMsg) { if (duration == null) duration = DEFAULT_SHORT_TIMEOUT; if (period == null) period = DEFAULT_SHORT_PERIOD; CountdownTimer timeleft = duration.countdownTimer(); T supplied; int count = 0; do { if (count > 0) Duration.sleep(period); supplied = supplier.get(); if (!predicate.apply(supplied)) { fail("Expected: continually " + predicate + "; got violation: " + supplied // tell timing if it worked the first time and then failed + (count > 0 ? " (after " + timeleft.getDurationElapsed() + ", successfully checked " + count + ")" : "") + (errMsg != null ? "; " + errMsg : "")); } count++; } while (timeleft.isNotExpired()); } /** * @see #succeedsContinually(Map, Callable) */ public static void succeedsEventually(Runnable r) { succeedsEventually(ImmutableMap.<String, Object>of(), r); } /** * @see #succeedsContinually(Map, Callable) */ public static void succeedsEventually(Map<String, ?> flags, Runnable r) { succeedsEventually(flags, toCallable(r)); } /** * @see #succeedsContinually(Map, Callable) */ public static <T> T succeedsEventually(Callable<T> c) { return succeedsEventually(ImmutableMap.<String, Object>of(), c); } // FIXME duplication with TestUtils.BooleanWithMessage public static class BooleanWithMessage { boolean value; String message; public BooleanWithMessage(boolean value, String message) { this.value = value; this.message = message; } public boolean asBoolean() { return value; } public String toString() { return message; } } // TODO flags are ugly; remove this in favour of something strongly typed, // e.g. extending Repeater and taking the extra semantics. // TODO remove the #succeedsEventually in favour of #eventually (and same for continually) /** * Convenience method for cases where we need to test until something is true. * * The Callable will be invoked periodically until it succesfully concludes. * <p> * The following flags are supported: * <ul> * <li>abortOnError (boolean, default true) * <li>abortOnException - (boolean, default false) * <li>timeout - (a Duration or an integer in millis, defaults to {@link Asserts#DEFAULT_LONG_TIMEOUT}) * <li>period - (a Duration or an integer in millis, for fixed retry time; if not set, defaults to exponentially increasing from 1 to 500ms) * <li>minPeriod - (a Duration or an integer in millis; only used if period not explicitly set; the minimum period when exponentially increasing; defaults to 1ms) * <li>maxPeriod - (a Duration or an integer in millis; only used if period not explicitly set; the maximum period when exponentially increasing; defaults to 500ms) * <li>maxAttempts - (integer, Integer.MAX_VALUE) * </ul> * * The following flags are deprecated: * <ul> * <li>useGroovyTruth - (defaults to false; any result code apart from 'false' will be treated as success including null; ignored for Runnables which aren't Callables) * </ul> * * @param flags, accepts the flags listed above * @param c The callable to invoke */ public static <T> T succeedsEventually(Map<String, ?> flags, Callable<T> c) { boolean abortOnException = get(flags, "abortOnException", false); boolean abortOnError = get(flags, "abortOnError", false); boolean useGroovyTruth = get(flags, "useGroovyTruth", false); boolean logException = get(flags, "logException", true); // To speed up tests, default is for the period to start small and increase... Duration duration = toDuration(flags.get("timeout"), DEFAULT_LONG_TIMEOUT); Duration fixedPeriod = toDuration(flags.get("period"), null); Duration minPeriod = (fixedPeriod != null) ? fixedPeriod : toDuration(flags.get("minPeriod"), Duration.millis(1)); Duration maxPeriod = (fixedPeriod != null) ? fixedPeriod : toDuration(flags.get("maxPeriod"), Duration.millis(500)); int maxAttempts = get(flags, "maxAttempts", Integer.MAX_VALUE); int attempt = 0; long startTime = System.currentTimeMillis(); try { Throwable lastException = null; T result = null; long lastAttemptTime = 0; long expireTime = startTime + duration.toMilliseconds(); long sleepTimeBetweenAttempts = minPeriod.toMilliseconds(); while (attempt < maxAttempts && lastAttemptTime < expireTime) { try { attempt++; lastAttemptTime = System.currentTimeMillis(); result = c.call(); if (log.isTraceEnabled()) log.trace("Attempt {} after {} ms: {}", new Object[] { attempt, System.currentTimeMillis() - startTime, result }); if (useGroovyTruth) { if (groovyTruth(result)) return result; } else if (Boolean.FALSE.equals(result)) { if (result instanceof BooleanWithMessage) log.warn( "Test returned an instance of BooleanWithMessage but useGroovyTruth is not set! " + "The result of this probably isn't what you intended."); // FIXME surprising behaviour, "false" result here is acceptable return result; } else { return result; } lastException = null; } catch (Throwable e) { lastException = e; if (log.isTraceEnabled()) log.trace("Attempt {} after {} ms: {}", new Object[] { attempt, System.currentTimeMillis() - startTime, e.getMessage() }); if (abortOnException) throw e; if (abortOnError && e instanceof Error) throw e; } long sleepTime = Math.min(sleepTimeBetweenAttempts, expireTime - System.currentTimeMillis()); if (sleepTime > 0) Thread.sleep(sleepTime); sleepTimeBetweenAttempts = Math.min(sleepTimeBetweenAttempts * 2, maxPeriod.toMilliseconds()); } log.info("succeedsEventually exceeded max attempts or timeout - {} attempts lasting {} ms, for {}", new Object[] { attempt, System.currentTimeMillis() - startTime, c }); if (lastException != null) throw lastException; throw fail("invalid result: " + result); } catch (Throwable t) { if (logException) log.info("failed succeeds-eventually, " + attempt + " attempts, " + (System.currentTimeMillis() - startTime) + "ms elapsed " + "(rethrowing): " + t); throw propagate(t); } } public static <T> void succeedsContinually(Runnable r) { succeedsContinually(ImmutableMap.<String, Object>of(), r); } public static <T> void succeedsContinually(Map<?, ?> flags, Runnable r) { succeedsContinually(flags, toCallable(r)); } public static <T> T succeedsContinually(Callable<T> c) { return succeedsContinually(ImmutableMap.<String, Object>of(), c); } // TODO unify with "continually"; see also eventually, some of those options might be useful public static <T> T succeedsContinually(Map<?, ?> flags, Callable<T> job) { Duration duration = toDuration(flags.get("timeout"), Duration.ONE_SECOND); Duration period = toDuration(flags.get("period"), Duration.millis(10)); long periodMs = period.toMilliseconds(); long startTime = System.currentTimeMillis(); long expireTime = startTime + duration.toMilliseconds(); int attempt = 0; boolean first = true; T result = null; while (first || System.currentTimeMillis() <= expireTime) { attempt++; try { result = job.call(); } catch (Exception e) { log.info("succeedsContinually failed - {} attempts lasting {} ms, for {} (rethrowing)", new Object[] { attempt, System.currentTimeMillis() - startTime, job }); throw propagate(e); } if (periodMs > 0) sleep(periodMs); first = false; } return result; } private static Duration toDuration(Object duration, Duration defaultVal) { if (duration == null) return defaultVal; else return Duration.of(duration); } public static void assertFails(Runnable r) { assertFailsWith(toCallable(r), Predicates.alwaysTrue()); } public static void assertFails(Callable<?> c) { assertFailsWith(c, Predicates.alwaysTrue()); } public static void assertFailsWith(Callable<?> c, final Closure<Boolean> exceptionChecker) { assertFailsWith(c, new Predicate<Throwable>() { public boolean apply(Throwable input) { return exceptionChecker.call(input); } }); } @SafeVarargs public static void assertFailsWith(Runnable c, final Class<? extends Throwable> validException, final Class<? extends Throwable>... otherValidExceptions) { final List<Class<?>> validExceptions = ImmutableList.<Class<?>>builder().add(validException) .addAll(ImmutableList.copyOf(otherValidExceptions)).build(); assertFailsWith(c, new Predicate<Throwable>() { public boolean apply(Throwable e) { for (Class<?> validException : validExceptions) { if (validException.isInstance(e)) return true; } fail("Test threw exception of unexpected type " + e.getClass() + "; expecting " + validExceptions); return false; } }); } public static void assertFailsWith(Runnable r, Predicate<? super Throwable> exceptionChecker) { assertFailsWith(toCallable(r), exceptionChecker); } public static void assertFailsWith(Callable<?> c, Predicate<? super Throwable> exceptionChecker) { boolean failed = false; try { c.call(); } catch (Throwable e) { failed = true; if (!exceptionChecker.apply(e)) { log.debug("Test threw invalid exception (failing)", e); fail("Test threw invalid exception: " + e); } log.debug("Test for exception successful (" + e + ")"); } if (!failed) fail("Test code should have thrown exception but did not"); } public static void assertReturnsEventually(final Runnable r, Duration timeout) throws InterruptedException, ExecutionException, TimeoutException { final AtomicReference<Throwable> throwable = new AtomicReference<Throwable>(); Runnable wrappedR = new Runnable() { @Override public void run() { try { r.run(); } catch (Throwable t) { throwable.set(t); throw Exceptions.propagate(t); } } }; Thread thread = new Thread(wrappedR, "assertReturnsEventually(" + r + ")"); try { thread.start(); thread.join(timeout.toMilliseconds()); if (thread.isAlive()) { throw new TimeoutException( "Still running: r=" + r + "; thread=" + Arrays.toString(thread.getStackTrace())); } } catch (InterruptedException e) { throw Exceptions.propagate(e); } finally { thread.interrupt(); } if (throwable.get() != null) { throw new ExecutionException(throwable.get()); } } public static <T> void assertThat(T object, Predicate<T> condition) { if (condition.apply(object)) return; fail("Failed " + condition + ": " + object); } public static void assertStringContains(String input, String phrase1ToContain, String... optionalOtherPhrasesToContain) { if (input == null) fail("Input is null."); if (phrase1ToContain != null) { assertThat(input, StringPredicates.containsLiteral(phrase1ToContain)); } for (String otherPhrase : optionalOtherPhrasesToContain) { if (otherPhrase != null) { assertThat(input, StringPredicates.containsLiteral(otherPhrase)); } } } public static void assertStringContainsAtLeastOne(String input, String possiblePhrase1ToContain, String... optionalOtherPossiblePhrasesToContain) { if (input == null) fail("Input is null."); List<String> missing = MutableList.of(); if (possiblePhrase1ToContain != null) { if (input.contains(possiblePhrase1ToContain)) return; missing.add(possiblePhrase1ToContain); } for (String otherPhrase : optionalOtherPossiblePhrasesToContain) { if (otherPhrase != null) { if (input.contains(otherPhrase)) return; missing.add(otherPhrase); } } fail("Input did not contain any of the expected phrases " + missing + ": " + input); } public static void assertStringContainsIgnoreCase(String input, String phrase1ToContain, String... optionalOtherPhrasesToContain) { if (input == null) fail("Input is null."); if (phrase1ToContain != null) { assertThat(input, StringPredicates.containsLiteralIgnoreCase(phrase1ToContain)); } for (String otherPhrase : optionalOtherPhrasesToContain) { if (otherPhrase != null) { assertThat(input, StringPredicates.containsLiteralIgnoreCase(otherPhrase)); } } } public static void assertStringMatchesRegex(String input, String regex1ToMatch, String... optionalOtherRegexesToMatch) { if (input == null) fail("Input is null."); if (regex1ToMatch != null) { assertThat(input, StringPredicates.matchesRegex(regex1ToMatch)); } for (String otherRegex : optionalOtherRegexesToMatch) { if (otherRegex != null) { assertThat(input, StringPredicates.matchesRegex(otherRegex)); } } } /** Subclass of {@link AssertionError} which indicates that code which should have thrown did not, * so that callers can disambiguate expected errors from this one. * See {@link #shouldHaveFailedPreviously()} */ public static class ShouldHaveFailedPreviouslyAssertionError extends AssertionError { private static final long serialVersionUID = 4359541529633617518L; public ShouldHaveFailedPreviouslyAssertionError() { this("Should have failed previously."); } public ShouldHaveFailedPreviouslyAssertionError(String message) { super(message); } } /** Throws a {@link ShouldHaveFailedPreviouslyAssertionError} exception, * to more easily distinguish this failure from other fails. * In particular, use one of the <code>expectedFailure</code> methods * in the surrounding <code>catch</code> block and this error will pass through it. */ public static void shouldHaveFailedPreviously() { throw new ShouldHaveFailedPreviouslyAssertionError(); } /** As {@link #shouldHaveFailedPreviously()} but allowing detail, * for example a value which was received when it shouldn't have been. */ public static void shouldHaveFailedPreviously(String message) { throw new ShouldHaveFailedPreviouslyAssertionError(message); } /** Tests that an exception is not {@link ShouldHaveFailedPreviouslyAssertionError}. * See {@link #shouldHaveFailedPreviously()} */ public static void expectedFailure(Throwable e) { if (e instanceof ShouldHaveFailedPreviouslyAssertionError) throw (Error) e; } /** * Tests that an exception is not {@link ShouldHaveFailedPreviouslyAssertionError} * and is either one of the given types, or has a caused-by of one of the given types. * * If you want *just* the instanceof (without checking the caused-by), then just catch * those exception types, treat that as success, and let any other exception be propagated. * * @return If the test is satisfied, this method returns normally. * The caller can decide whether anything more should be done with the exception. * If the test fails, then either it is propagated, * if the {@link Throwable} is a fatal ({@link Exceptions#propagateIfFatal(Throwable)}) other than an {@link AssertionError}, * or more usually the test failure of this method is thrown, * with detail of the original {@link Throwable} logged and included in the caused-by. */ public static void expectedFailureOfType(Throwable e, Class<?>... permittedSupertypes) { if (e instanceof ShouldHaveFailedPreviouslyAssertionError) throw (Error) e; for (Class<?> clazz : permittedSupertypes) { @SuppressWarnings("unchecked") Throwable match = Exceptions.getFirstThrowableOfType(e, (Class<? extends Throwable>) clazz); if (match != null) return; } rethrowPreferredException(e, new AssertionError("Error " + JavaClassNames.simpleClassName(e) + " is not any of the expected types: " + Arrays.asList(permittedSupertypes), e)); } /** Tests {@link #expectedFailure(Throwable)} and that the <code>toString</code> * satisfies {@link #assertStringContains(String, String, String...)}. * @return as per {@link #expectedFailureOfType(Throwable, Class...)} */ public static void expectedFailureContains(Throwable e, String phrase1ToContain, String... optionalOtherPhrasesToContain) { if (e instanceof ShouldHaveFailedPreviouslyAssertionError) throw (Error) e; try { assertStringContains(e.toString(), phrase1ToContain, optionalOtherPhrasesToContain); } catch (AssertionError ee) { rethrowPreferredException(e, ee); } } /** As {@link #expectedFailureContains(Throwable, String, String...)} but case insensitive */ public static void expectedFailureContainsIgnoreCase(Throwable e, String phrase1ToContain, String... optionalOtherPhrasesToContain) { if (e instanceof ShouldHaveFailedPreviouslyAssertionError) throw (Error) e; try { assertStringContainsIgnoreCase(e.toString(), phrase1ToContain, optionalOtherPhrasesToContain); } catch (AssertionError ee) { rethrowPreferredException(e, ee); } } /** Implements the return beahvior for {@link #expectedFailureOfType(Throwable, Class...)} and others. */ private static void rethrowPreferredException(Throwable earlierPreferredIfFatalElseLogged, Throwable laterPreferredOtherwise) throws AssertionError { if (!(earlierPreferredIfFatalElseLogged instanceof AssertionError)) { Exceptions.propagateIfFatal(earlierPreferredIfFatalElseLogged); } log.warn("Detail of unexpected error: " + earlierPreferredIfFatalElseLogged, earlierPreferredIfFatalElseLogged); throw Exceptions.propagate(laterPreferredOtherwise); } @SuppressWarnings("rawtypes") private static boolean groovyTruth(Object o) { // TODO Doesn't handle matchers (see http://docs.codehaus.org/display/GROOVY/Groovy+Truth) if (o == null) { return false; } else if (o instanceof Boolean) { return (Boolean) o; } else if (o instanceof String) { return !((String) o).isEmpty(); } else if (o instanceof Collection) { return !((Collection) o).isEmpty(); } else if (o instanceof Map) { return !((Map) o).isEmpty(); } else if (o instanceof Iterator) { return ((Iterator) o).hasNext(); } else if (o instanceof Enumeration) { return ((Enumeration) o).hasMoreElements(); } else { return true; } } @SuppressWarnings("unchecked") private static <T> T get(Map<String, ?> map, String key, T defaultVal) { Object val = map.get(key); return (T) ((val == null) ? defaultVal : val); } private static Callable<?> toCallable(Runnable r) { return (r instanceof Callable) ? (Callable<?>) r : new RunnableAdapter<Void>(r, null); } /** Same as {@link java.util.concurrent.Executors#callable(Runnable)}, except includes toString() */ static final class RunnableAdapter<T> implements Callable<T> { final Runnable task; final T result; RunnableAdapter(Runnable task, T result) { this.task = task; this.result = result; } public T call() { task.run(); return result; } @Override public String toString() { return "RunnableAdapter(" + task + ")"; } } private static void sleep(long periodMs) { if (periodMs > 0) { try { Thread.sleep(periodMs); } catch (InterruptedException e) { throw propagate(e); } } } private static RuntimeException propagate(Throwable t) { if (t instanceof InterruptedException) { Thread.currentThread().interrupt(); } if (t instanceof RuntimeException) throw (RuntimeException) t; if (t instanceof Error) throw (Error) t; throw new RuntimeException(t); } /** As {@link #eventuallyOnNotify(Object, Supplier, Predicate, Duration, boolean)} with default timeout. */ public static <T> void eventuallyOnNotify(Object notifyTarget, Supplier<T> supplier, Predicate<T> predicate) { eventuallyOnNotify(notifyTarget, supplier, predicate, null); } /** as {@link #eventually(Supplier, Predicate)} for cases where an object is notified; * more efficient as it waits on the notify target object. * See also the simpler {@link #eventuallyOnNotify(Object, Predicate)} when looking at a collection which is getting notified. * Timeout defaults to {@link #DEFAULT_SHORT_TIMEOUT}. * <p> * This synchronizes on the notify target for the duration of the wait, * including while getting and checking the value, so as not to miss any notification. */ public static <T> void eventuallyOnNotify(Object notifyTarget, Supplier<T> supplier, Predicate<T> predicate, Duration timeout) { T supplied = null; if (timeout == null) timeout = DEFAULT_SHORT_TIMEOUT; CountdownTimer remaining = timeout.countdownTimer(); int checks = 0; synchronized (notifyTarget) { do { if (checks > 0) { remaining.waitOnForExpiryUnchecked(notifyTarget); } supplied = supplier.get(); if (predicate.apply(supplied)) return; checks++; } while (remaining.isNotExpired()); } // should get 2 checks, 1 before and 1 after, if no notifications; if more, tell the user fail("Expected: eventually " + predicate + "; got most recently: " + supplied + " (waited " + remaining.getDurationElapsed() + (checks > 2 ? "; notification count " + (checks - 2) : "") + ")"); } /** Convenience for {@link #eventuallyOnNotify(Object, Supplier, Predicate, Duration, boolean)} * when the notify target and the value under test are the same. */ public static <T> void eventuallyOnNotify(T object, Predicate<T> predicate, Duration timeout) { eventuallyOnNotify(object, Suppliers.ofInstance(object), predicate, timeout); } /** As {@link #eventuallyOnNotify(Object, Predicate, Duration)} with the default duration of {@link #eventuallyOnNotify(Object, Supplier, Predicate)}. */ public static <T> void eventuallyOnNotify(T object, Predicate<T> predicate) { eventuallyOnNotify(object, Suppliers.ofInstance(object), predicate, null); } }