Polishing

Addresses #162

documentation/src/docs/asciidoc/release-notes/release-notes-5.4.0-M1.adoc

@@ -28,7 +28,8 @@ repository on GitHub.
   `org.junit.Assume` utility class.
 * In addition to returning streams, `@TestFactory`-annotated methods may return a single
   `DynamicNode`, i.e. a `DynamicTest` or a `DynamicContainer`, instance.
-
+* New `DisplayNameGenerator` interface and `@DisplayNameGeneration` annotation that allow
+  declarative configuration of a pre-defined or custom display name generator.
 
 [[release-notes-5.4.0-M1-junit-jupiter]]
 === JUnit Jupiter

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

@@ -89,8 +89,7 @@ include::{testDir}/example/DisplayNameDemo.java[tags=user_guide]
 
 ==== Display Name Generators
 
-JUnit Jupiter supports since version 5.4.0-SNAPSHOT custom display name generators.
-
+JUnit Jupiter supports custom display name generators via the `@DisplayNameGeneration` annotation.
 Values provided with a `@DisplayName` annotations always take precedence over display names
 generated by a display name generator.
 

junit-jupiter-api/src/main/java/org/junit/jupiter/api/DisplayNameGeneration.java

@@ -39,7 +39,7 @@
 	/**
 	 * Custom display name generator.
 	 *
-	 * @return custom display name generator implementation
+	 * @return custom display name generator class
 	 */
 	Class<? extends DisplayNameGenerator> value();
 

junit-jupiter-api/src/main/java/org/junit/jupiter/api/DisplayNameGenerator.java

