Partner Plugin "pimutationmate‐override‐plugin"

Why another plugin?

To scope the PITest runs appropriately we need to override the gradle-pitest-plugin's settings. Specifically important is the ability to override the targetClasses and optionally the targetTests and reportDir settings. At the time this is only possible using a dedicated gradle plugin since the gradle-pitest-plugin only allows overriding a handful of settings from the commandline (additionalFeatures and targetTests). There are Issues (like #166 and #349) to allow overriding more options but development progress is slow and it is not deemed likely that a PullRequest would be accepted in time for the release of the PITmutationmate plugin. The new partner plugin is written in groovy and very closely reflects the now archived gradle-override-plugin just with a much more narrow focus on the pitest settings needed for the PITmutationmate Intellij plugin. The mentioned gradle-override-plugin cannot be used because it does now allow for overriding of more complex structures like Sets which are needed to override the targetClasses setting of the gradle-pitest-plugin.

How does it work?

The partner plugin reads all passed command line arguments to a gradle run (via the -D switch) every time a gradle run is started. It selects those that are prefixed with our prefix pitmutationmate.override.. These arguments are checked against our supported PITest arguments listed here. If it is a valid setting, the plugin gets the PitestPluginExtension object from the gradle-pitest-plugin via reflection and overrides the current object's value.

Supported Pitest settings

• targetClasses
• targetTests
• outputFormats
• reportDir
• verbose
• includeLaunchClasspath
• timestampedReports
• threads

How can I use the partner plugin?

As a user of the PITmutationmate Intellij Plugin

As a user the only thing that is required for the partner plugin to do it's job is to add the plugin import to your build.gradle or build.gradle.kts plugins section:

build.gradle

plugins {
    id 'io.github.amosproj.pitmutationmate.override' version '1.0'
}

or build.gradle.kts

plugins {
    id("io.github.amosproj.pitmutationmate.override") version "1.0"
}

Now the partner plugin will inspect the command line arguments to any gradle task run and override the pitest settings if given the right arguments.

As a developer developing the PITmutationmate plugin

1. Install groovy (instructions here)
2. Perform the steps from the previous section
3. Make sure the consuming project has the mavenLocal repository set in its settings.gradle[.kts]:

   pluginManagement {
       repositories {
           gradlePluginPortal()
           mavenLocal()
           mavenCentral()
       }
   }
   

4. Publish the partner plugin to your local maven repository from within the partner plugins project folder:

   cd pitmutationmate-override-plugin
   ./gradlew publishToMavenLocal
   

Gradle will now find the partner plugin in your local maven repository without a need for it to be present in a public repository.

Debugging the partner plugin

To debug the plugin use this tutorial.

To summarize the tutorial:

1. Create a new run configuration Remote Configuration. Give it a name but keep all the other settings unchanged.
2. Make sure all steps from the previous section are performed.
3. Manually run the gradle task from the command line in the consuming project:

   ./gradlew pitest -Dorg.gradle.debug=true -Dpitmutationmate.override.verbose=true --no-daemon
   

   The task will wait with its execution until a remote debugger is attached.
4. Run the in 1. created remote task in debug mode (click the bug icon with the task selected)
5. Debug...