From 387a795e2b59e43d1df92a12fbd587930ca65f4e Mon Sep 17 00:00:00 2001 From: Romain Manni-Bucau Date: Wed, 12 Jun 2019 15:44:49 +0200 Subject: [PATCH 1/4] adding an example of @Timeout usage for 'wait until' logic in tests --- .../asciidoc/user-guide/writing-tests.adoc | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index abe9402f4340..61872b1f0036 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -1659,6 +1659,25 @@ omitted. Specifying no unit is equivalent to using seconds. | `42 d` | `@Timeout(value = 42, unit = DAYS)` |=== +==== Use @Timeout for polling tests + +It is common to write tests waiting for some updates. +In some cases you can rewrite the logic to use a `CountDownLatch` or any other synchronization mecanism but sometimes it is not possible - generally when depending on an external system. +These tests require some timeout to ensure they don't hang the test suite forever and the test fails if the waiting condition "never" happens. +With `@Timeout` it becomes very easy to write such tests since the test itself just require to become an infinite loop: + +[source,java] +---- +@Timeout(5) // 5s +void waitUntil() { + while (!isConditionTrue()) { + sleep(250); // use some adapted retry duration + } + // if needed asserts on the result of the awaited condition +} +---- + +Such a simple usage enables to implement "test when" or "wait until" logic very easily. [[writing-tests-parallel-execution]] === Parallel Execution From 0744bcdc9de71153b938737530ba84bf0c8d2928 Mon Sep 17 00:00:00 2001 From: Romain Manni-Bucau Date: Fri, 28 Jun 2019 14:52:58 +0200 Subject: [PATCH 2/4] extracting polling sample in a class to compile it + adding a sentence about Awaitility --- .../asciidoc/user-guide/writing-tests.adoc | 21 +++++++------- .../src/test/java/example/PollingTimeout.java | 29 +++++++++++++++++++ 2 files changed, 40 insertions(+), 10 deletions(-) create mode 100644 documentation/src/test/java/example/PollingTimeout.java diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 61872b1f0036..018431861a01 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -1,5 +1,6 @@ [[writing-tests]] == Writing Tests +:testDir: /media/data/home/rmannibucau/1_dev/junit5/documentation/src/test/java The following example provides a glimpse at the minimum requirements for writing a test in JUnit Jupiter. Subsequent sections of this chapter will provide further details on all @@ -1662,23 +1663,23 @@ omitted. Specifying no unit is equivalent to using seconds. ==== Use @Timeout for polling tests It is common to write tests waiting for some updates. -In some cases you can rewrite the logic to use a `CountDownLatch` or any other synchronization mecanism but sometimes it is not possible - generally when depending on an external system. -These tests require some timeout to ensure they don't hang the test suite forever and the test fails if the waiting condition "never" happens. -With `@Timeout` it becomes very easy to write such tests since the test itself just require to become an infinite loop: +In some cases you can rewrite the logic to use a `CountDownLatch` or any other synchronization +mecanism but sometimes it is not possible - generally when depending on an external system. +These tests require some timeout to ensure they don't hang the test suite forever and +the test fails if the waiting condition "never" happens. +With `@Timeout` it becomes very easy to write such tests since the test itself just require +to become an infinite loop: [source,java] ---- -@Timeout(5) // 5s -void waitUntil() { - while (!isConditionTrue()) { - sleep(250); // use some adapted retry duration - } - // if needed asserts on the result of the awaited condition -} +include::{testDir}/example/PollingTimeout.java[tags=user_guide,indent=0] ---- Such a simple usage enables to implement "test when" or "wait until" logic very easily. +Alternatively, you can use a library handling for you the awaiting like the well-known +link:https://github.com/awaitility/awaitility[Awaitility]. + [[writing-tests-parallel-execution]] === Parallel Execution diff --git a/documentation/src/test/java/example/PollingTimeout.java b/documentation/src/test/java/example/PollingTimeout.java new file mode 100644 index 000000000000..a27ac7a0c314 --- /dev/null +++ b/documentation/src/test/java/example/PollingTimeout.java @@ -0,0 +1,29 @@ +/* + * Copyright 2015-2019 the original author or authors. + * + * All rights reserved. This program and the accompanying materials are + * made available under the terms of the Eclipse Public License v2.0 which + * accompanies this distribution and is available at + * + * https://www.eclipse.org/legal/epl-v20.html + */ + +package example; + +import org.junit.jupiter.api.Timeout; + +class PollingTimeout { + // tag::user_guide[] + @Timeout(5) // 5s + void waitUntil() throws InterruptedException { + while (!isConditionTrue()) { + Thread.sleep(250); // use some adapted retry duration + } + // if needed asserts on the result of the awaited condition + } + // end::user_guide[] + + private boolean isConditionTrue() { + return true; + } +} From 2e839e52f410e71a65443055cb1aa47b76f22e68 Mon Sep 17 00:00:00 2001 From: Romain Manni-Bucau Date: Fri, 28 Jun 2019 16:52:29 +0200 Subject: [PATCH 3/4] oops, dev attribute should have been dropped --- documentation/src/docs/asciidoc/user-guide/writing-tests.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 018431861a01..4dc3ec5c91d1 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -1,6 +1,5 @@ [[writing-tests]] == Writing Tests -:testDir: /media/data/home/rmannibucau/1_dev/junit5/documentation/src/test/java The following example provides a glimpse at the minimum requirements for writing a test in JUnit Jupiter. Subsequent sections of this chapter will provide further details on all From 30ea6acbea6944fed39eaf8c2d622c522bce9806 Mon Sep 17 00:00:00 2001 From: Romain Manni-Bucau Date: Fri, 28 Jun 2019 17:13:32 +0200 Subject: [PATCH 4/4] typo on mechanism --- documentation/src/docs/asciidoc/user-guide/writing-tests.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 4dc3ec5c91d1..d43113b851ae 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -1663,7 +1663,7 @@ omitted. Specifying no unit is equivalent to using seconds. It is common to write tests waiting for some updates. In some cases you can rewrite the logic to use a `CountDownLatch` or any other synchronization -mecanism but sometimes it is not possible - generally when depending on an external system. +mechanism but sometimes it is not possible - generally when depending on an external system. These tests require some timeout to ensure they don't hang the test suite forever and the test fails if the waiting condition "never" happens. With `@Timeout` it becomes very easy to write such tests since the test itself just require