@@ -33,11 +33,17 @@ public interface DisplayNameGenerator {
 
 	/**
 	 * Generate a display name for the given top-level or {@code static} nested test class.
+	 *
+	 * @param testClass the class generate a name for; never {@code null}
+	 * @return the display name of the container; never {@code null} or blank
 	 */
 	String generateDisplayNameForClass(Class<?> testClass);
 
 	/**
-	 * Generate a display name for the given {@link Nested} inner test class.
+	 * Generate a display name for the given {@link Nested @Nested} inner test class.
+	 *
+	 * @param nestedClass the class generate a name for; never {@code null}
+	 * @return the display name of the container; never {@code null} or blank
 	 */
 	String generateDisplayNameForNestedClass(Class<?> nestedClass);
 
@@ -48,15 +54,16 @@ public interface DisplayNameGenerator {
 	 * the returned class by {@code testMethod.getDeclaringClass()}: e.g., when
 	 * a test method is inherited from a super class.
 	 *
-	 * @param testClass the class the test method is invoked on
-	 * @param testMethod method to generate a display name for
+	 * @param testClass the class the test method is invoked on; never {@code null}
+	 * @param testMethod method to generate a display name for; never {@code null}
+	 * @return the display name of the test; never {@code null} or blank
 	 */
 	String generateDisplayNameForMethod(Class<?> testClass, Method testMethod);
 
 	/**
 	 * Compile a string representation from all simple parameter type names.
 	 *
-	 * @param method the method providing parameter types for the result
+	 * @param method the method providing parameter types for the result; never {@code null}
 	 * @return a string representation of all parameter types of the
 	 *         supplied method or {@code "()"} if the method has no parameters
 	 */
@@ -71,25 +78,21 @@ static String parameterTypesAsString(Method method) {
 	 * <p>The implementation matches the published behaviour when Jupiter 5.0.0
 	 * was released.
 	 */
-	class StandardGenerator implements DisplayNameGenerator {
+	class Standard implements DisplayNameGenerator {
 		@Override
 		public String generateDisplayNameForClass(Class<?> testClass) {
-			Preconditions.notNull(testClass, "Test class must not be null");
 			String name = testClass.getName();
 			int lastDot = name.lastIndexOf('.');
 			return name.substring(lastDot + 1);
 		}
 
 		@Override
 		public String generateDisplayNameForNestedClass(Class<?> nestedClass) {
-			Preconditions.notNull(nestedClass, "Nested test class must not be null");
 			return nestedClass.getSimpleName();
 		}
 
 		@Override
 		public String generateDisplayNameForMethod(Class<?> testClass, Method testMethod) {
-			Preconditions.notNull(testClass, "Test class must not be null");
-			Preconditions.notNull(testMethod, "Test method must not be null");
 			return testMethod.getName() + parameterTypesAsString(testMethod);
 		}
 	}
@@ -100,7 +103,7 @@ public String generateDisplayNameForMethod(Class<?> testClass, Method testMethod
 	 * <p>The {@code ReplaceUnderscores} generator replaces all underscore characters
 	 * ({@code '_'}) found in class and method names with space characters: {@code ' '}.
 	 */
-	class ReplaceUnderscores extends StandardGenerator {
+	class ReplaceUnderscores extends Standard {
 
 		@Override
 		public String generateDisplayNameForClass(Class<?> testClass) {
@@ -114,8 +117,6 @@ public String generateDisplayNameForNestedClass(Class<?> nestedClass) {
 
 		@Override
 		public String generateDisplayNameForMethod(Class<?> testClass, Method testMethod) {
-			Preconditions.notNull(testClass, "Test class must not be null");
-			Preconditions.notNull(testMethod, "Test method must not be null");
 			// don't replace underscores in parameter type names
 			return replaceUnderscores(testMethod.getName()) + parameterTypesAsString(testMethod);
 		}

junit-jupiter-engine/src/main/java/org/junit/jupiter/engine/descriptor/DisplayNameUtils.java

@@ -21,7 +21,7 @@
 import org.junit.jupiter.api.DisplayNameGeneration;
 import org.junit.jupiter.api.DisplayNameGenerator;
 import org.junit.jupiter.api.DisplayNameGenerator.ReplaceUnderscores;
-import org.junit.jupiter.api.DisplayNameGenerator.StandardGenerator;
+import org.junit.jupiter.api.DisplayNameGenerator.Standard;
 import org.junit.platform.commons.logging.Logger;
 import org.junit.platform.commons.logging.LoggerFactory;
 import org.junit.platform.commons.util.Preconditions;
@@ -43,7 +43,7 @@ final class DisplayNameUtils {
 	/**
 	 * Pre-defined standard display name generator instance.
 	 */
-	private static final DisplayNameGenerator standardGenerator = new StandardGenerator();
+	private static final DisplayNameGenerator standardGenerator = new Standard();
 
 	/**
 	 * Pre-defined display name generator instance replacing underscores.
@@ -66,7 +66,7 @@ static String determineDisplayName(AnnotatedElement element, Supplier<String> di
 				return displayName;
 			}
 		}
-		// else let a 'DisplayNameGenerator' generator generate a display name
+		// else let a 'DisplayNameGenerator' generate a display name
 		return displayNameSupplier.get();
 	}
 
@@ -86,14 +86,14 @@ static Supplier<String> createDisplayNameSupplierForNestedClass(Class<?> testCla
 
 	private static DisplayNameGenerator getDisplayNameGenerator(Class<?> testClass) {
 		Preconditions.notNull(testClass, "Test class must not be null");
-		DisplayNameGeneration generation = getDisplayNameGenerationOrNull(testClass);
+		DisplayNameGeneration generation = getDisplayNameGeneration(testClass).orElse(null);
 		// trivial case: no user-defined generation annotation present, return default generator
 		if (generation == null) {
 			return standardGenerator;
 		}
 		// check for pre-defined generators and return matching singleton
 		Class<? extends DisplayNameGenerator> displayNameGeneratorClass = generation.value();
-		if (displayNameGeneratorClass == StandardGenerator.class) {
+		if (displayNameGeneratorClass == Standard.class) {
 			return standardGenerator;
 		}
 		if (displayNameGeneratorClass == ReplaceUnderscores.class) {
@@ -108,15 +108,15 @@ private static DisplayNameGenerator getDisplayNameGenerator(Class<?> testClass)
 	 * <em>directly present</em>, <em>meta-present</em>, <em>indirectly present</em>
 	 * on the supplied {@code testClass} or on an enclosing class.
 	 */
-	private static DisplayNameGeneration getDisplayNameGenerationOrNull(Class<?> testClass) {
+	private static Optional<DisplayNameGeneration> getDisplayNameGeneration(Class<?> testClass) {
 		Class<?> candidate = testClass;
 		do {
 			Optional<DisplayNameGeneration> generation = findAnnotation(candidate, DisplayNameGeneration.class);
 			if (generation.isPresent()) {
-				return generation.get();
+				return generation;
 			}
 			candidate = candidate.getEnclosingClass();
 		} while (candidate != null);
-		return null;
+		return Optional.empty();
 	}
 }

junit-jupiter-engine/src/test/java/org/junit/jupiter/api/DisplayNameGenerationTests.java

@@ -161,7 +161,7 @@ void testDisplayNamePrevails() {
 		}
 	}
 
-	@DisplayNameGeneration(DisplayNameGenerator.StandardGenerator.class)
+	@DisplayNameGeneration(DisplayNameGenerator.Standard.class)
 	static class DefaultStyleTestCase extends AbstractTestCase {
 	}