initial real plugin (#1)

Author: esword

README.md

@@ -2,11 +2,110 @@
    <a href="https://autorelease.general.dmz.palantir.tech/palantir/gradle-plugin-testing"><img src="https://img.shields.io/badge/Perform%20an-Autorelease-success.svg" alt="Autorelease"></a>
 </p>
 
-## About gradle-plugin-testing
+# About
 
-Gradle plugin and helpers to assist with writing tests for other gradle plugins
+Gradle plugin and helpers to assist with writing tests for other gradle plugins.
 
-### Built With
+## Using the Plugin
+    
+ ```groovy
+apply plugin: 'com.palantir.gradle-plugin-testing'
+ ```
 
-* Groovy
-* Java
+The plugin automatically adds a `testImplementation` dependency on the `com.palantir.gradle.plugintesting:plugin-testing-core` library so that the helper classes are available in tests.
+
+# Primary Functionality
+
+## Automatic suppression of gradle deprecation warnings
+The nebula-test framework will automatically fail a test if it detects gradle deprecation messages in the output.  Unfortunately, this will fail if another plugin used in a test is using deprecated gradle components even if the actual plugin under test is clean.  The plugin-testing plugin will automatically set the `ignoreDeprecations` system property so that the nebula-test framework will ignore deprecation messages.  Use other mechanisms, such as java deprecation linting, to detect and fix deprecations in the plugin under test.
+
+This behavior can be overridden using the `gradleTestUtils` extension.  e.g.
+
+```groovy
+gradleTestUtils {
+    ignoreGradleDeprecations = false
+}
+```
+
+## Resolution of dependencies in generated build files
+Integration tests for Gradle plugins often write build files which include other plugins.  The version of those included plugins is hardcoded in some way, either directly in the test, e.g.
+
+```groovy
+//...within a nebula spec...
+  buildFile << """
+     buildscript {
+         repositories {
+             mavenCentral()
+         }
+         dependencies {
+             classpath 'com.palantir.gradle.conjure:gradle-conjure:0.0.1'
+         }
+     }
+     dependencies {
+         implementation 'com.palantir.conjure.java:conjure-lib:0.0.1'
+     }
+     """
+```
+
+or in some "Versions" class that has a listing of all the dependencies the test uses.  e.g. 
+```java
+final class TestPluginVersions {
+    static final String CONJURE_JAVA = "com.palantir.conjure.java:conjure-java:5.7.1";
+    static final String CONJURE = "com.palantir.conjure:conjure:4.10.1";
+```
+
+Once these tests are written, the versions of the plugins are often not updated, even when the project under test keeps its dependencies of those plugins up-to-date.  This can cause tests to fail when the plugin is updated not because the plugin is bad, but because there is an incompatibility in the old versions of plugins used in the integration tests.  This can often happen with Gradle version bumps.
+
+When applied to a project, the `gradle-plugin-testing` plugin scans the `testRuntimeClasspath` configuration for the project and passes all dependencies to the test task as a system property.  The version of the dependencies can then be resolved when tests are run and written into generated files.  e.g.
+
+```groovy
+import static com.palantir.gradle.plugintesting.TestDependencyVersions.resolve
+import nebula.test.IntegrationSpec
+
+class HelloWorldSpec extends IntegrationSpec {
+   def setup() {
+       //language=gradle
+       buildFile << """
+        buildscript {
+            repositories {
+                mavenCentral()
+            }
+            dependencies {
+                classpath '${resolve('com.palantir.gradle.conjure:gradle-conjure')}'
+            }
+        }
+        dependencies {
+            implementation '${resolve('com.palantir.conjure.java:conjure-lib')}'
+        }
+        """
+   }
+```
+# Resolution of Gradle versions to test against
+Similarly, tests may hardcode versions of Gradle that they need to stay compatible with. These versions also get stale and PRs start failing for the inverse reason of the above - the code in the plugin or a dependency of it is updated and is no longer compatible with an old version of Gradle. For example, attempting to update jackson libraries from `2.15.0` -> `2.17.0` would fail if a test tried to run on Gradle versiosn < `7.6.4` (when compatibility with jackson `2.17.0` was fixed).
+
+The `GradleTestVersions` class can provide up-to-date versions of Gradle to test against.  
+```groovy
+import nebula.test.IntegrationSpec
+import com.palantir.gradle.plugintesting.GradleTestVersions
+
+class HelloWorldSpec extends IntegrationSpec {
+    def 'runs on version of gradle: #version'() {
+        when:
+        gradleVersion = version
+
+        then:
+        def result = runTasks('someTask')
+        result.success
+
+        where:
+        version << GradleTestVersions.gradleVersionsForTests
+    }
+}
+```
+The plugin sets default versions to test against, but these can be overridden using the `gradleTestUtils` extension.  e.g.
+
+```groovy
+gradleTestUtils {
+    gradleVersions = ['7.6.4', '8.8']
+}
+```

changelog/@unreleased/pr-1.v2.yml

@@ -0,0 +1,5 @@
+type: feature
+feature:
+  description: initial real plugin
+  links:
+  - https://github.com/palantir/gradle-plugin-testing/pull/1

gradle-plugin-testing/build.gradle

@@ -4,9 +4,10 @@ apply plugin: 'com.palantir.external-publish-jar'
 apply plugin: 'com.palantir.external-publish-gradle-plugin'
 
 dependencies {
-    compileOnly gradleApi()
+    implementation project(':plugin-testing-core')
+    implementation 'com.google.guava:guava'
 
-    testImplementation gradleTestKit()
+    testImplementation 'org.junit.jupiter:junit-jupiter'
     testImplementation 'com.netflix.nebula:nebula-test'
 }
 
@@ -16,11 +17,20 @@ gradlePlugin {
 
     plugins {
         pluginTestingPlugin {
-            id = 'com.palantir.plugin-testing'
+            id = 'com.palantir.gradle-plugin-testing'
             displayName = 'Palantir Plugin for testing other gradle plugins'
             description = 'A Gradle plugin that detects failures in CircleCI jobs and converts them into JUnit test reports that can be rendered in CircleCI UI.'
             tags.set(['failure', 'report', 'reporting', 'circleci'])
             implementationClass = 'com.palantir.gradle.plugintesting.PluginTestingPlugin'
         }
     }
 }
+
+test {
+    systemProperty 'projectVersion', project.version
+    //TODO(#xxx): Remove this once we have a published version of the plugin that we can apply to the project itself
+    systemProperty 'ignoreDeprecations', 'true'
+
+    // Added as a jar the so in nebula-tests needs to exist in maven local
+    dependsOn tasks.findByPath(':plugin-testing-core:publishToMavenLocal')
+}

gradle-plugin-testing/src/main/java/com/palantir/gradle/plugintesting/PluginTestingExtension.java

@@ -0,0 +1,42 @@
+/*
+ * (c) Copyright 2024 Palantir Technologies Inc. All rights reserved.
+ *
+ * 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 com.palantir.gradle.plugintesting;
+
+import org.gradle.api.provider.Property;
+import org.gradle.api.provider.SetProperty;
+
+public abstract class PluginTestingExtension {
+    public static final String EXTENSION_NAME = "gradleTestUtils";
+
+    /**
+     * Whether to set the ignoreDeprecations system property when running tests.  This is for nebula tests that will
+     * fail if there are gradle deprecations.
+     */
+    public abstract Property<Boolean> getIgnoreGradleDeprecations();
+
+    /**
+     * Gradle versions to test against.
+     */
+    public abstract SetProperty<String> getGradleVersions();
+
+    public PluginTestingExtension() {
+        getIgnoreGradleDeprecations().convention(true);
+        // TODO(#XXX): Should this be the latest gradle 8, or maybe whatever this plugin is compiled against?
+        // or is this the set of "milestone" versions and we dynamically add the version of the consuming project?
+        getGradleVersions().convention(GradleTestVersions.DEFAULT_TEST_GRADLE_VERSIONS);
+    }
+}

