From 54a6c1f598929130a0becb990dc5f1fd8474fe59 Mon Sep 17 00:00:00 2001 From: 2897robo <2897robo@gmail.com> Date: Mon, 12 May 2025 13:04:52 +0900 Subject: [PATCH 1/6] Add example usage of @Execution annotation for parallel test execution Issue: #2669 --- .../asciidoc/user-guide/writing-tests.adoc | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index b9c86dbb8a89..377ad94586c0 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -3195,6 +3195,28 @@ execution order. Thus, in both cases, test methods in such test classes are only concurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or method. +==== Using @Execution Annotation + +You can use the `@Execution` annotation to explicitly configure concurrent execution for a test class or method: + +[source,java] +---- +import org.junit.jupiter.api.parallel.Execution; +import org.junit.jupiter.api.parallel.ExecutionMode; + +@Execution(ExecutionMode.CONCURRENT) +class MyParallelTests { + + @Test + void testA() { ... } + + @Test + void testB() { ... } +} +---- + +This allows test classes or methods to opt-in to parallel execution even when the default is `same_thread`. + When parallel execution is enabled and a default `{ClassOrderer}` is registered (see <> for details), top-level test classes will initially be sorted accordingly and scheduled in that order. However, they are not @@ -3284,6 +3306,36 @@ used instead. [[writing-tests-parallel-execution-config]] ==== Configuration +[cols="3,6,2,1", options="header"] +|=== +| Property | Description | Possible Values | Default + +| junit.jupiter.execution.parallel.enabled +| Enables parallel test execution +| true, false +| false + +| junit.jupiter.execution.parallel.mode.default +| Execution mode for test elements +| same_thread, concurrent +| same_thread + +| junit.jupiter.execution.parallel.mode.classes.default +| Execution mode for test classes +| same_thread, concurrent +| same_thread + +| junit.jupiter.execution.parallel.config.strategy +| Strategy for configuring thread pool +| dynamic, fixed, custom +| dynamic + +| junit.jupiter.execution.parallel.config.fixed.parallelism +| Thread count for fixed strategy +| Integer (e.g., 4) +| none +|=== + Properties such as the desired parallelism and the maximum pool size can be configured using a `{ParallelExecutionConfigurationStrategy}`. The JUnit Platform provides two implementations out of the box: `dynamic` and `fixed`. Alternatively, you may implement a From 09256c5c4651ff8a1cbd036104c7d489a95e0006 Mon Sep 17 00:00:00 2001 From: 2897robo <2897robo@gmail.com> Date: Mon, 19 May 2025 00:27:30 +0900 Subject: [PATCH 2/6] Refactor: Extract @Execution example to external file and update doc accordingly --- .../asciidoc/user-guide/writing-tests.adoc | 45 +------------------ .../example/ExplicitExecutionModeDemo.java | 20 +++++++++ 2 files changed, 21 insertions(+), 44 deletions(-) create mode 100644 documentation/src/test/java/example/ExplicitExecutionModeDemo.java diff --git a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc index 377ad94586c0..fb47794d83b9 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -3195,24 +3195,11 @@ execution order. Thus, in both cases, test methods in such test classes are only concurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or method. -==== Using @Execution Annotation - You can use the `@Execution` annotation to explicitly configure concurrent execution for a test class or method: [source,java] ---- -import org.junit.jupiter.api.parallel.Execution; -import org.junit.jupiter.api.parallel.ExecutionMode; - -@Execution(ExecutionMode.CONCURRENT) -class MyParallelTests { - - @Test - void testA() { ... } - - @Test - void testB() { ... } -} +include::{testDir}/example/ExplicitExecutionModeDemo.java[] ---- This allows test classes or methods to opt-in to parallel execution even when the default is `same_thread`. @@ -3306,36 +3293,6 @@ used instead. [[writing-tests-parallel-execution-config]] ==== Configuration -[cols="3,6,2,1", options="header"] -|=== -| Property | Description | Possible Values | Default - -| junit.jupiter.execution.parallel.enabled -| Enables parallel test execution -| true, false -| false - -| junit.jupiter.execution.parallel.mode.default -| Execution mode for test elements -| same_thread, concurrent -| same_thread - -| junit.jupiter.execution.parallel.mode.classes.default -| Execution mode for test classes -| same_thread, concurrent -| same_thread - -| junit.jupiter.execution.parallel.config.strategy -| Strategy for configuring thread pool -| dynamic, fixed, custom -| dynamic - -| junit.jupiter.execution.parallel.config.fixed.parallelism -| Thread count for fixed strategy -| Integer (e.g., 4) -| none -|=== - Properties such as the desired parallelism and the maximum pool size can be configured using a `{ParallelExecutionConfigurationStrategy}`. The JUnit Platform provides two implementations out of the box: `dynamic` and `fixed`. Alternatively, you may implement a diff --git a/documentation/src/test/java/example/ExplicitExecutionModeDemo.java b/documentation/src/test/java/example/ExplicitExecutionModeDemo.java new file mode 100644 index 000000000000..c20c6cefeed6 --- /dev/null +++ b/documentation/src/test/java/example/ExplicitExecutionModeDemo.java @@ -0,0 +1,20 @@ +package example; + +import org.junit.jupiter.api.Test; +import org.junit.jupiter.api.parallel.Execution; +import org.junit.jupiter.api.parallel.ExecutionMode; + +@Execution(ExecutionMode.CONCURRENT) +class ExplicitExecutionModeDemo { + + @Test + void testA() { + // concurrent + } + + @Test + @Execution(ExecutionMode.SAME_THREAD) + void testB() { + // overrides to same_thread + } +} \ No newline at end of file From fea623a37756a85e308670af189eade01a71b8a3 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 19 May 2025 12:25:36 +0200 Subject: [PATCH 3/6] Update documentation/src/docs/asciidoc/user-guide/writing-tests.adoc --- documentation/src/docs/asciidoc/user-guide/writing-tests.adoc | 3 ++- 1 file changed, 2 insertions(+), 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 1785aa6f6356..a1957b29f327 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -3195,7 +3195,8 @@ execution order. Thus, in both cases, test methods in such test classes are only concurrently if the `@Execution(CONCURRENT)` annotation is present on the test class or method. -You can use the `@Execution` annotation to explicitly configure concurrent execution for a test class or method: +You can use the `@Execution` annotation to explicitly configure the execution mode for a +test class or method: [source,java] ---- From 4b3f4a7e81126da44d2f819ff25fe7598152c117 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 19 May 2025 12:27:07 +0200 Subject: [PATCH 4/6] Update documentation/src/docs/asciidoc/user-guide/writing-tests.adoc --- documentation/src/docs/asciidoc/user-guide/writing-tests.adoc | 3 ++- 1 file changed, 2 insertions(+), 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 a1957b29f327..10993f42ad88 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -3203,7 +3203,8 @@ test class or method: include::{testDir}/example/ExplicitExecutionModeDemo.java[] ---- -This allows test classes or methods to opt-in to parallel execution even when the default is `same_thread`. +This allows test classes or methods to opt in or out of parallel execution regardless of +the globally configured default. When parallel execution is enabled and a default `{ClassOrderer}` is registered (see <> for details), top-level test classes will From 80661703ce023ab2fc8905c48c4da69a03c29536 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 19 May 2025 12:27:41 +0200 Subject: [PATCH 5/6] Update documentation/src/docs/asciidoc/user-guide/writing-tests.adoc --- 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 10993f42ad88..0c4f39c92816 100644 --- a/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc +++ b/documentation/src/docs/asciidoc/user-guide/writing-tests.adoc @@ -3203,7 +3203,7 @@ test class or method: include::{testDir}/example/ExplicitExecutionModeDemo.java[] ---- -This allows test classes or methods to opt in or out of parallel execution regardless of +This allows test classes or methods to opt in or out of concurrent execution regardless of the globally configured default. When parallel execution is enabled and a default `{ClassOrderer}` is registered (see From aa123dbe303f70615a1cb4d26769d47ffca79848 Mon Sep 17 00:00:00 2001 From: Marc Philipp Date: Mon, 19 May 2025 12:28:58 +0200 Subject: [PATCH 6/6] Fix formatting --- .../test/java/example/ExplicitExecutionModeDemo.java | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/documentation/src/test/java/example/ExplicitExecutionModeDemo.java b/documentation/src/test/java/example/ExplicitExecutionModeDemo.java index c20c6cefeed6..83735b7b8419 100644 --- a/documentation/src/test/java/example/ExplicitExecutionModeDemo.java +++ b/documentation/src/test/java/example/ExplicitExecutionModeDemo.java @@ -1,3 +1,13 @@ +/* + * Copyright 2015-2025 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.Test; @@ -17,4 +27,4 @@ void testA() { void testB() { // overrides to same_thread } -} \ No newline at end of file +}