Added suspendForMs to @RetryingTest

docs/retrying-test.adoc

@@ -25,6 +25,12 @@ The test function will be executed, up to `maxAttempts`, until it completes succ
 
 The default for `minSuccess` is 1. The value must be greater than or equal to 1.
 
+=== suspendForMs [optional]
+
+The `suspendForMs` attribute specifies the amount of time to pause between retries, in milliseconds.
+
+The default for `suspendForMs` is 0 (no pause). The value must be greater than or equal to 0.
+
 === onExceptions [optional]
 
 By default a test annotated with `@RetryingTest` will be retried on all exceptions except https://ota4j-team.github.io/opentest4j/docs/current/api/org/opentest4j/TestAbortedException.html[`TestAbortedException`] (which will abort the test entirely).

src/main/java/org/junitpioneer/jupiter/RetryingTest.java

@@ -103,6 +103,13 @@
 	 */
 	int minSuccess() default 1;
 
+	/**
+	 * Specifies a pause (in milliseconds) between executions.
+	 *
+	 * Value must be greater than or equal to 0.
+	 */
+	int suspendForMs() default 0;
+
 	/**
 	 * Specifies on which exceptions a failed test is retried.
 	 *

src/main/java/org/junitpioneer/jupiter/RetryingTestExtension.java

@@ -19,6 +19,7 @@
 import java.util.Arrays;
 import java.util.Iterator;
 import java.util.NoSuchElementException;
+import java.util.concurrent.TimeUnit;
 import java.util.stream.Stream;
 
 import org.junit.jupiter.api.extension.ExtensionContext;
@@ -71,16 +72,19 @@ private static class FailedTestRetrier implements Iterator<RetryingTestInvocatio
 
 		private final int maxRetries;
 		private final int minSuccess;
+		private final int suspendForMs;
 		private final Class<? extends Throwable>[] expectedExceptions;
 
 		private int retriesSoFar;
 		private int exceptionsSoFar;
 		private boolean seenFailedAssumption;
 		private boolean seenUnexpectedException;
 
-		private FailedTestRetrier(int maxRetries, int minSuccess, Class<? extends Throwable>[] expectedExceptions) {
+		private FailedTestRetrier(int maxRetries, int minSuccess, int suspendForMs,
+				Class<? extends Throwable>[] expectedExceptions) {
 			this.maxRetries = maxRetries;
 			this.minSuccess = minSuccess;
+			this.suspendForMs = suspendForMs;
 			this.expectedExceptions = expectedExceptions;
 			this.retriesSoFar = 0;
 			this.exceptionsSoFar = 0;
@@ -112,7 +116,13 @@ else if (maxAttempts <= minSuccess) {
 						minSuccess == 1 ? "1" : "`minSuccess`", additionalMessage));
 			}
 
-			return new FailedTestRetrier(maxAttempts, minSuccess, retryingTest.onExceptions());
+			if (retryingTest.suspendForMs() < 0) {
+				throw new IllegalStateException(
+					"@RetryingTest requires that `suspendForMs` be greater than or equal to 0.");
+			}
+
+			return new FailedTestRetrier(maxAttempts, minSuccess, retryingTest.suspendForMs(),
+				retryingTest.onExceptions());
 		}
 
 		void failed(Throwable exception) throws Throwable {
@@ -131,7 +141,8 @@ void failed(Throwable exception) throws Throwable {
 
 			if (hasNext())
 				throw new TestAbortedException(
-					format("Test execution #%d (of up to %d) failed ~> will retry...", retriesSoFar, maxRetries),
+					format("Test execution #%d (of up to %d) failed ~> will retry in %d ms...", retriesSoFar,
+						maxRetries, suspendForMs),
 					exception);
 			else
 				throw new AssertionFailedError(format(
@@ -147,6 +158,20 @@ private boolean expectedException(Throwable exception) {
 			return Arrays.stream(expectedExceptions).anyMatch(type -> type.isInstance(exception));
 		}
 
+		private void suspendFor(int millis) {
+			if (millis < 1) {
+				return;
+			}
+
+			try {
+				TimeUnit.MILLISECONDS.sleep(millis);
+			}
+			catch (InterruptedException e) {
+				Thread.currentThread().interrupt();
+				throw new IllegalStateException("Cannot suspend execution after retry", e);
+			}
+		}
+
 		@Override
 		public boolean hasNext() {
 			// there's always at least one execution
@@ -167,6 +192,9 @@ public RetryingTestInvocationContext next() {
 			if (!hasNext())
 				throw new NoSuchElementException();
 			retriesSoFar++;
+
+			suspendFor(suspendForMs);
+
 			return new RetryingTestInvocationContext();
 		}
 

src/test/java/org/junitpioneer/jupiter/RetryingTestExtensionTests.java

@@ -18,16 +18,24 @@
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import java.time.Duration;
+import java.time.Instant;
+import java.util.List;
 
+import org.assertj.core.api.Assertions;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.TestInstance;
 import org.junit.jupiter.api.TestTemplate;
+import org.junit.platform.testkit.engine.Execution;
 import org.junitpioneer.testkit.ExecutionResults;
 import org.junitpioneer.testkit.PioneerTestKit;
 import org.opentest4j.TestAbortedException;
 
 class RetryingTestExtensionTests {
 
+	private static final int SUSPEND_FOR = 200;
+	private static final long SUSPEND_FOR_ERROR_MARGIN = 30L;
+
 	@Test
 	void invalidConfigurationWithTest() {
 		ExecutionResults results = PioneerTestKit
@@ -220,6 +228,63 @@ void minSuccessLessThanOne_fails() {
 		assertThat(results).hasNumberOfDynamicallyRegisteredTests(0);
 	}
 
+	@Test
+	void suspendForLessThanZero_fails() {
+		ExecutionResults results = PioneerTestKit
+				.executeTestMethod(RetryingTestTestCases.class, "suspendForLessThanZero");
+
+		assertThat(results).hasNumberOfDynamicallyRegisteredTests(0);
+	}
+
+	@Test
+	void failThreeTimesWithSuspend() {
+		ExecutionResults results = PioneerTestKit
+				.executeTestMethod(RetryingTestTestCases.class, "failThreeTimesWithSuspend");
+
+		assertThat(results)
+				.hasNumberOfDynamicallyRegisteredTests(3)
+				.hasNumberOfAbortedTests(2)
+				.hasNumberOfFailedTests(1)
+				.hasNumberOfSucceededTests(0);
+
+		assertSuspendedForCloseTo(results, SUSPEND_FOR);
+	}
+
+	@Test
+	void failThreeTimesWithoutSuspend() {
+		ExecutionResults results = PioneerTestKit
+				.executeTestMethod(RetryingTestTestCases.class, "failThreeTimesWithoutSuspend");
+
+		assertThat(results)
+				.hasNumberOfDynamicallyRegisteredTests(3)
+				.hasNumberOfAbortedTests(2)
+				.hasNumberOfFailedTests(1)
+				.hasNumberOfSucceededTests(0);
+
+		assertSuspendedForCloseTo(results, 0);
+	}
+
+	private void assertSuspendedForCloseTo(ExecutionResults results, long closeTo) {
+		List<Execution> finishedExecutions = results.testEvents().executions().finished().list();
+		List<Execution> startedExecutions = results.testEvents().executions().started().list();
+
+		// Compare 'finished' execution timestamp with follow-up 'started' execution,
+		// skipping the 1st 'started' and final 'finished'.
+		// This duration should be close to 'suspendFor'.
+		for (int i = 0; i < finishedExecutions.size() - 1; i++) {
+			Execution finished = finishedExecutions.get(i);
+			Execution nextStarted = startedExecutions.get(i + 1);
+
+			Instant finishedAt = finished.getEndInstant();
+			Instant nextStartedAt = nextStarted.getStartInstant();
+
+			long suspendedFor = Duration.between(finishedAt, nextStartedAt).toMillis();
+
+			// We allow an error margin since testing timings is not an exact science.
+			Assertions.assertThat(suspendedFor).isCloseTo(closeTo, Assertions.within(SUSPEND_FOR_ERROR_MARGIN));
+		}
+	}
+
 	// TEST CASES -------------------------------------------------------------------
 
 	// Some tests require state to keep track of the number of test executions.
@@ -363,6 +428,21 @@ void minSuccessLessThanOne() {
 			// Do nothing
 		}
 
+		@RetryingTest(suspendForMs = -1)
+		void suspendForLessThanZero() {
+			// Do nothing
+		}
+
+		@RetryingTest(maxAttempts = 3, suspendForMs = SUSPEND_FOR)
+		void failThreeTimesWithSuspend() {
+			throw new IllegalArgumentException();
+		}
+
+		@RetryingTest(maxAttempts = 3)
+		void failThreeTimesWithoutSuspend() {
+			throw new IllegalArgumentException();
+		}
+
 	}
 
 	@Target({ METHOD, ANNOTATION_TYPE })