Add nullability annotations and compile-time checks

CONTRIBUTING.md

@@ -120,6 +120,17 @@ See [`ExtensionContext`](junit-jupiter-api/src/main/java/org/junit/jupiter/api/e
 [`ParameterContext`](junit-jupiter-api/src/main/java/org/junit/jupiter/api/extension/ParameterContext.java) for example Javadoc.
 
 
+### Nullability
+
+This project uses JSpecify's annotation to indicate nullability. In general, the approach
+is as follows:
+
+- The Gradle build is set up to treat all code as being `@NullMarked`
+- The descriptor of each module is annotated with `@NullMarked` for IDEs such as IntelliJ
+  IDEA to treat code correctly.
+- Fields, parameters, return types etc. may be annotated with `@Nullable`
+- A package can be excluded (temporarily) using `@NullUnmarked`
+
 ### Tests
 
 #### Naming

documentation/documentation.gradle.kts

@@ -18,6 +18,7 @@ plugins {
 	alias(libs.plugins.plantuml)
 	id("junitbuild.build-parameters")
 	id("junitbuild.java-multi-release-test-sources")
+	id("junitbuild.java-nullability-conventions")
 	id("junitbuild.kotlin-library-conventions")
 	id("junitbuild.testing-conventions")
 }

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

@@ -27,7 +27,8 @@ repository on GitHub.
 [[release-notes-6.0.0-M1-overall-new-features-and-improvements]]
 ==== New Features and Improvements
 
-* ❓
+* All JUnit modules now use https://jspecify.dev/[JSpecify]'s nullability annotations to
+  indicate which method parameters, return types, etc. can be `null`.
 
 
 [[release-notes-6.0.0-M1-junit-platform]]

documentation/src/main/java/example/util/StringUtils.java

@@ -10,10 +10,14 @@
 
 package example.util;
 
+import static java.util.Objects.requireNonNull;
+
+import org.jspecify.annotations.Nullable;
+
 public class StringUtils {
 
-	public static boolean isPalindrome(String candidate) {
-		int length = candidate.length();
+	public static boolean isPalindrome(@Nullable String candidate) {
+		int length = requireNonNull(candidate).length();
 		for (int i = 0; i < length / 2; i++) {
 			if (candidate.charAt(i) != candidate.charAt(length - (i + 1))) {
 				return false;

documentation/src/test/java/example/ClassTemplateDemo.java

@@ -19,6 +19,7 @@
 import java.util.List;
 import java.util.stream.Stream;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.ClassTemplate;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ClassTemplateInvocationContext;
@@ -37,6 +38,9 @@ class ClassTemplateDemo {
 	// tag::custom_line_break[]
 		= unmodifiableList(Arrays.asList("apple", "banana", "lemon"));
 
+	//end::user_guide[]
+	@Nullable
+	//tag::user_guide[]
 	private String fruit;
 
 	@Test

documentation/src/test/java/example/DynamicTestsDemo.java

@@ -47,7 +47,7 @@ class DynamicTestsDemo {
 	@TestFactory
 	// end::user_guide[]
 	@Tag("exclude")
-	DynamicTest dummy() { return null; }
+	DynamicTest dummy() { return dynamicTest("dummy", () -> {}); }
 	// tag::user_guide[]
 	List<String> dynamicTestsWithInvalidReturnType() {
 		return Arrays.asList("Hello");

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

@@ -18,6 +18,7 @@
 import java.io.UncheckedIOException;
 import java.net.ServerSocket;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.engine.EngineDiscoveryRequest;
 import org.junit.platform.engine.ExecutionRequest;
 import org.junit.platform.engine.TestDescriptor;
@@ -32,6 +33,9 @@
  */
 public class FirstCustomEngine implements TestEngine {
 
+	//end::user_guide[]
+	@Nullable
+	//tag::user_guide[]
 	public ServerSocket socket;
 
 	@Override

documentation/src/test/java/example/ParameterizedTestDemo.java

@@ -459,6 +459,7 @@ void testWithExplicitArgumentConversion(
 
 	// end::explicit_conversion_example[]
 	static
+	@SuppressWarnings({ "NullableProblems", "NullAway" })
 	// tag::explicit_conversion_example_ToStringArgumentConverter[]
 	public class ToStringArgumentConverter extends SimpleArgumentConverter {
 
@@ -474,6 +475,7 @@ protected Object convert(Object source, Class<?> targetType) {
 	// end::explicit_conversion_example_ToStringArgumentConverter[]
 
 	static
+	@SuppressWarnings({ "NullableProblems", "NullAway", "ConstantValue" })
 	// tag::explicit_conversion_example_TypedArgumentConverter[]
 	public class ToLengthArgumentConverter extends TypedArgumentConverter<String, Integer> {
 

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

@@ -17,6 +17,7 @@
 import java.io.UncheckedIOException;
 import java.net.ServerSocket;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.platform.engine.EngineDiscoveryRequest;
 import org.junit.platform.engine.ExecutionRequest;
 import org.junit.platform.engine.TestDescriptor;
@@ -32,6 +33,9 @@
  */
 public class SecondCustomEngine implements TestEngine {
 
+	//end::user_guide[]
+	@Nullable
+	//tag::user_guide[]
 	public ServerSocket socket;
 
 	@Override

documentation/src/test/java/example/TestingAStackDemo.java

@@ -27,8 +27,6 @@
 @DisplayName("A stack")
 class TestingAStackDemo {
 
-	Stack<Object> stack;
-
 	@Test
 	@DisplayName("is instantiated with new Stack()")
 	void isInstantiatedWithNew() {
@@ -39,6 +37,8 @@ void isInstantiatedWithNew() {
 	@DisplayName("when new")
 	class WhenNew {
 
+		Stack<Object> stack;
+
 		@BeforeEach
 		void createNewStack() {
 			stack = new Stack<>();

documentation/src/test/java/example/callbacks/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.callbacks;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/defaultmethods/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.defaultmethods;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/exception/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.exception;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/extensions/HttpServerExtension.java

@@ -28,12 +28,15 @@ public boolean supportsParameter(ParameterContext parameterContext, ExtensionCon
 		return HttpServer.class.equals(parameterContext.getParameter().getType());
 	}
 
+	//end::user_guide[]
+	@SuppressWarnings({ "DataFlowIssue", "NullAway" })
+	//tag::user_guide[]
 	@Override
 	public Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {
 
 		ExtensionContext rootContext = extensionContext.getRoot();
 		ExtensionContext.Store store = rootContext.getStore(Namespace.GLOBAL);
-		String key = HttpServerResource.class.getName();
+		Class<HttpServerResource> key = HttpServerResource.class;
 		HttpServerResource resource = store.getOrComputeIfAbsent(key, __ -> {
 			try {
 				HttpServerResource serverResource = new HttpServerResource(0);

documentation/src/test/java/example/extensions/RandomNumberDemo.java

@@ -10,6 +10,7 @@
 
 package example.extensions;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
@@ -19,6 +20,9 @@ class RandomNumberDemo {
 	// Use static randomNumber0 field anywhere in the test class,
 	// including @BeforeAll or @AfterEach lifecycle methods.
 	@Random
+	// end::user_guide[]
+	@Nullable
+	// tag::user_guide[]
 	private static Integer randomNumber0;
 
 	// Use randomNumber1 field in test methods and @BeforeEach

documentation/src/test/java/example/extensions/RandomNumberExtension.java

@@ -17,6 +17,7 @@
 import java.lang.reflect.Field;
 import java.util.function.Predicate;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.extension.BeforeAllCallback;
 import org.junit.jupiter.api.extension.ExtensionContext;
 import org.junit.jupiter.api.extension.ParameterContext;
@@ -69,7 +70,7 @@ public Integer resolveParameter(ParameterContext pc, ExtensionContext ec) {
 		return this.random.nextInt();
 	}
 
-	private void injectFields(Class<?> testClass, Object testInstance,
+	private void injectFields(Class<?> testClass, @Nullable Object testInstance,
 			Predicate<Field> predicate) {
 
 		predicate = predicate.and(field -> isInteger(field.getType()));

documentation/src/test/java/example/extensions/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.extensions;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/interceptor/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.interceptor;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/registration/DocumentationDemo.java

@@ -12,6 +12,7 @@
 
 import java.nio.file.Path;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.AfterEachCallback;
 import org.junit.jupiter.api.extension.ExtensionContext;
@@ -20,6 +21,9 @@
 //tag::user_guide[]
 class DocumentationDemo {
 
+	//end::user_guide[]
+	@Nullable
+	//tag::user_guide[]
 	static Path lookUpDocsDir() {
 		// return path to docs dir
 		// end::user_guide[]
@@ -40,13 +44,13 @@ void generateDocumentation() {
 class DocumentationExtension implements AfterEachCallback {
 
 	@SuppressWarnings("unused")
-	private final Path path;
+	private final @Nullable Path path;
 
-	private DocumentationExtension(Path path) {
+	private DocumentationExtension(@Nullable Path path) {
 		this.path = path;
 	}
 
-	static DocumentationExtension forPath(Path path) {
+	static DocumentationExtension forPath(@Nullable Path path) {
 		return new DocumentationExtension(path);
 	}
 

documentation/src/test/java/example/registration/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.registration;
+
+import org.jspecify.annotations.NullMarked;

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

@@ -49,6 +49,9 @@ public boolean supportsParameter(ParameterContext parameterContext, ExtensionCon
 		return HttpServer.class.equals(parameterContext.getParameter().getType());
 	}
 
+	//end::user_guide[]
+	@SuppressWarnings({ "DataFlowIssue", "NullAway" })
+	//tag::user_guide[]
 	@Override
 	public Object resolveParameter(ParameterContext parameterContext, ExtensionContext extensionContext) {
 		return extensionContext

documentation/src/test/java/example/session/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.session;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/sharedresources/SharedResourceDemo.java

@@ -24,6 +24,7 @@
 
 class SharedResourceDemo {
 
+	@SuppressWarnings({ "DataFlowIssue", "NullAway" })
 	//tag::user_guide[]
 	@Test
 	void runBothCustomEnginesTest() {

documentation/src/test/java/example/sharedresources/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.sharedresources;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/testinterface/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.testinterface;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/testkit/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.testkit;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/example/timing/TimingExtension.java

@@ -36,12 +36,15 @@ public class TimingExtension implements BeforeTestExecutionCallback, AfterTestEx
 	private static final String START_TIME = "start time";
 
 	@Override
-	public void beforeTestExecution(ExtensionContext context) throws Exception {
+	public void beforeTestExecution(ExtensionContext context) {
 		getStore(context).put(START_TIME, System.currentTimeMillis());
 	}
 
+	//end::user_guide[]
+	@SuppressWarnings({ "DataFlowIssue", "NullAway" })
+	//tag::user_guide[]
 	@Override
-	public void afterTestExecution(ExtensionContext context) throws Exception {
+	public void afterTestExecution(ExtensionContext context) {
 		Method testMethod = context.getRequiredTestMethod();
 		long startTime = getStore(context).remove(START_TIME, long.class);
 		long duration = System.currentTimeMillis() - startTime;

documentation/src/test/java/example/timing/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.timing;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java/extensions/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package extensions;
+
+import org.jspecify.annotations.NullMarked;

documentation/src/test/java21/example/ParameterizedLifecycleDemo.java

@@ -17,6 +17,7 @@
 import java.nio.file.Path;
 import java.util.List;
 
+import org.jspecify.annotations.Nullable;
 import org.junit.jupiter.api.Nested;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.io.TempDir;
@@ -53,6 +54,9 @@ static void beforeInvocation(TextFile textFile, @TempDir Path tempDir) throws Ex
 			textFile.path = Files.writeString(filePath, textFile.content);
 		}
 
+		//end::user_guide[]
+		@SuppressWarnings({ "DataFlowIssue", "NullAway" })
+		//tag::user_guide[]
 		@AfterParameterizedClassInvocation
 		static void afterInvocation(TextFile textFile) throws Exception {
 			var actualContent = Files.readString(textFile.path); // <3>
@@ -61,6 +65,9 @@ static void afterInvocation(TextFile textFile) throws Exception {
 			// File will be deleted automatically by @TempDir support
 		}
 
+		//end::user_guide[]
+		@SuppressWarnings({ "DataFlowIssue", "NullAway" })
+		//tag::user_guide[]
 		@Test
 		void test() {
 			assertTrue(Files.exists(textFile.path)); // <2>
@@ -75,6 +82,9 @@ static class TextFile {
 
 			final String fileName;
 			final String content;
+			// end::example[]
+			@Nullable
+			// tag::example[]
 			Path path;
 
 			TextFile(String fileName, String content) {

documentation/src/test/java21/example/package-info.java

@@ -0,0 +1,5 @@
+
+@NullMarked
+package example;
+
+import org.jspecify.annotations.NullMarked;