Use JUnit 5 and remove JUnit 4 API dependencies

docs/README.adoc

@@ -135,7 +135,7 @@ You can verify samples either through one of the <<verifying-using-a-junit-runne
 
 ==== Verifying using a JUnit Runner
 
-This library provides 2 JUnit runners link:../samples-check/src/main/java/org/gradle/exemplar/test/runner/SamplesRunner.java[`SamplesRunner`] (executes via CLI) and link:../samples-check/src/main/java/org/gradle/exemplar/test/runner/GradleSamplesRunner.java[`GradleSamplesRunner`] (executes samples using https://docs.gradle.org/current/userguide/test_kit.html[Gradle TestKit]). If you are using `GradleSamplesRunner`, you will need to add `gradleTestKit()` and SLF4J binding dependencies as well:
+This library provides 2 JUnit runners link:../samples-check/src/main/java/org/gradle/exemplar/test/runner/SamplesRunner.java[`SamplesRunner`] (executes via CLI) and link:../samples-check/src/main/java/org/gradle/exemplar/test/runner/GradleSamplesRunner.java[`GradleSamplesRunner`] (executes samples using https://docs.gradle.org/current/userguide/test_kit.html[Gradle TestKit]). If you are using `GradleSamplesExtension`, you will need to add `gradleTestKit()` and SLF4J binding dependencies as well:
 
 [source,kotlin]
 ----
@@ -145,7 +145,7 @@ dependencies {
 }
 ----
 
-*NOTE:* `GradleSamplesRunner` supports Java 8 and above and ignores tests when running on Java 7 or lower.
+*NOTE:* `GradleSamplesExtension` supports Java 8 and above and ignores tests when running on Java 7 or lower.
 
 To use them, just create a JUnit test class in your test sources (maybe something like `src/integTest/com/example/SamplesIntegrationTest.java`, https://docs.gradle.org/current/userguide/java_testing.html#sec:configuring_java_integration_tests[keeping these slow tests separate] from your fast unit tests.) and annotate it with which JUnit runner implementation you'd like and where to find samples.
 Like this:
@@ -264,7 +264,7 @@ For example, you might prepend a `Command` that sets up some environment before
 
 === Custom Gradle installation
 
-To allow Gradle itself to run using test versions of Gradle, the `GradleSamplesRunner` allows a custom installation to be injected using the system property "integTest.gradleHomeDir".
+To allow Gradle itself to run using test versions of Gradle, the `GradleSamplesExtension` allows a custom installation to be injected using the system property "integTest.gradleHomeDir".
 
 == Contributing
 

docs/build.gradle.kts

@@ -7,6 +7,5 @@ dependencies {
 }
 
 tasks.test {
-    useJUnit()
     inputs.file("README.adoc").withPathSensitivity(PathSensitivity.RELATIVE)
 }

docs/src/test/java/org/gradle/exemplar/ReadmeTest.java

@@ -15,11 +15,15 @@
  */
 package org.gradle.exemplar;
 
-import org.gradle.exemplar.test.runner.GradleEmbeddedSamplesRunner;
-import org.gradle.exemplar.test.runner.SamplesRoot;
-import org.junit.runner.RunWith;
+import org.gradle.exemplar.test.Samples;
+import org.gradle.exemplar.test.engine.GradleSamplesExtension;
 
-@RunWith(GradleEmbeddedSamplesRunner.class)
-@SamplesRoot(".")
+import static org.gradle.exemplar.test.Samples.SamplesType.EMBEDDED;
+
+@Samples(root = ".",
+        samplesType = EMBEDDED,
+        implicitRootDirSupplier = GradleSamplesExtension.ImplicitSamplesRootDirSupplier.class,
+        commandExecutorFunction = GradleSamplesExtension.GradleCommandExecutorFunction.class
+)
 public class ReadmeTest {
 }

gradle/libs.versions.toml

@@ -1,5 +1,6 @@
 [versions]
 spock = "2.0-groovy-3.0"
+junit-platform = "1.8.1"
 
 [libraries]
 asciidoctorj = "org.asciidoctor:asciidoctorj:1.5.8.1"
@@ -9,6 +10,8 @@ commons-lang3 = "org.apache.commons:commons-lang3:3.12.0"
 groovy = "org.codehaus.groovy:groovy:3.0.8"
 junit = "junit:junit:4.13.2"
 junit-vintage-engine = "org.junit.vintage:junit-vintage-engine:5.8.1"
+junit-platform-engine = { module="org.junit.platform:junit-platform-engine", version.ref="junit-platform" }
+junit-platform-launcher = { module="org.junit.platform:junit-platform-launcher", version.ref="junit-platform" }
 jsr305 = "com.google.code.findbugs:jsr305:3.0.2"
 objenesis = "org.objenesis:objenesis:3.2"
 spock-core = { module="org.spockframework:spock-core", version.ref="spock" }

samples-check/build.gradle.kts

@@ -9,6 +9,8 @@ dependencies {
     compileOnly(libs.jsr305)
     implementation(libs.commons.io)
     implementation(libs.commons.lang3)
+    implementation(libs.junit.platform.engine)
+    implementation(libs.junit.platform.launcher)
     implementation(gradleTestKit())
     testImplementation(libs.cglib)
     testImplementation(libs.groovy)

samples-check/src/main/java/org/gradle/exemplar/test/NoopOutputNormalizer.java

@@ -0,0 +1,11 @@
+package org.gradle.exemplar.test;
+
+import org.gradle.exemplar.executor.ExecutionMetadata;
+import org.gradle.exemplar.test.normalizer.OutputNormalizer;
+
+public class NoopOutputNormalizer implements OutputNormalizer {
+    @Override
+    public String normalize(String commandOutput, ExecutionMetadata executionMetadata) {
+        return commandOutput;
+    }
+}

samples-check/src/main/java/org/gradle/exemplar/test/NoopRootDirSupplier.java

@@ -0,0 +1,11 @@
+package org.gradle.exemplar.test;
+
+import java.io.File;
+import java.util.function.Supplier;
+
+public class NoopRootDirSupplier implements Supplier<File> {
+    @Override
+    public File get() {
+        return null;
+    }
+}

samples-check/src/main/java/org/gradle/exemplar/test/NoopSampleModifier.java

@@ -0,0 +1,10 @@
+package org.gradle.exemplar.test;
+
+import org.gradle.exemplar.model.Sample;
+
+public class NoopSampleModifier implements SampleModifier {
+    @Override
+    public Sample modify(Sample sampleIn) {
+        return sampleIn;
+    }
+}

samples-check/src/main/java/org/gradle/exemplar/test/runner/SampleModifier.java → samples-check/src/main/java/org/gradle/exemplar/test/SampleModifier.java

@@ -13,7 +13,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.gradle.exemplar.test.runner;
+package org.gradle.exemplar.test;
 
 import org.gradle.exemplar.model.Sample;
 

samples-check/src/main/java/org/gradle/exemplar/test/Samples.java

@@ -0,0 +1,54 @@
+/*
+ * Copyright 2018 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.gradle.exemplar.test;
+
+import org.gradle.exemplar.executor.CommandExecutor;
+import org.gradle.exemplar.test.engine.CommandExecutorParams;
+import org.gradle.exemplar.test.engine.DefaultCommandExecutorFunction;
+import org.gradle.exemplar.test.normalizer.OutputNormalizer;
+
+import java.io.File;
+import java.lang.annotation.Documented;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Inherited;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+import java.util.function.Function;
+import java.util.function.Supplier;
+
+@Documented
+@Inherited
+@Target(ElementType.TYPE)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface Samples {
+    String root();
+
+    SamplesType samplesType() default SamplesType.DEFAULT;
+
+    Class<? extends SampleModifier>[] modifiers() default { NoopSampleModifier.class };
+
+    Class<? extends OutputNormalizer>[] outputNormalizers() default { NoopOutputNormalizer.class };
+
+    Class<? extends Supplier<File>> implicitRootDirSupplier() default NoopRootDirSupplier.class;
+
+    Class<? extends Function<CommandExecutorParams, CommandExecutor>> commandExecutorFunction() default DefaultCommandExecutorFunction.class;
+
+    enum SamplesType {
+        DEFAULT,
+        EMBEDDED
+    }
+}

samples-check/src/main/java/org/gradle/exemplar/test/engine/CommandExecutorFunction.java

@@ -0,0 +1,8 @@
+package org.gradle.exemplar.test.engine;
+
+import org.gradle.exemplar.executor.CommandExecutor;
+
+import java.util.function.Function;
+
+public interface CommandExecutorFunction extends Function<CommandExecutorParams, CommandExecutor> {
+}

samples-check/src/main/java/org/gradle/exemplar/test/engine/CommandExecutorParams.java

@@ -0,0 +1,19 @@
+package org.gradle.exemplar.test.engine;
+
+import org.gradle.exemplar.executor.ExecutionMetadata;
+import org.gradle.exemplar.model.Command;
+
+import java.io.File;
+
+public class CommandExecutorParams {
+    final ExecutionMetadata executionMetadata;
+    final File workingDir;
+    final Command command;
+
+    public CommandExecutorParams(ExecutionMetadata executionMetadata, File workingDir, Command command) {
+        this.executionMetadata = executionMetadata;
+        this.workingDir = workingDir;
+        this.command = command;
+    }
+
+}

samples-check/src/main/java/org/gradle/exemplar/test/engine/DefaultCommandExecutorFunction.java

@@ -0,0 +1,11 @@
+package org.gradle.exemplar.test.engine;
+
+import org.gradle.exemplar.executor.CliCommandExecutor;
+import org.gradle.exemplar.executor.CommandExecutor;
+
+public class DefaultCommandExecutorFunction implements CommandExecutorFunction {
+    @Override
+    public CommandExecutor apply(CommandExecutorParams params) {
+        return new CliCommandExecutor(params.workingDir);
+    }
+}

samples-check/src/main/java/org/gradle/exemplar/test/runner/GradleSamplesRunner.java → samples-check/src/main/java/org/gradle/exemplar/test/engine/GradleSamplesExtension.java

@@ -13,75 +13,65 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-package org.gradle.exemplar.test.runner;
+package org.gradle.exemplar.test.engine;
 
 import org.gradle.api.JavaVersion;
 import org.gradle.exemplar.executor.CliCommandExecutor;
 import org.gradle.exemplar.executor.CommandExecutor;
-import org.gradle.exemplar.executor.ExecutionMetadata;
 import org.gradle.exemplar.executor.GradleRunnerCommandExecutor;
-import org.gradle.exemplar.model.Command;
 import org.gradle.exemplar.model.Sample;
-import org.junit.Rule;
-import org.junit.rules.TemporaryFolder;
-import org.junit.runners.model.InitializationError;
 
 import javax.annotation.Nullable;
 import java.io.File;
+import java.util.function.Function;
+import java.util.function.Supplier;
 
-/**
- * A custom implementation of {@link SamplesRunner} that uses the Gradle Tooling API to execute sample builds.
- */
-public class GradleSamplesRunner extends SamplesRunner {
+public class GradleSamplesExtension {
     private static final String GRADLE_EXECUTABLE = "gradle";
-    @Rule
-    public TemporaryFolder tempGradleUserHomeDir = new TemporaryFolder();
-    private File customGradleInstallation = null;
-
-    public GradleSamplesRunner(Class<?> testClass) throws InitializationError {
-        super(testClass);
-    }
+    private static File customGradleInstallation = null;
 
     /**
      * Gradle samples tests are ignored on Java 7 and below.
      */
-    @Override
     protected boolean isIgnored(Sample child) {
         return !JavaVersion.current().isJava8Compatible();
     }
 
-    @Override
-    protected CommandExecutor selectExecutor(ExecutionMetadata executionMetadata, File workingDir, Command command) {
-        boolean expectFailure = command.isExpectFailure();
-        if (command.getExecutable().equals(GRADLE_EXECUTABLE)) {
-            return new GradleRunnerCommandExecutor(workingDir, customGradleInstallation, expectFailure);
+    public static class GradleCommandExecutorFunction implements CommandExecutorFunction {
+        @Override
+        public CommandExecutor apply(CommandExecutorParams params) {
+            boolean expectFailure = params.command.isExpectFailure();
+            if (params.command.getExecutable().equals(GRADLE_EXECUTABLE)) {
+                return new GradleRunnerCommandExecutor(params.workingDir, customGradleInstallation, expectFailure);
+            }
+            return new CliCommandExecutor(params.workingDir);
         }
-        return new CliCommandExecutor(workingDir);
     }
 
-    @Nullable
-    @Override
-    protected File getImplicitSamplesRootDir() {
-        String gradleHomeDir = getCustomGradleInstallationFromSystemProperty();
-        if (System.getProperty("integTest.samplesdir") != null) {
-            String samplesRootProperty = System.getProperty("integTest.samplesdir", gradleHomeDir + "/samples");
-            return new File(samplesRootProperty);
-        } else if (customGradleInstallation != null) {
-            return new File(customGradleInstallation, "samples");
-        } else {
-            return null;
+    public static class ImplicitSamplesRootDirSupplier implements Supplier<File> {
+        @Override
+        public File get() {
+            String gradleHomeDir = getCustomGradleInstallationFromSystemProperty();
+            if (System.getProperty("integTest.samplesdir") != null) {
+                String samplesRootProperty = System.getProperty("integTest.samplesdir", gradleHomeDir + "/samples");
+                return new File(samplesRootProperty);
+            } else if (customGradleInstallation != null) {
+                return new File(customGradleInstallation, "samples");
+            } else {
+                return null;
+            }
         }
     }
 
     @Nullable
-    private String getCustomGradleInstallationFromSystemProperty() {
+    private static String getCustomGradleInstallationFromSystemProperty() {
         // Allow Gradle installation and samples root dir to be set from a system property
         // This is to allow Gradle to test Gradle installations during integration testing
         final String gradleHomeDirProperty = System.getProperty("integTest.gradleHomeDir");
         if (gradleHomeDirProperty != null) {
             File customGradleInstallationDir = new File(gradleHomeDirProperty);
             if (customGradleInstallationDir.exists()) {
-                this.customGradleInstallation = customGradleInstallationDir;
+                customGradleInstallation = customGradleInstallationDir;
             } else {
                 throw new RuntimeException(String.format("Custom Gradle installation dir at %s was not found", gradleHomeDirProperty));
             }