Document how to execute static nested test classes using Maven Surefire

Resolves #1378.

Author: marcphilipp

documentation/documentation.gradle

@@ -115,6 +115,7 @@ asciidoctor {
 				'mainDir': project.sourceSets.main.java.srcDirs[0],
 				'testDir': project.sourceSets.test.java.srcDirs[0],
 				'kotlinTestDir': project.sourceSets.test.kotlin.srcDirs[0],
+				'surefire-version': surefireVersion,
 				'consoleLauncherOptionsFile': consoleLauncherOptionsFile.toString(),
 				'experimentalApisTableFile': experimentalApisTableFile.toString(),
 				'testResourcesDir': project.sourceSets.test.resources.srcDirs[0],

documentation/src/docs/asciidoc/user-guide/running-tests.adoc

@@ -208,12 +208,13 @@ additional dependency to the runtime classpath.
 [[running-tests-build-maven]]
 ==== Maven
 
-The JUnit team has developed a very basic provider for Maven Surefire that lets you run
-JUnit 4 and JUnit Jupiter tests via `mvn test`. The `pom.xml` file in the
+The JUnit team has developed a basic provider for Maven Surefire that lets you run JUnit 4
+and JUnit Jupiter tests via `mvn test`. The `pom.xml` file in the
 `{junit5-maven-consumer}` project demonstrates how to use it and can serve as a starting
 point.
 
-NOTE: Please use Maven Surefire 2.21.0 with the `junit-platform-surefire-provider`.
+NOTE: Please use Maven Surefire {surefire-version} with the
+`junit-platform-surefire-provider`.
 
 [source,xml,indent=0]
 [subs=attributes+]
@@ -224,7 +225,7 @@ NOTE: Please use Maven Surefire 2.21.0 with the `junit-platform-surefire-provide
 			...
 			<plugin>
 				<artifactId>maven-surefire-plugin</artifactId>
-				<version>2.21.0</version>
+				<version>{surefire-version}</version>
 				<dependencies>
 					<dependency>
 						<groupId>org.junit.platform</groupId>
@@ -257,7 +258,7 @@ dependencies of the `maven-surefire-plugin` similar to the following.
 			...
 			<plugin>
 				<artifactId>maven-surefire-plugin</artifactId>
-				<version>2.21.0</version>
+				<version>{surefire-version}</version>
 				<dependencies>
 					<dependency>
 						<groupId>org.junit.platform</groupId>
@@ -299,7 +300,7 @@ the dependencies of the `maven-surefire-plugin` similar to the following.
 			...
 			<plugin>
 				<artifactId>maven-surefire-plugin</artifactId>
-				<version>2.21.0</version>
+				<version>{surefire-version}</version>
 				<dependencies>
 					<dependency>
 						<groupId>org.junit.platform</groupId>
@@ -347,11 +348,39 @@ the following patterns.
 
 - `+**/Test*.java+`
 - `+**/*Test.java+`
-- `+**/*Tests.java+` _(supported since Surefire 2.20)_
+- `+**/*Tests.java+`
 - `+**/*TestCase.java+`
 
+Moreover, it will exclude all nested classes (including static member classes) by default.
+
 Note, however, that you can override this default behavior by configuring explicit
-`include` and `exclude` rules in your `pom.xml` file. See the
+`include` and `exclude` rules in your `pom.xml` file. For example, to keep Maven Surefire
+from excluding static member classes, you can override its exclude rules.
+
+[source,xml,indent=0]
+[subs=attributes+]
+.Overriding exclude rules of Maven Surefire
+----
+	...
+	<build>
+		<plugins>
+			...
+			<plugin>
+				<artifactId>maven-surefire-plugin</artifactId>
+				<version>{surefire-version}</version>
+				<configuration>
+					<excludes>
+						<exclude/>
+					</excludes>
+				</configuration>
+				...
+			</plugin>
+		</plugins>
+	</build>
+	...
+----
+
+Please see the
 https://maven.apache.org/surefire/maven-surefire-plugin/examples/inclusion-exclusion.html[Inclusions and Exclusions of Tests]
 documentation for Maven Surefire for details.
 
@@ -365,14 +394,15 @@ the following configuration properties.
 - to exclude _tags_ or _tag expressions_, use either `excludedGroups` or `excludeTags`.
 
 [source,xml,indent=0]
+[subs=attributes+]
 ----
 	...
 	<build>
 		<plugins>
 			...
 			<plugin>
 				<artifactId>maven-surefire-plugin</artifactId>
-				<version>2.21.0</version>
+				<version>{surefire-version}</version>
 				<configuration>
 			        <properties>
 			            <includeTags>acceptance | !feature-a</includeTags>
@@ -397,14 +427,15 @@ property and providing key-value pairs using the Java `Properties` file syntax (
 below) or via the `junit-platform.properties` file.
 
 [source,xml,indent=0]
+[subs=attributes+]
 ----
 	...
 	<build>
 		<plugins>
 			...
 			<plugin>
 				<artifactId>maven-surefire-plugin</artifactId>
-				<version>2.21.0</version>
+				<version>{surefire-version}</version>
 				<configuration>
 					<properties>
 						<configurationParameters>

gradle.properties

@@ -28,6 +28,7 @@ log4jVersion        = 2.11.0
 mockitoVersion      = 2.18.0
 ota4jVersion        = 1.0.0
 shadowVersion       = 2.0.3
+surefireVersion     = 2.21.0
 
 defaultBuiltBy      = JUnit Team
 releaseBranch       = master

junit-platform-surefire-provider/junit-platform-surefire-provider.gradle

@@ -14,8 +14,8 @@ junitPlatform {
 
 dependencies {
 	api(project(':junit-platform-launcher'))
-	implementation('org.apache.maven.surefire:surefire-api:2.21.0')
-	implementation('org.apache.maven.surefire:common-java5:2.21.0')
+	implementation("org.apache.maven.surefire:surefire-api:${surefireVersion}")
+	implementation("org.apache.maven.surefire:common-java5:${surefireVersion}")
 
 	testImplementation(project(':junit-jupiter-api'))
 	testImplementation(project(':junit-platform-runner'))