Enable NullAway in documentation

marcphilipp · marcphilipp · commit 62797b0a56a8 · 2025-05-23T15:55:42.000+02:00
diff --git a/documentation/documentation.gradle.kts b/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")
 }
diff --git a/documentation/src/test/java/example/ClassTemplateDemo.java b/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
diff --git a/documentation/src/test/java/example/DynamicTestsDemo.java b/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");
diff --git a/documentation/src/test/java/example/FirstCustomEngine.java b/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
diff --git a/documentation/src/test/java/example/ParameterizedTestDemo.java b/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> {
 
diff --git a/documentation/src/test/java/example/SecondCustomEngine.java b/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
diff --git a/documentation/src/test/java/example/TestingAStackDemo.java b/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<>();
diff --git a/documentation/src/test/java/example/callbacks/package-info.java b/documentation/src/test/java/example/callbacks/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.callbacks;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/defaultmethods/package-info.java b/documentation/src/test/java/example/defaultmethods/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.defaultmethods;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/exception/package-info.java b/documentation/src/test/java/example/exception/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.exception;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/extensions/HttpServerExtension.java b/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);
diff --git a/documentation/src/test/java/example/extensions/RandomNumberDemo.java b/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
diff --git a/documentation/src/test/java/example/extensions/RandomNumberExtension.java b/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()));
diff --git a/documentation/src/test/java/example/extensions/package-info.java b/documentation/src/test/java/example/extensions/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.extensions;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/interceptor/package-info.java b/documentation/src/test/java/example/interceptor/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.interceptor;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/package-info.java b/documentation/src/test/java/example/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/registration/DocumentationDemo.java b/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);
 	}
 
diff --git a/documentation/src/test/java/example/registration/package-info.java b/documentation/src/test/java/example/registration/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.registration;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/session/HttpTests.java b/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
diff --git a/documentation/src/test/java/example/session/package-info.java b/documentation/src/test/java/example/session/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.session;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/sharedresources/SharedResourceDemo.java b/documentation/src/test/java/example/sharedresources/SharedResourceDemo.java
@@ -24,6 +24,7 @@
 
 class SharedResourceDemo {
 
+	@SuppressWarnings({ "DataFlowIssue", "NullAway" })
 	//tag::user_guide[]
 	@Test
 	void runBothCustomEnginesTest() {
diff --git a/documentation/src/test/java/example/sharedresources/package-info.java b/documentation/src/test/java/example/sharedresources/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.sharedresources;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/testinterface/package-info.java b/documentation/src/test/java/example/testinterface/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.testinterface;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/testkit/package-info.java b/documentation/src/test/java/example/testkit/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.testkit;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/example/timing/TimingExtension.java b/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;
diff --git a/documentation/src/test/java/example/timing/package-info.java b/documentation/src/test/java/example/timing/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example.timing;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java/extensions/package-info.java b/documentation/src/test/java/extensions/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package extensions;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/documentation/src/test/java21/example/ParameterizedLifecycleDemo.java b/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) {
diff --git a/documentation/src/test/java21/example/package-info.java b/documentation/src/test/java21/example/package-info.java
@@ -0,0 +1,5 @@
+
+@NullMarked
+package example;
+
+import org.jspecify.annotations.NullMarked;
diff --git a/gradle/plugins/common/src/main/kotlin/junitbuild.java-nullability-conventions.gradle.kts b/gradle/plugins/common/src/main/kotlin/junitbuild.java-nullability-conventions.gradle.kts
@@ -26,7 +26,7 @@ tasks.withType<JavaCompile>().configureEach {
 	}
 }
 
-tasks.compileTestJava {
+tasks.withType<JavaCompile>().named { it.startsWith("compileTest") }.configureEach {
 	options.errorprone.nullaway {
 		handleTestAssertionLibraries = true
 		excludedFieldAnnotations.addAll(

Original file line number	Diff line number	Diff line change
`@@ -18,6 +18,7 @@ plugins {`
`18`	`18`	`alias(libs.plugins.plantuml)`
`19`	`19`	`id("junitbuild.build-parameters")`
`20`	`20`	`id("junitbuild.java-multi-release-test-sources")`
	`21`	`+ id("junitbuild.java-nullability-conventions")`
`21`	`22`	`id("junitbuild.kotlin-library-conventions")`
`22`	`23`	`id("junitbuild.testing-conventions")`
`23`	`24`	`}`