Provide mechanism for managing resources across engines and executions

documentation/src/docs/asciidoc/link-attributes.adoc

@@ -46,6 +46,7 @@ endif::[]
 :IterationSelector:                          {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/IterationSelector.html[IterationSelector]
 :MethodSelector:                             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/MethodSelector.html[MethodSelector]
 :ModuleSelector:                             {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/ModuleSelector.html[ModuleSelector]
+:NamespacedHierarchicalStore:                {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/support/store/NamespacedHierarchicalStore.html[NamespacedHierarchicalStore]
 :NestedClassSelector:                        {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/NestedClassSelector.html[NestedClassSelector]
 :NestedMethodSelector:                       {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/discovery/NestedMethodSelector.html[NestedMethodSelector]
 :OutputDirectoryProvider:                    {javadoc-root}/org.junit.platform.engine/org/junit/platform/engine/reporting/OutputDirectoryProvider.html[OutputDirectoryProvider]

documentation/src/docs/asciidoc/release-notes/release-notes-5.13.0-M3.adoc

@@ -26,7 +26,15 @@ repository on GitHub.
 [[release-notes-5.13.0-M3-junit-platform-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* Introduce resource management mechanism that allows preparing and sharing state across
+  executions or test engines via stores that are scoped to a `LauncherSession` or
+  `ExecutionRequest`. The Jupiter API uses these stores as ancestors to the `Store`
+  instances accessible via `ExtensionContext` and provides a new method to access them
+  directly. Please refer to the User Guide for examples of managing
+  <<../user-guide/index.adoc#launcher-api-launcher-session-listeners-tool-example-usage, session-scoped>>
+  and
+  <<../user-guide/index.adoc#launcher-api-managing-state-across-test-engines, request-scoped>>
+  resources.
 
 
 [[release-notes-5.13.0-M3-junit-jupiter]]

documentation/src/docs/asciidoc/user-guide/advanced-topics/launcher-api.adoc

@@ -1,3 +1,6 @@
+:testDir: ../../../../../src/test/java
+:testResourcesDir: ../../../../../src/test/resources
+
 [[launcher-api]]
 === JUnit Platform Launcher API
 
@@ -132,10 +135,22 @@ package example.session;
 
 include::{testDir}/example/session/GlobalSetupTeardownListener.java[tags=user_guide]
 ----
-<1> Start the HTTP server
-<2> Export its host address as a system property for consumption by tests
-<3> Export its port as a system property for consumption by tests
-<4> Stop the HTTP server
+<1> Get the store from the launcher session
+<2> Lazily create the HTTP server and put it into the store
+<3> Start the HTTP server
+
+It uses a wrapper class to ensure the server is stopped when the launcher session is
+closed:
+
+[source,java]
+.src/test/java/example/session/CloseableHttpServer.java
+----
+package example.session;
+
+include::{testDir}/example/session/CloseableHttpServer.java[tags=user_guide]
+----
+<1> The `close()` method is called when the launcher session is closed
+<2> Stop the HTTP server
 
 This sample uses the HTTP server implementation from the jdk.httpserver module that comes
 with the JDK but would work similarly with any other server or resource. In order for the
@@ -158,10 +173,11 @@ package example.session;
 
 include::{testDir}/example/session/HttpTests.java[tags=user_guide]
 ----
-<1> Read the host address of the server from the system property set by the listener
-<2> Read the port of the server from the system property set by the listener
-<3> Send a request to the server
-<4> Check the status code of the response
+<1> Retrieve the HTTP server instance from the store
+<2> Get the host string directly from the injected HTTP server instance
+<3> Get the port number directly from the injected HTTP server instance
+<4> Send a request to the server
+<5> Check the status code of the response
 
 [[launcher-api-launcher-interceptors-custom]]
 ==== Registering a LauncherInterceptor
@@ -285,3 +301,55 @@ execute any tests but will notify registered `{TestExecutionListener}` instances
 tests had been skipped and their containers had been successful. This can be useful to
 test changes in the configuration of a build or to verify a listener is called as expected
 without having to wait for all tests to be executed.
+
+[[launcher-api-managing-state-across-test-engines]]
+==== Managing State Across Test Engines
+
+When running tests on the JUnit Platform, multiple test engines may need to access shared
+resources. Rather than initializing these resources multiple times, JUnit Platform
+provides mechanisms to share state across test engines efficiently. Test engines can use
+the Platform's `{NamespacedHierarchicalStore}` API to lazily initialize and share
+resources, ensuring they are created only once regardless of execution order. Any resource
+that is put into the store and implements `AutoCloseable` will be closed automatically when
+the execution is finished.
+
+TIP: The Jupiter engine allows read and write access to such resources via its
+`{ExtensionContext_Store}` API.
+
+The following example demonstrates two custom test engines sharing a `ServerSocket`
+resource. `FirstCustomEngine` attempts to retrieve an existing `ServerSocket` from the
+global store or creates a new one if it doesn't exist:
+
+[source,java]
+----
+include::{testDir}/example/FirstCustomEngine.java[tags=user_guide]
+----
+
+`SecondCustomEngine` follows the same pattern, ensuring that regardless whether it runs
+before or after `FirstCustomEngine`, it will use the same socket instance:
+
+[source,java]
+----
+include::{testDir}/example/SecondCustomEngine.java[tags=user_guide]
+----
+
+TIP: In this case, the `ServerSocket` can be stored directly in the global store while
+ensuring since it gets closed because it implements `AutoCloseable`. If you need to use a
+type that does not do so, you can wrap it in a custom class that implements
+`AutoCloseable` and delegates to the original type. This is important to ensure that the
+resource is closed properly when the test run is finished.
+
+For illustration, the following test verifies that both engines are sharing the same
+`ServerSocket` instance and that it's closed after `Launcher.execute()` returns:
+
+[source,java,indent=0]
+----
+include::{testDir}/example/sharedresources/SharedResourceDemo.java[tags=user_guide]
+----
+
+By using the Platform's `{NamespacedHierarchicalStore}` API with shared namespaces in this
+way, test engines can coordinate resource creation and sharing without direct dependencies
+between them.
+
+Alternatively, it's possible to inject resources into test engines by
+<<launcher-api-launcher-session-listeners-custom, registering a `LauncherSessionListener`>>.

documentation/src/test/java/example/FirstCustomEngine.java

@@ -0,0 +1,68 @@
+/*
+ * 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;
+
+//tag::user_guide[]
+import static java.net.InetAddress.getLoopbackAddress;
+import static org.junit.platform.engine.TestExecutionResult.successful;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.net.ServerSocket;
+
+import org.junit.platform.engine.EngineDiscoveryRequest;
+import org.junit.platform.engine.ExecutionRequest;
+import org.junit.platform.engine.TestDescriptor;
+import org.junit.platform.engine.TestEngine;
+import org.junit.platform.engine.UniqueId;
+import org.junit.platform.engine.support.descriptor.EngineDescriptor;
+import org.junit.platform.engine.support.store.Namespace;
+import org.junit.platform.engine.support.store.NamespacedHierarchicalStore;
+
+/**
+ * First custom test engine implementation.
+ */
+public class FirstCustomEngine implements TestEngine {
+
+	public ServerSocket socket;
+
+	@Override
+	public String getId() {
+		return "first-custom-test-engine";
+	}
+
+	@Override
+	public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {
+		return new EngineDescriptor(uniqueId, "First Custom Test Engine");
+	}
+
+	@Override
+	public void execute(ExecutionRequest request) {
+		request.getEngineExecutionListener()
+				// tag::custom_line_break[]
+				.executionStarted(request.getRootTestDescriptor());
+
+		NamespacedHierarchicalStore<Namespace> store = request.getStore();
+		socket = store.getOrComputeIfAbsent(Namespace.GLOBAL, "serverSocket", key -> {
+			try {
+				return new ServerSocket(0, 50, getLoopbackAddress());
+			}
+			catch (IOException e) {
+				throw new UncheckedIOException("Failed to start ServerSocket", e);
+			}
+		}, ServerSocket.class);
+
+		request.getEngineExecutionListener()
+				// tag::custom_line_break[]
+				.executionFinished(request.getRootTestDescriptor(), successful());
+	}
+}
+//end::user_guide[]

documentation/src/test/java/example/SecondCustomEngine.java

@@ -0,0 +1,68 @@
+/*
+ * 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 static java.net.InetAddress.getLoopbackAddress;
+import static org.junit.platform.engine.TestExecutionResult.successful;
+
+import java.io.IOException;
+import java.io.UncheckedIOException;
+import java.net.ServerSocket;
+
+import org.junit.platform.engine.EngineDiscoveryRequest;
+import org.junit.platform.engine.ExecutionRequest;
+import org.junit.platform.engine.TestDescriptor;
+import org.junit.platform.engine.TestEngine;
+import org.junit.platform.engine.UniqueId;
+import org.junit.platform.engine.support.descriptor.EngineDescriptor;
+import org.junit.platform.engine.support.store.Namespace;
+import org.junit.platform.engine.support.store.NamespacedHierarchicalStore;
+
+//tag::user_guide[]
+/**
+ * Second custom test engine implementation.
+ */
+public class SecondCustomEngine implements TestEngine {
+
+	public ServerSocket socket;
+
+	@Override
+	public String getId() {
+		return "second-custom-test-engine";
+	}
+
+	@Override
+	public TestDescriptor discover(EngineDiscoveryRequest discoveryRequest, UniqueId uniqueId) {
+		return new EngineDescriptor(uniqueId, "Second Custom Test Engine");
+	}
+
+	@Override
+	public void execute(ExecutionRequest request) {
+		request.getEngineExecutionListener()
+				// tag::custom_line_break[]
+				.executionStarted(request.getRootTestDescriptor());
+
+		NamespacedHierarchicalStore<Namespace> store = request.getStore();
+		socket = store.getOrComputeIfAbsent(Namespace.GLOBAL, "serverSocket", key -> {
+			try {
+				return new ServerSocket(0, 50, getLoopbackAddress());
+			}
+			catch (IOException e) {
+				throw new UncheckedIOException("Failed to start ServerSocket", e);
+			}
+		}, ServerSocket.class);
+
+		request.getEngineExecutionListener()
+				// tag::custom_line_break[]
+				.executionFinished(request.getRootTestDescriptor(), successful());
+	}
+}
+//end::user_guide[]

documentation/src/test/java/example/session/CloseableHttpServer.java

@@ -0,0 +1,38 @@
+/*
+ * 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.session;
+
+//tag::user_guide[]
+import java.util.concurrent.ExecutorService;
+
+import com.sun.net.httpserver.HttpServer;
+
+public class CloseableHttpServer implements AutoCloseable {
+
+	private final HttpServer server;
+	private final ExecutorService executorService;
+
+	CloseableHttpServer(HttpServer server, ExecutorService executorService) {
+		this.server = server;
+		this.executorService = executorService;
+	}
+
+	public HttpServer getServer() {
+		return server;
+	}
+
+	@Override
+	public void close() { // <1>
+		server.stop(0); // <2>
+		executorService.shutdownNow();
+	}
+}
+//end::user_guide[]

documentation/src/test/java/example/session/GlobalSetupTeardownListener.java

@@ -21,15 +21,15 @@
 
 import com.sun.net.httpserver.HttpServer;
 
+import org.junit.platform.engine.support.store.Namespace;
+import org.junit.platform.engine.support.store.NamespacedHierarchicalStore;
 import org.junit.platform.launcher.LauncherSession;
 import org.junit.platform.launcher.LauncherSessionListener;
 import org.junit.platform.launcher.TestExecutionListener;
 import org.junit.platform.launcher.TestPlan;
 
 public class GlobalSetupTeardownListener implements LauncherSessionListener {
 
-	private Fixture fixture;
-
 	@Override
 	public void launcherSessionOpened(LauncherSession session) {
 		// Avoid setup for test discovery by delaying it until tests are about to be executed
@@ -42,50 +42,28 @@ public void testPlanExecutionStarted(TestPlan testPlan) {
 					return;
 				}
 				//tag::user_guide[]
-				if (fixture == null) {
-					fixture = new Fixture();
-					fixture.setUp();
-				}
-			}
-		});
-	}
+				NamespacedHierarchicalStore<Namespace> store = session.getStore(); // <1>
+				store.getOrComputeIfAbsent(Namespace.GLOBAL, "httpServer", key -> { // <2>
+					InetSocketAddress address = new InetSocketAddress(getLoopbackAddress(), 0);
+					HttpServer server;
+					try {
+						server = HttpServer.create(address, 0);
+					}
+					catch (IOException e) {
+						throw new UncheckedIOException("Failed to start HTTP server", e);
+					}
+					server.createContext("/test", exchange -> {
+						exchange.sendResponseHeaders(204, -1);
+						exchange.close();
+					});
+					ExecutorService executorService = Executors.newCachedThreadPool();
+					server.setExecutor(executorService);
+					server.start(); // <3>
 
-	@Override
-	public void launcherSessionClosed(LauncherSession session) {
-		if (fixture != null) {
-			fixture.tearDown();
-			fixture = null;
-		}
-	}
-
-	static class Fixture {
-
-		private HttpServer server;
-		private ExecutorService executorService;
-
-		void setUp() {
-			try {
-				server = HttpServer.create(new InetSocketAddress(getLoopbackAddress(), 0), 0);
+					return new CloseableHttpServer(server, executorService);
+				});
 			}
-			catch (IOException e) {
-				throw new UncheckedIOException("Failed to start HTTP server", e);
-			}
-			server.createContext("/test", exchange -> {
-				exchange.sendResponseHeaders(204, -1);
-				exchange.close();
-			});
-			executorService = Executors.newCachedThreadPool();
-			server.setExecutor(executorService);
-			server.start(); // <1>
-			int port = server.getAddress().getPort();
-			System.setProperty("http.server.host", getLoopbackAddress().getHostAddress()); // <2>
-			System.setProperty("http.server.port", String.valueOf(port)); // <3>
-		}
-
-		void tearDown() {
-			server.stop(0); // <4>
-			executorService.shutdownNow();
-		}
+		});
 	}
 
 }