Part 7: Use a Consumer Project

Learn how to set up a dummy consumer project to test your plugin without publishing it.

In this section, you’ll:

Create a consumer project to use your plugin.
Configure a Composite Build to link the consumer and plugin projects.
Test your plugin in a real-world scenario.

Step 0: Before you Begin

You initialized your plugin in part 1.
You added an extension to your plugin in part 2.
You created a custom task in part3.
You wrote a unit test in part 4.
You added a dataflow action to your plugin in part 5.
You wrote a functional test in part 6.

Step 1: Create a Consumer Project

We will now create a separate consumer project. This is a best practice for testing plugins because it simulates how a real user would apply your plugin to their own project. It also allows you to test your plugin without publishing it to a repository like the Gradle Plugin Portal.

First, update your project structure to include a new consumer directory:

.
├── gradlew
├── settings.gradle.kts
├── plugin/
└── consumer/   (1)
    ├── settings.gradle.kts
    └── build.gradle.kts

1	Create a new `consumer` directory with its own build files.

.
├── gradlew
├── settings.gradle
├── plugin/
└── consumer/   (1)
    ├── settings.gradle
    └── build.gradle

1	Create a new `consumer` directory with its own build files.

Next, we’ll configure a Composite Build by updating the root settings.gradle(.kts) file. This tells Gradle to treat the plugin project as an included build.

settings.gradle.kts

rootProject.name = "plugin-tutorial"

includeBuild("consumer")

settings.gradle

rootProject.name = 'plugin-tutorial'

includeBuild('consumer')

The key line here is includeBuild("plugin") inside the pluginManagement {} block. This makes all the plugins from the plugin project available to other projects in the composite build by their ID.

Finally, we need to update the plugin’s build file to account for the composite build setup. We’ll change the `id from a local file to a standard String.

plugin/build.gradle.kts

plugins {
    // Apply the Java Gradle plugin development plugin to add support for developing Gradle plugins
    `java-gradle-plugin`
    // Apply the Kotlin JVM plugin to add support for Kotlin.
    /*
    alias(libs.plugins.kotlin.jvm)
     */
    id("org.jetbrains.kotlin.jvm") version "2.0.0"
}

plugin/build.gradle

dependencies {
    // Use the awesome Spock testing and specification framework
    /*
    testImplementation libs.spock.core
     */
    testImplementation 'org.spockframework:spock-core:2.3-groovy-4.0'
    testRuntimeOnly 'org.junit.platform:junit-platform-launcher'
    // Use the Java Slack Client APIs
    implementation("com.slack.api:slack-api-client:1.45.3")
}

In a Composite Build, the plugin project no longer has access to the root libs.versions.toml file. For this tutorial, we are using direct dependency declarations.

Step 2: Wire the Consumer Project to the Plugin

Now we’ll configure the consumer project’s settings file to apply our plugin.

Add this code to consumer/settings.gradle(.kts):

consumer/settings.gradle.kts

pluginManagement {
    includeBuild("../plugin")
    repositories {
        gradlePluginPortal()
    }
}
rootProject.name = "consumer"

consumer/settings.gradle

pluginManagement {
    includeBuild("../plugin")
    repositories {
        gradlePluginPortal()
    }
}
rootProject.name = "consumer"

This tells Gradle that when it encounters a plugins block that references your org.example.slack plugin, it should look for the plugin in the plugin project of the composite build.

Step 3: Apply and Configure the Plugin in the Consumer

Now, let’s configure the consumer project’s build.gradle(.kts) file to actually apply and configure our plugin.

consumer/build.gradle.kts

plugins {
    id("java")
    id("org.example.slack")
}


repositories {
    mavenCentral()
}

slack {
    token.set(System.getenv("SLACK_TOKEN"))
    channel.set("#social")
    message.set("Hello from consumer via composite build!")
}

consumer/build.gradle

plugins {
    id("java")
    id("org.example.slack")
}


repositories {
    mavenCentral()
}

slack {
    token.set(System.getenv("SLACK_TOKEN"))
    channel.set("#social")
    message.set("Hello from consumer via composite build!")
}

Notice that we don’t need a version for the plugin! Gradle automatically resolves it from the included build.

Step 4: Run the Consumer Project

You can now test your plugin by running a task in the consumer project.

From the consumer directory, you can run your custom task:

$ ./gradlew sendTestSlackMessage

Or, from the root directory, you can run the same task using its full path:

$ ./gradlew :consumer:sendTestSlackMessage

You can also run a standard lifecycle task like build, which will automatically trigger the FlowAction to send a Slack notification at the end of the build.

$ ./gradlew :consumer:build

You can now iterate on your plugin in the plugin directory and test it immediately in the consumer project without any publishing overhead.

Next Step: Publish your Plugin Locally >>