Added suspendForMs to @RetryingTest

docs/retrying-test.adoc

@@ -31,6 +31,8 @@ The default for `minSuccess` is 1. The value must be greater than or equal to 1.
 
 The `suspendForMs` attribute specifies the amount of time to pause between retries, in milliseconds.
 
+The thread executing this test is sleeping during that time and won't execute other tests, so long suspensions are discouraged.
+
 The default for `suspendForMs` is 0 (no pause). The value must be greater than or equal to 0.
 
 === onExceptions [optional]
@@ -97,6 +99,17 @@ include::{demo}[tag=retrying_configure_numbers_of_success]
 The test `requiresTwoSuccesses` must run at least two times without raising an exception.
 However, it will not run more than four times.
 
+=== Suspending between each Retry
+
+[source,java,indent=0]
+----
+include::{demo}[tag=suspending_between_each_retry]
+----
+
+Use `suspendForMs` to specify the number of milliseconds to wait between each retry.
+
+After failure, the test `suspendBetweenRetries` will wait for 100ms before retrying.
+
 === Configuring on which Exceptions to Retry
 
 Use `onExceptions` to only retry on the mentioned exception(s):

src/demo/java/org/junitpioneer/jupiter/RetryingTestExtensionDemo.java

@@ -49,6 +49,13 @@ void requiresTwoSuccesses() {
 	}
 	// end::retrying_configure_numbers_of_success[]
 
+	// tag::suspending_between_each_retry[]
+	@RetryingTest(maxAttempts = 3, suspendForMs = 100)
+	void suspendsBetweenRetries() {
+		// test code that will suspend/wait for 100 ms between retries
+	}
+	// end::suspending_between_each_retry[]
+
 	class TheseTestsWillFailIntentionally {
 
 		// tag::retrying_configure_exception_for_retry[]

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

@@ -145,7 +145,10 @@
 	/**
 	 * Specifies a pause (in milliseconds) between executions.
 	 *
-	 * Value must be greater than or equal to 0.
+	 * <p>The thread executing this test is sleeping during that time
+	 * and won't execute other tests, so long suspensions are discouraged.</p>
+	 *
+	 * <p>Value must be greater than or equal to 0.</p>
 	 */
 	int suspendForMs() default 0;
 

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

@@ -175,16 +175,20 @@ private void suspendFor(int millis) {
 			try {
 				TimeUnit.MILLISECONDS.sleep(millis);
 			}
-			catch (InterruptedException e) {
+			catch (InterruptedException ex) {
 				Thread.currentThread().interrupt();
-				throw new IllegalStateException("Cannot suspend execution after retry", e);
+				throw new IllegalStateException("Thread interrupted during retry suspension.", ex);
 			}
 		}
 
+		private boolean isFirstExecution() {
+			return retriesSoFar == 0;
+		}
+
 		@Override
 		public boolean hasNext() {
 			// there's always at least one execution
-			if (retriesSoFar == 0)
+			if (isFirstExecution())
 				return true;
 			if (seenFailedAssumption || seenUnexpectedException)
 				return false;
@@ -200,9 +204,12 @@ public boolean hasNext() {
 		public RetryingTestInvocationContext next() {
 			if (!hasNext())
 				throw new NoSuchElementException();
-			retriesSoFar++;
 
-			suspendFor(suspendForMs);
+			if (!isFirstExecution()) {
+				suspendFor(suspendForMs);
+			}
+
+			retriesSoFar++;
 
 			return new RetryingTestInvocationContext(formatter);
 		}

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

@@ -34,8 +34,7 @@
 
 class RetryingTestExtensionTests {
 
-	private static final int SUSPEND_FOR = 200;
-	private static final long SUSPEND_FOR_ERROR_MARGIN = 30L;
+	private static final int SUSPEND_FOR = 10;
 
 	@Test
 	void invalidConfigurationWithTest() {
@@ -279,7 +278,7 @@ void failThreeTimesWithSuspend() {
 				.hasNumberOfFailedTests(1)
 				.hasNumberOfSucceededTests(0);
 
-		assertSuspendedForCloseTo(results, SUSPEND_FOR);
+		assertSuspendedFor(results, SUSPEND_FOR);
 	}
 
 	@Test
@@ -293,16 +292,16 @@ void failThreeTimesWithoutSuspend() {
 				.hasNumberOfFailedTests(1)
 				.hasNumberOfSucceededTests(0);
 
-		assertSuspendedForCloseTo(results, 0);
+		assertSuspendedFor(results, 0);
 	}
 
-	private void assertSuspendedForCloseTo(ExecutionResults results, long closeTo) {
+	private void assertSuspendedFor(ExecutionResults results, long greaterThanOrEqualTo) {
 		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'.
+		// This duration should be equals to or greater than 'suspendFor'.
 		for (int i = 0; i < finishedExecutions.size() - 1; i++) {
 			Execution finished = finishedExecutions.get(i);
 			Execution nextStarted = startedExecutions.get(i + 1);
@@ -312,8 +311,7 @@ private void assertSuspendedForCloseTo(ExecutionResults results, long closeTo) {
 
 			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));
+			Assertions.assertThat(suspendedFor).isGreaterThanOrEqualTo(greaterThanOrEqualTo);
 		}
 	}