Introduce BeforeSuite and AfterSuite annotations for Suite classes

These new lifecycle callback method can be used to run code before the 
first and after the last test in the suite.

Resolves #456.

Co-authored-by: Marc Philipp <mail@marcphilipp.de>

documentation/src/docs/asciidoc/release-notes/release-notes-5.11.0-RC1.adoc

@@ -33,6 +33,7 @@ repository on GitHub.
   exception's _root_ cause matches all supplied conditions, for use with the
   `EngineTestKit`.
 * `ReflectionSupport` now supports scanning for classpath resources.
+* Introduce `@BeforeSuite` and `@AfterSuite` annotations.
 
 
 [[release-notes-5.11.0-RC1-junit-jupiter]]

documentation/src/docs/asciidoc/user-guide/advanced-topics/junit-platform-suite-engine.adoc

@@ -48,3 +48,14 @@ include::{testDir}/example/SuiteDemo.java[tags=user_guide]
 NOTE: There are numerous configuration options for discovering and filtering tests in a
 test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full
 list of supported annotations and further details.
+
+==== @BeforeSuite and @AfterSuite
+
+`@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a
+`@Suite`-annotated class. They will be executed respectively before and after
+all tests of the test suite.
+
+[source,java,indent=0]
+----
+include::{testDir}/example/BeforeAndAfterSuiteDemo.java[tags=user_guide]
+----

documentation/src/test/java/example/BeforeAndAfterSuiteDemo.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2015-2024 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.platform.suite.api.AfterSuite;
+import org.junit.platform.suite.api.BeforeSuite;
+import org.junit.platform.suite.api.SelectPackages;
+import org.junit.platform.suite.api.Suite;
+
+//tag::user_guide[]
+@Suite
+@SelectPackages("example")
+class BeforeAndAfterSuiteDemo {
+
+	@BeforeSuite
+	static void beforeSuite() {
+		// executes before the test suite
+	}
+
+	@AfterSuite
+	static void afterSuite() {
+		// executes after the test suite
+	}
+
+}
+//end::user_guide[]

junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/AfterSuite.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2015-2024 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 org.junit.platform.suite.api;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@code @AfterSuite} is used to signal that the annotated method should be
+ * executed <em>after</em> <strong>all</strong> tests in the current test suite.
+ *
+ * <h2>Method Signatures</h2>
+ *
+ * <p>{@code @AfterSuite} methods must have a {@code void} return type, must
+ * be {@code static} and must not be {@code private}.
+ *
+ * <h2>Inheritance and Execution Order</h2>
+ *
+ * <p>{@code @AfterSuite} methods are inherited from superclasses as long as they
+ * are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Furthermore, {@code @AfterSuite} methods from superclasses will be
+ * executed after {@code @AfterSuite} methods in subclasses.
+ *
+ * <p>The JUnit Platform Suite Engine does not guarantee the execution order of
+ * multiple {@code @AfterSuite} methods that are declared within a single test
+ * class or test interface. While it may at times appear that these methods are
+ * invoked in alphabetical order, they are in fact sorted using an algorithm
+ * that is deterministic but intentionally non-obvious.
+ *
+ * <p>In addition, {@code @AfterSuite} methods are in no way linked to
+ * {@code @BeforeSuite} methods. Consequently, there are no guarantees with regard
+ * to their <em>wrapping</em> behavior. For example, given two
+ * {@code @BeforeSuite} methods {@code createA()} and {@code createB()} as well as
+ * two {@code @AfterSuite} methods {@code destroyA()} and {@code destroyB()}, the
+ * order in which the {@code @BeforeSuite} methods are executed (e.g.
+ * {@code createA()} before {@code createB()}) does not imply any order for the
+ * seemingly corresponding {@code @AfterSuite} methods. In other words,
+ * {@code destroyA()} might be called before <em>or</em> after
+ * {@code destroyB()}. The JUnit Team therefore recommends that developers
+ * declare at most one {@code @BeforeSuite} method and at most one
+ * {@code @AfterSuite} method per test class or test interface unless there are no
+ * dependencies between the {@code @BeforeSuite} methods or between the
+ * {@code @AfterSuite} methods.
+ *
+ * <h2>Composition</h2>
+ *
+ * <p>{@code @AfterSuite} may be used as a meta-annotation in order to create
+ * a custom <em>composed annotation</em> that inherits the semantics of
+ * {@code @AfterSuite}.
+ *
+ * @since 1.11
+ * @see BeforeSuite
+ * @see Suite
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@API(status = EXPERIMENTAL, since = "1.11")
+public @interface AfterSuite {
+}

junit-platform-suite-api/src/main/java/org/junit/platform/suite/api/BeforeSuite.java

@@ -0,0 +1,75 @@
+/*
+ * Copyright 2015-2024 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 org.junit.platform.suite.api;
+
+import static org.apiguardian.api.API.Status.EXPERIMENTAL;
+
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+import org.apiguardian.api.API;
+
+/**
+ * {@code @BeforeSuite} is used to signal that the annotated method should be
+ * executed <em>before</em> <strong>all</strong> tests in the current test suite.
+ *
+ * <h2>Method Signatures</h2>
+ *
+ * <p>{@code @BeforeSuite} methods must have a {@code void} return type, must
+ * be {@code static} and must not be {@code private}.
+ *
+ * <h2>Inheritance and Execution Order</h2>
+ *
+ * <p>{@code @BeforeSuite} methods are inherited from superclasses as long as they
+ * are not <em>overridden</em> according to the visibility rules of the Java
+ * language. Furthermore, {@code @BeforeSuite} methods from superclasses will be
+ * executed before {@code @BeforeSuite} methods in subclasses.
+ *
+ * <p>The JUnit Platform Suite Engine does not guarantee the execution order of
+ * multiple {@code @BeforeSuite} methods that are declared within a single test
+ * class or test interface. While it may at times appear that these methods are
+ * invoked in alphabetical order, they are in fact sorted using an algorithm
+ * that is deterministic but intentionally non-obvious.
+ *
+ * <p>In addition, {@code @BeforeSuite} methods are in no way linked to
+ * {@code @AfterSuite} methods. Consequently, there are no guarantees with regard
+ * to their <em>wrapping</em> behavior. For example, given two
+ * {@code @BeforeSuite} methods {@code createA()} and {@code createB()} as well as
+ * two {@code @AfterSuite} methods {@code destroyA()} and {@code destroyB()}, the
+ * order in which the {@code @BeforeSuite} methods are executed (e.g.
+ * {@code createA()} before {@code createB()}) does not imply any order for the
+ * seemingly corresponding {@code @AfterSuite} methods. In other words,
+ * {@code destroyA()} might be called before <em>or</em> after
+ * {@code destroyB()}. The JUnit Team therefore recommends that developers
+ * declare at most one {@code @BeforeSuite} method and at most one
+ * {@code @AfterSuite} method per test class or test interface unless there are no
+ * dependencies between the {@code @BeforeSuite} methods or between the
+ * {@code @AfterSuite} methods.
+ *
+ * <h2>Composition</h2>
+ *
+ * <p>{@code @BeforeSuite} may be used as a meta-annotation in order to create
+ * a custom <em>composed annotation</em> that inherits the semantics of
+ * {@code @BeforeSuite}.
+ *
+ * @since 1.11
+ * @see AfterSuite
+ * @see Suite
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+@Documented
+@API(status = EXPERIMENTAL, since = "1.11")
+public @interface BeforeSuite {
+}

junit-platform-suite-engine/src/main/java/org/junit/platform/suite/engine/LifecycleMethodUtils.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2015-2024 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 org.junit.platform.suite.engine;
+
+import static org.junit.platform.commons.util.AnnotationUtils.findAnnotatedMethods;
+import static org.junit.platform.commons.util.ReflectionUtils.returnsPrimitiveVoid;
+
+import java.lang.annotation.Annotation;
+import java.lang.reflect.Method;
+import java.util.List;
+
+import org.junit.platform.commons.JUnitException;
+import org.junit.platform.commons.util.ReflectionUtils;
+import org.junit.platform.commons.util.ReflectionUtils.HierarchyTraversalMode;
+import org.junit.platform.engine.support.hierarchical.ThrowableCollector;
+import org.junit.platform.suite.api.AfterSuite;
+import org.junit.platform.suite.api.BeforeSuite;
+
+/**
+ * Collection of utilities for working with test lifecycle methods.
+ *
+ * @since 1.11
+ */
+final class LifecycleMethodUtils {
+
+	private LifecycleMethodUtils() {
+		/* no-op */
+	}
+
+	static List<Method> findBeforeSuiteMethods(Class<?> testClass, ThrowableCollector throwableCollector) {
+		return findMethodsAndAssertStaticAndNonPrivate(testClass, BeforeSuite.class, HierarchyTraversalMode.TOP_DOWN,
+			throwableCollector);
+	}
+
+	static List<Method> findAfterSuiteMethods(Class<?> testClass, ThrowableCollector throwableCollector) {
+		return findMethodsAndAssertStaticAndNonPrivate(testClass, AfterSuite.class, HierarchyTraversalMode.BOTTOM_UP,
+			throwableCollector);
+	}
+
+	private static List<Method> findMethodsAndAssertStaticAndNonPrivate(Class<?> testClass,
+			Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode,
+			ThrowableCollector throwableCollector) {
+
+		List<Method> methods = findAnnotatedMethods(testClass, annotationType, traversalMode);
+		throwableCollector.execute(() -> methods.forEach(method -> {
+			assertVoid(annotationType, method);
+			assertStatic(annotationType, method);
+			assertNonPrivate(annotationType, method);
+			assertNoParameters(annotationType, method);
+		}));
+		return methods;
+	}
+
+	private static void assertStatic(Class<? extends Annotation> annotationType, Method method) {
+		if (ReflectionUtils.isNotStatic(method)) {
+			throw new JUnitException(String.format("@%s method '%s' must be static.", annotationType.getSimpleName(),
+				method.toGenericString()));
+		}
+	}
+
+	private static void assertNonPrivate(Class<? extends Annotation> annotationType, Method method) {
+		if (ReflectionUtils.isPrivate(method)) {
+			throw new JUnitException(String.format("@%s method '%s' must not be private.",
+				annotationType.getSimpleName(), method.toGenericString()));
+		}
+	}
+
+	private static void assertVoid(Class<? extends Annotation> annotationType, Method method) {
+		if (!returnsPrimitiveVoid(method)) {
+			throw new JUnitException(String.format("@%s method '%s' must not return a value.",
+				annotationType.getSimpleName(), method.toGenericString()));
+		}
+	}
+
+	private static void assertNoParameters(Class<? extends Annotation> annotationType, Method method) {
+		if (method.getParameterCount() > 0) {
+			throw new JUnitException(String.format("@%s method '%s' must not accept parameters.",
+				annotationType.getSimpleName(), method.toGenericString()));
+		}
+	}
+
+}

junit-platform-suite-engine/src/main/java/org/junit/platform/suite/engine/SuiteTestDescriptor.java

@@ -13,8 +13,12 @@
 import static org.junit.platform.commons.util.AnnotationUtils.findAnnotation;
 import static org.junit.platform.suite.commons.SuiteLauncherDiscoveryRequestBuilder.request;
 
+import java.lang.reflect.Method;
+import java.util.List;
+
 import org.junit.platform.commons.JUnitException;
 import org.junit.platform.commons.util.Preconditions;
+import org.junit.platform.commons.util.ReflectionUtils;
 import org.junit.platform.commons.util.StringUtils;
 import org.junit.platform.engine.ConfigurationParameters;
 import org.junit.platform.engine.EngineExecutionListener;
@@ -24,6 +28,8 @@
 import org.junit.platform.engine.discovery.DiscoverySelectors;
 import org.junit.platform.engine.support.descriptor.AbstractTestDescriptor;
 import org.junit.platform.engine.support.descriptor.ClassSource;
+import org.junit.platform.engine.support.hierarchical.OpenTest4JAwareThrowableCollector;
+import org.junit.platform.engine.support.hierarchical.ThrowableCollector;
 import org.junit.platform.launcher.LauncherDiscoveryRequest;
 import org.junit.platform.launcher.core.LauncherDiscoveryResult;
 import org.junit.platform.launcher.listeners.TestExecutionSummary;
@@ -121,16 +127,58 @@ private static String getSuiteDisplayName(Class<?> testClass) {
 
 	void execute(EngineExecutionListener parentEngineExecutionListener) {
 		parentEngineExecutionListener.executionStarted(this);
+		ThrowableCollector throwableCollector = new OpenTest4JAwareThrowableCollector();
+
+		List<Method> beforeSuiteMethods = LifecycleMethodUtils.findBeforeSuiteMethods(suiteClass, throwableCollector);
+		List<Method> afterSuiteMethods = LifecycleMethodUtils.findAfterSuiteMethods(suiteClass, throwableCollector);
+
+		executeBeforeSuiteMethods(beforeSuiteMethods, throwableCollector);
+
+		TestExecutionSummary summary = executeTests(parentEngineExecutionListener, throwableCollector);
+
+		executeAfterSuiteMethods(afterSuiteMethods, throwableCollector);
+
+		TestExecutionResult testExecutionResult = computeTestExecutionResult(summary, throwableCollector);
+		parentEngineExecutionListener.executionFinished(this, testExecutionResult);
+	}
+
+	private void executeBeforeSuiteMethods(List<Method> beforeSuiteMethods, ThrowableCollector throwableCollector) {
+		if (throwableCollector.isNotEmpty()) {
+			return;
+		}
+		for (Method beforeSuiteMethod : beforeSuiteMethods) {
+			throwableCollector.execute(() -> ReflectionUtils.invokeMethod(beforeSuiteMethod, null));
+			if (throwableCollector.isNotEmpty()) {
+				return;
+			}
+		}
+	}
+
+	private TestExecutionSummary executeTests(EngineExecutionListener parentEngineExecutionListener,
+			ThrowableCollector throwableCollector) {
+		if (throwableCollector.isNotEmpty()) {
+			return null;
+		}
+
 		// #2838: The discovery result from a suite may have been filtered by
 		// post discovery filters from the launcher. The discovery result should
 		// be pruned accordingly.
 		LauncherDiscoveryResult discoveryResult = this.launcherDiscoveryResult.withRetainedEngines(
 			getChildren()::contains);
-		TestExecutionSummary summary = launcher.execute(discoveryResult, parentEngineExecutionListener);
-		parentEngineExecutionListener.executionFinished(this, computeTestExecutionResult(summary));
+		return launcher.execute(discoveryResult, parentEngineExecutionListener);
 	}
 
-	private TestExecutionResult computeTestExecutionResult(TestExecutionSummary summary) {
+	private void executeAfterSuiteMethods(List<Method> afterSuiteMethods, ThrowableCollector throwableCollector) {
+		for (Method afterSuiteMethod : afterSuiteMethods) {
+			throwableCollector.execute(() -> ReflectionUtils.invokeMethod(afterSuiteMethod, null));
+		}
+	}
+
+	private TestExecutionResult computeTestExecutionResult(TestExecutionSummary summary,
+			ThrowableCollector throwableCollector) {
+		if (throwableCollector.isNotEmpty()) {
+			return TestExecutionResult.failed(throwableCollector.getThrowable());
+		}
 		if (failIfNoTests && summary.getTestsFoundCount() == 0) {
 			return TestExecutionResult.failed(new NoTestsDiscoveredException(suiteClass));
 		}