gradle-plugin-testing/src/main/java/com/palantir/gradle/plugintesting/PluginTestingPlugin.java

@@ -16,13 +16,95 @@
 
 package com.palantir.gradle.plugintesting;
 
+import java.util.Optional;
+import java.util.Set;
+import java.util.stream.Collectors;
+import org.gradle.api.Action;
+import org.gradle.api.NamedDomainObjectProvider;
 import org.gradle.api.Plugin;
 import org.gradle.api.Project;
+import org.gradle.api.Task;
+import org.gradle.api.artifacts.Configuration;
+import org.gradle.api.artifacts.ModuleDependency;
+import org.gradle.api.tasks.SourceSet;
+import org.gradle.api.tasks.SourceSetContainer;
+import org.gradle.api.tasks.testing.Test;
 
 public class PluginTestingPlugin implements Plugin<Project> {
+    /**
+     * Used in tests to pick up the current version of this plugin.
+     */
+    static final String PLUGIN_VERSION_PROPERTY_NAME = "pluginTestingPluginVersion";
 
+    /**
+     * Applies the plugin to the given project.
+     */
     @Override
-    public final void apply(Project project) {
-        project.getTasks().register("plugintestingTask", PluginTestingTask.class);
+    public void apply(Project project) {
+        PluginTestingExtension testUtilsExt =
+                project.getExtensions().create(PluginTestingExtension.EXTENSION_NAME, PluginTestingExtension.class);
+
+        addTestDependency(project);
+
+        SourceSetContainer sourceSetContainer = project.getExtensions().getByType(SourceSetContainer.class);
+        SourceSet sourceSet = sourceSetContainer.getByName(SourceSet.TEST_SOURCE_SET_NAME);
+        NamedDomainObjectProvider<Configuration> testRuntimeConfig =
+                project.getConfigurations().named(sourceSet.getRuntimeClasspathConfigurationName());
+
+        project.getTasks().withType(Test.class).configureEach(test -> {
+            // need to use the doFirst so that any custom settings on the extension are applied before reading
+            // the values and setting the system properties.
+            Action<Task> action = new Action<>() {
+                @Override
+                public void execute(Task _task) {
+                    // add system property for all test dependencies so that TestDepVersions can resolve them
+                    Set<String> depSet = getDependencyStrings(testRuntimeConfig.get());
+                    String depsString = String.join(",", depSet);
+                    test.systemProperty(TestDependencyVersions.TEST_DEPENDENCIES_SYSTEM_PROPERTY, depsString);
+
+                    // add system property for what versions of gradle should be used in tests
+                    String versions =
+                            String.join(",", testUtilsExt.getGradleVersions().get());
+                    test.systemProperty(GradleTestVersions.TEST_GRADLE_VERSIONS_SYSTEM_PROPERTY, versions);
+
+                    // add system property to ignore gradle deprecations so that nebula tests don't fail
+                    if (testUtilsExt.getIgnoreGradleDeprecations().get()) {
+                        // from
+                        // https://github.com/nebula-plugins/nebula-test/blob/main/src/main/groovy/nebula/test/IntegrationBase.groovy
+                        test.systemProperty("ignoreDeprecations", "true");
+                    }
+                }
+            };
+            test.doFirst(action);
+        });
+    }
+
+    /**
+     * Add test dependency on the utility jar to the project so that an explicit dependency statement isn't needed.
+     * This is done by getting the Implementation-Version metainfo from the compiled jar when this plugin is used
+     * for real, but that doesn't work when running tests in this repo, so we can also look it up via a gradle property
+     * that tests set.
+     */
+    private static void addTestDependency(Project project) {
+        SourceSetContainer sourceSetContainer = project.getExtensions().getByType(SourceSetContainer.class);
+        SourceSet testSourceSet = sourceSetContainer.getByName(SourceSet.TEST_SOURCE_SET_NAME);
+        String version = Optional.ofNullable((String) project.findProperty(PLUGIN_VERSION_PROPERTY_NAME))
+                .or(() -> Optional.ofNullable(
+                        PluginTestingPlugin.class.getPackage().getImplementationVersion()))
+                .orElseThrow(() -> new RuntimeException("PluginTestingPlugin implementation version not found"));
+
+        String testImplConfigName = testSourceSet.getImplementationConfigurationName();
+        project.getConfigurations().named(testImplConfigName).configure(conf -> {
+            conf.getDependencies()
+                    .add(project.getDependencies()
+                            .create("com.palantir.gradle.plugintesting:plugin-testing-core:" + version));
+        });
+    }
+
+    private static Set<String> getDependencyStrings(Configuration config) {
+        return config.getAllDependencies().stream()
+                .filter(ModuleDependency.class::isInstance)
+                .map(dep -> dep.getGroup() + ":" + dep.getName() + ":" + dep.getVersion())
+                .collect(Collectors.toSet());
     }
 }