Skip to content

Commit a4c3408

Browse files
juliette-derancourtmarcphilipp
juliette-derancourt
and
marcphilipp
authored
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 <[email protected]>
1 parent f8a65af commit a4c3408

File tree

10 files changed

+857
-3
lines changed

10 files changed

+857
-3
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ repository on GitHub.
3333
exception's _root_ cause matches all supplied conditions, for use with the
3434
`EngineTestKit`.
3535
* `ReflectionSupport` now supports scanning for classpath resources.
36+
* Introduce `@BeforeSuite` and `@AfterSuite` annotations.
3637

3738

3839
[[release-notes-5.11.0-RC1-junit-jupiter]]

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

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,3 +48,14 @@ include::{testDir}/example/SuiteDemo.java[tags=user_guide]
4848
NOTE: There are numerous configuration options for discovering and filtering tests in a
4949
test suite. Please consult the Javadoc of the `{suite-api-package}` package for a full
5050
list of supported annotations and further details.
51+
52+
==== @BeforeSuite and @AfterSuite
53+
54+
`@BeforeSuite` and `@AfterSuite` annotations can be used on methods inside a
55+
`@Suite`-annotated class. They will be executed respectively before and after
56+
all tests of the test suite.
57+
58+
[source,java,indent=0]
59+
----
60+
include::{testDir}/example/BeforeAndAfterSuiteDemo.java[tags=user_guide]
61+
----

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

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
/*
2+
* Copyright 2015-2024 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* https://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package example;
12+
13+
import org.junit.platform.suite.api.AfterSuite;
14+
import org.junit.platform.suite.api.BeforeSuite;
15+
import org.junit.platform.suite.api.SelectPackages;
16+
import org.junit.platform.suite.api.Suite;
17+
18+
//tag::user_guide[]
19+
@Suite
20+
@SelectPackages("example")
21+
class BeforeAndAfterSuiteDemo {
22+
23+
@BeforeSuite
24+
static void beforeSuite() {
25+
// executes before the test suite
26+
}
27+
28+
@AfterSuite
29+
static void afterSuite() {
30+
// executes after the test suite
31+
}
32+
33+
}
34+
//end::user_guide[]

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/*
2+
* Copyright 2015-2024 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* https://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.platform.suite.api;
12+
13+
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
14+
15+
import java.lang.annotation.Documented;
16+
import java.lang.annotation.ElementType;
17+
import java.lang.annotation.Retention;
18+
import java.lang.annotation.RetentionPolicy;
19+
import java.lang.annotation.Target;
20+
21+
import org.apiguardian.api.API;
22+
23+
/**
24+
* {@code @AfterSuite} is used to signal that the annotated method should be
25+
* executed <em>after</em> <strong>all</strong> tests in the current test suite.
26+
*
27+
* <h2>Method Signatures</h2>
28+
*
29+
* <p>{@code @AfterSuite} methods must have a {@code void} return type, must
30+
* be {@code static} and must not be {@code private}.
31+
*
32+
* <h2>Inheritance and Execution Order</h2>
33+
*
34+
* <p>{@code @AfterSuite} methods are inherited from superclasses as long as they
35+
* are not <em>overridden</em> according to the visibility rules of the Java
36+
* language. Furthermore, {@code @AfterSuite} methods from superclasses will be
37+
* executed after {@code @AfterSuite} methods in subclasses.
38+
*
39+
* <p>The JUnit Platform Suite Engine does not guarantee the execution order of
40+
* multiple {@code @AfterSuite} methods that are declared within a single test
41+
* class or test interface. While it may at times appear that these methods are
42+
* invoked in alphabetical order, they are in fact sorted using an algorithm
43+
* that is deterministic but intentionally non-obvious.
44+
*
45+
* <p>In addition, {@code @AfterSuite} methods are in no way linked to
46+
* {@code @BeforeSuite} methods. Consequently, there are no guarantees with regard
47+
* to their <em>wrapping</em> behavior. For example, given two
48+
* {@code @BeforeSuite} methods {@code createA()} and {@code createB()} as well as
49+
* two {@code @AfterSuite} methods {@code destroyA()} and {@code destroyB()}, the
50+
* order in which the {@code @BeforeSuite} methods are executed (e.g.
51+
* {@code createA()} before {@code createB()}) does not imply any order for the
52+
* seemingly corresponding {@code @AfterSuite} methods. In other words,
53+
* {@code destroyA()} might be called before <em>or</em> after
54+
* {@code destroyB()}. The JUnit Team therefore recommends that developers
55+
* declare at most one {@code @BeforeSuite} method and at most one
56+
* {@code @AfterSuite} method per test class or test interface unless there are no
57+
* dependencies between the {@code @BeforeSuite} methods or between the
58+
* {@code @AfterSuite} methods.
59+
*
60+
* <h2>Composition</h2>
61+
*
62+
* <p>{@code @AfterSuite} may be used as a meta-annotation in order to create
63+
* a custom <em>composed annotation</em> that inherits the semantics of
64+
* {@code @AfterSuite}.
65+
*
66+
* @since 1.11
67+
* @see BeforeSuite
68+
* @see Suite
69+
*/
70+
@Target(ElementType.METHOD)
71+
@Retention(RetentionPolicy.RUNTIME)
72+
@Documented
73+
@API(status = EXPERIMENTAL, since = "1.11")
74+
public @interface AfterSuite {
75+
}

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

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
/*
2+
* Copyright 2015-2024 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* https://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.platform.suite.api;
12+
13+
import static org.apiguardian.api.API.Status.EXPERIMENTAL;
14+
15+
import java.lang.annotation.Documented;
16+
import java.lang.annotation.ElementType;
17+
import java.lang.annotation.Retention;
18+
import java.lang.annotation.RetentionPolicy;
19+
import java.lang.annotation.Target;
20+
21+
import org.apiguardian.api.API;
22+
23+
/**
24+
* {@code @BeforeSuite} is used to signal that the annotated method should be
25+
* executed <em>before</em> <strong>all</strong> tests in the current test suite.
26+
*
27+
* <h2>Method Signatures</h2>
28+
*
29+
* <p>{@code @BeforeSuite} methods must have a {@code void} return type, must
30+
* be {@code static} and must not be {@code private}.
31+
*
32+
* <h2>Inheritance and Execution Order</h2>
33+
*
34+
* <p>{@code @BeforeSuite} methods are inherited from superclasses as long as they
35+
* are not <em>overridden</em> according to the visibility rules of the Java
36+
* language. Furthermore, {@code @BeforeSuite} methods from superclasses will be
37+
* executed before {@code @BeforeSuite} methods in subclasses.
38+
*
39+
* <p>The JUnit Platform Suite Engine does not guarantee the execution order of
40+
* multiple {@code @BeforeSuite} methods that are declared within a single test
41+
* class or test interface. While it may at times appear that these methods are
42+
* invoked in alphabetical order, they are in fact sorted using an algorithm
43+
* that is deterministic but intentionally non-obvious.
44+
*
45+
* <p>In addition, {@code @BeforeSuite} methods are in no way linked to
46+
* {@code @AfterSuite} methods. Consequently, there are no guarantees with regard
47+
* to their <em>wrapping</em> behavior. For example, given two
48+
* {@code @BeforeSuite} methods {@code createA()} and {@code createB()} as well as
49+
* two {@code @AfterSuite} methods {@code destroyA()} and {@code destroyB()}, the
50+
* order in which the {@code @BeforeSuite} methods are executed (e.g.
51+
* {@code createA()} before {@code createB()}) does not imply any order for the
52+
* seemingly corresponding {@code @AfterSuite} methods. In other words,
53+
* {@code destroyA()} might be called before <em>or</em> after
54+
* {@code destroyB()}. The JUnit Team therefore recommends that developers
55+
* declare at most one {@code @BeforeSuite} method and at most one
56+
* {@code @AfterSuite} method per test class or test interface unless there are no
57+
* dependencies between the {@code @BeforeSuite} methods or between the
58+
* {@code @AfterSuite} methods.
59+
*
60+
* <h2>Composition</h2>
61+
*
62+
* <p>{@code @BeforeSuite} may be used as a meta-annotation in order to create
63+
* a custom <em>composed annotation</em> that inherits the semantics of
64+
* {@code @BeforeSuite}.
65+
*
66+
* @since 1.11
67+
* @see AfterSuite
68+
* @see Suite
69+
*/
70+
@Target(ElementType.METHOD)
71+
@Retention(RetentionPolicy.RUNTIME)
72+
@Documented
73+
@API(status = EXPERIMENTAL, since = "1.11")
74+
public @interface BeforeSuite {
75+
}

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

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
/*
2+
* Copyright 2015-2024 the original author or authors.
3+
*
4+
* All rights reserved. This program and the accompanying materials are
5+
* made available under the terms of the Eclipse Public License v2.0 which
6+
* accompanies this distribution and is available at
7+
*
8+
* https://www.eclipse.org/legal/epl-v20.html
9+
*/
10+
11+
package org.junit.platform.suite.engine;
12+
13+
import static org.junit.platform.commons.util.AnnotationUtils.findAnnotatedMethods;
14+
import static org.junit.platform.commons.util.ReflectionUtils.returnsPrimitiveVoid;
15+
16+
import java.lang.annotation.Annotation;
17+
import java.lang.reflect.Method;
18+
import java.util.List;
19+
20+
import org.junit.platform.commons.JUnitException;
21+
import org.junit.platform.commons.util.ReflectionUtils;
22+
import org.junit.platform.commons.util.ReflectionUtils.HierarchyTraversalMode;
23+
import org.junit.platform.engine.support.hierarchical.ThrowableCollector;
24+
import org.junit.platform.suite.api.AfterSuite;
25+
import org.junit.platform.suite.api.BeforeSuite;
26+
27+
/**
28+
* Collection of utilities for working with test lifecycle methods.
29+
*
30+
* @since 1.11
31+
*/
32+
final class LifecycleMethodUtils {
33+
34+
private LifecycleMethodUtils() {
35+
/* no-op */
36+
}
37+
38+
static List<Method> findBeforeSuiteMethods(Class<?> testClass, ThrowableCollector throwableCollector) {
39+
return findMethodsAndAssertStaticAndNonPrivate(testClass, BeforeSuite.class, HierarchyTraversalMode.TOP_DOWN,
40+
throwableCollector);
41+
}
42+
43+
static List<Method> findAfterSuiteMethods(Class<?> testClass, ThrowableCollector throwableCollector) {
44+
return findMethodsAndAssertStaticAndNonPrivate(testClass, AfterSuite.class, HierarchyTraversalMode.BOTTOM_UP,
45+
throwableCollector);
46+
}
47+
48+
private static List<Method> findMethodsAndAssertStaticAndNonPrivate(Class<?> testClass,
49+
Class<? extends Annotation> annotationType, HierarchyTraversalMode traversalMode,
50+
ThrowableCollector throwableCollector) {
51+
52+
List<Method> methods = findAnnotatedMethods(testClass, annotationType, traversalMode);
53+
throwableCollector.execute(() -> methods.forEach(method -> {
54+
assertVoid(annotationType, method);
55+
assertStatic(annotationType, method);
56+
assertNonPrivate(annotationType, method);
57+
assertNoParameters(annotationType, method);
58+
}));
59+
return methods;
60+
}
61+
62+
private static void assertStatic(Class<? extends Annotation> annotationType, Method method) {
63+
if (ReflectionUtils.isNotStatic(method)) {
64+
throw new JUnitException(String.format("@%s method '%s' must be static.", annotationType.getSimpleName(),
65+
method.toGenericString()));
66+
}
67+
}
68+
69+
private static void assertNonPrivate(Class<? extends Annotation> annotationType, Method method) {
70+
if (ReflectionUtils.isPrivate(method)) {
71+
throw new JUnitException(String.format("@%s method '%s' must not be private.",
72+
annotationType.getSimpleName(), method.toGenericString()));
73+
}
74+
}
75+
76+
private static void assertVoid(Class<? extends Annotation> annotationType, Method method) {
77+
if (!returnsPrimitiveVoid(method)) {
78+
throw new JUnitException(String.format("@%s method '%s' must not return a value.",
79+
annotationType.getSimpleName(), method.toGenericString()));
80+
}
81+
}
82+
83+
private static void assertNoParameters(Class<? extends Annotation> annotationType, Method method) {
84+
if (method.getParameterCount() > 0) {
85+
throw new JUnitException(String.format("@%s method '%s' must not accept parameters.",
86+
annotationType.getSimpleName(), method.toGenericString()));
87+
}
88+
}
89+
90+
}

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

