Document support for Java records as test classes

Resolves #3892.

Author: marcphilipp

documentation/documentation.gradle.kts

@@ -13,6 +13,7 @@ plugins {
 	alias(libs.plugins.gitPublish)
 	alias(libs.plugins.plantuml)
 	id("junitbuild.build-parameters")
+	id("junitbuild.java-multi-release-test-sources")
 	id("junitbuild.kotlin-library-conventions")
 	id("junitbuild.testing-conventions")
 }
@@ -313,6 +314,13 @@ tasks {
 			inputs.dir(kotlin.srcDirs.first())
 		}
 
+		sourceSets["testRelease21"].apply {
+			attributes(mapOf(
+				"testRelease21Dir" to java.srcDirs.first()
+			))
+			inputs.dir(java.srcDirs.first())
+		}
+
 		jvm {
 			// To avoid warning, see https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/597
 			jvmArgs(

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

@@ -1,3 +1,7 @@
+:testDir: ../../../../src/test/java
+:testRelease21Dir: ../../../../src/test/java21
+:kotlinTestDir: ../../../../src/test/kotlin
+
 [[writing-tests]]
 == Writing Tests
 
@@ -120,6 +124,7 @@ Test Class::
 any top-level class, `static` member class, or <<writing-tests-nested,
 `@Nested` class>> that contains at least one _test method_, i.e. a _container_.
 Test classes must not be `abstract` and must have a single constructor.
+Java `record` classes are supported as well.
 
 Test Method::
 any instance method that is directly annotated or meta-annotated with
@@ -178,6 +183,15 @@ lifecycle methods. For further information on runtime semantics, see
 include::{testDir}/example/StandardTests.java[tags=user_guide]
 ----
 
+It is also possible to use Java `record` classes as test classes as illustrated by the
+following example.
+
+[source,java,indent=0]
+.A test class written as a Java record
+----
+include::{testRelease21Dir}/example/MyFirstJUnitJupiterRecordTests.java[tags=user_guide]
+----
+
 [[writing-tests-display-names]]
 === Display Names
 

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

@@ -0,0 +1,28 @@
+/*
+ * Copyright 2015-2024 the original author or authors.
+ *
+ * All rights reserved. This program and the accompanying materials are
+ * made available under the terms of the Eclipse Public License v2.0 which
+ * accompanies this distribution and is available at
+ *
+ * https://www.eclipse.org/legal/epl-v20.html
+ */
+
+package example;
+
+// tag::user_guide[]
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import example.util.Calculator;
+
+import org.junit.jupiter.api.Test;
+
+record MyFirstJUnitJupiterRecordTests() {
+
+	@Test
+	void addition() {
+		assertEquals(2, new Calculator().add(1, 1));
+	}
+
+}
+// end::user_guide[]

gradle/plugins/common/src/main/kotlin/junitbuild.java-multi-release-test-sources.gradle.kts

@@ -0,0 +1,42 @@
+import junitbuild.extensions.capitalized
+
+plugins {
+	id("junitbuild.java-library-conventions")
+}
+
+listOf(21).forEach { javaVersion ->
+	val sourceSet = sourceSets.register("testRelease${javaVersion}") {
+		compileClasspath += sourceSets.main.get().output
+		runtimeClasspath += sourceSets.main.get().output
+		java {
+			setSrcDirs(setOf("src/test/java${javaVersion}"))
+		}
+	}
+
+	configurations {
+		named(sourceSet.get().compileClasspathConfigurationName).configure {
+			extendsFrom(configurations.testCompileClasspath.get())
+		}
+		named(sourceSet.get().runtimeClasspathConfigurationName).configure {
+			extendsFrom(configurations.testRuntimeClasspath.get())
+		}
+	}
+
+	tasks {
+		val testTask = register<Test>("testRelease${javaVersion}") {
+			group = "verification"
+			description = "Runs the tests for Java ${javaVersion}"
+			testClassesDirs = sourceSet.get().output.classesDirs
+			classpath = sourceSet.get().runtimeClasspath
+		}
+		check {
+			dependsOn(testTask)
+		}
+		named<JavaCompile>(sourceSet.get().compileJavaTaskName).configure {
+			options.release = javaVersion
+		}
+		named<Checkstyle>("checkstyle${sourceSet.name.capitalized()}").configure {
+			config = resources.text.fromFile(checkstyle.configDirectory.file("checkstyleTest.xml"))
+		}
+	}
+}