Lines changed: 51 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -13,8 +13,12 @@
1313
import static org.junit.platform.commons.util.AnnotationUtils.findAnnotation;
1414
import static org.junit.platform.suite.commons.SuiteLauncherDiscoveryRequestBuilder.request;
1515

16+
import java.lang.reflect.Method;
17+
import java.util.List;
18+
1619
import org.junit.platform.commons.JUnitException;
1720
import org.junit.platform.commons.util.Preconditions;
21+
import org.junit.platform.commons.util.ReflectionUtils;
1822
import org.junit.platform.commons.util.StringUtils;
1923
import org.junit.platform.engine.ConfigurationParameters;
2024
import org.junit.platform.engine.EngineExecutionListener;
@@ -24,6 +28,8 @@
2428
import org.junit.platform.engine.discovery.DiscoverySelectors;
2529
import org.junit.platform.engine.support.descriptor.AbstractTestDescriptor;
2630
import org.junit.platform.engine.support.descriptor.ClassSource;
31+
import org.junit.platform.engine.support.hierarchical.OpenTest4JAwareThrowableCollector;
32+
import org.junit.platform.engine.support.hierarchical.ThrowableCollector;
2733
import org.junit.platform.launcher.LauncherDiscoveryRequest;
2834
import org.junit.platform.launcher.core.LauncherDiscoveryResult;
2935
import org.junit.platform.launcher.listeners.TestExecutionSummary;
@@ -121,16 +127,58 @@ private static String getSuiteDisplayName(Class<?> testClass) {
121127

122128
void execute(EngineExecutionListener parentEngineExecutionListener) {
123129
parentEngineExecutionListener.executionStarted(this);
130+
ThrowableCollector throwableCollector = new OpenTest4JAwareThrowableCollector();
131+
132+
List<Method> beforeSuiteMethods = LifecycleMethodUtils.findBeforeSuiteMethods(suiteClass, throwableCollector);
133+
List<Method> afterSuiteMethods = LifecycleMethodUtils.findAfterSuiteMethods(suiteClass, throwableCollector);
134+
135+
executeBeforeSuiteMethods(beforeSuiteMethods, throwableCollector);
136+
137+
TestExecutionSummary summary = executeTests(parentEngineExecutionListener, throwableCollector);
138+
139+
executeAfterSuiteMethods(afterSuiteMethods, throwableCollector);
140+
141+
TestExecutionResult testExecutionResult = computeTestExecutionResult(summary, throwableCollector);
142+
parentEngineExecutionListener.executionFinished(this, testExecutionResult);
143+
}
144+
145+
private void executeBeforeSuiteMethods(List<Method> beforeSuiteMethods, ThrowableCollector throwableCollector) {
146+
if (throwableCollector.isNotEmpty()) {
147+
return;
148+
}
149+
for (Method beforeSuiteMethod : beforeSuiteMethods) {
150+
throwableCollector.execute(() -> ReflectionUtils.invokeMethod(beforeSuiteMethod, null));
151+
if (throwableCollector.isNotEmpty()) {
152+
return;
153+
}
154+
}
155+
}
156+
157+
private TestExecutionSummary executeTests(EngineExecutionListener parentEngineExecutionListener,
158+
ThrowableCollector throwableCollector) {
159+
if (throwableCollector.isNotEmpty()) {
160+
return null;
161+
}
162+
124163
// #2838: The discovery result from a suite may have been filtered by
125164
// post discovery filters from the launcher. The discovery result should
126165
// be pruned accordingly.
127166
LauncherDiscoveryResult discoveryResult = this.launcherDiscoveryResult.withRetainedEngines(
128167
getChildren()::contains);
129-
TestExecutionSummary summary = launcher.execute(discoveryResult, parentEngineExecutionListener);
130-
parentEngineExecutionListener.executionFinished(this, computeTestExecutionResult(summary));
168+
return launcher.execute(discoveryResult, parentEngineExecutionListener);
131169
}
132170

133-
private TestExecutionResult computeTestExecutionResult(TestExecutionSummary summary) {
171+
private void executeAfterSuiteMethods(List<Method> afterSuiteMethods, ThrowableCollector throwableCollector) {
172+
for (Method afterSuiteMethod : afterSuiteMethods) {
173+
throwableCollector.execute(() -> ReflectionUtils.invokeMethod(afterSuiteMethod, null));
174+
}
175+
}
176+
177+
private TestExecutionResult computeTestExecutionResult(TestExecutionSummary summary,
178+
ThrowableCollector throwableCollector) {
179+
if (throwableCollector.isNotEmpty()) {
180+
return TestExecutionResult.failed(throwableCollector.getThrowable());
181+
}
134182
if (failIfNoTests && summary.getTestsFoundCount() == 0) {
135183
return TestExecutionResult.failed(new NoTestsDiscoveredException(suiteClass));
136184
}

0 commit comments

Comments
 (0)