Searching for problems

There are two types of problems you may face:

• On first run (with cache enabled) gradle could indicate problems with configuration state serialization . Not always obvious to track, but, ususallly, quite easy to fix.

• On second run (from cache) there might be problems because of incorrect assumptions. For example, you rely on build service data (filled at configuration time), which is not preserved when running from cache (build service state not serialized).

We will see both types of problems below.

Access project at runtime

The simplest and the most popular problem is using not allowed objects at runtime. Most likely, you’ll face project usage in task:

public abstract class Fail1Task extends DefaultTask {

    @TaskAction
    public void run() {
        System.out.println("[run] Task executed for project: " + getProject().getName());
    }
}

And a very simple plugin:

public abstract class Fail1Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
          project.getTasks().register("fail1Task", Fail1Task.class);
    }
}

It will fail to run fail1Task --configuration-cache --configuration-cache-problems=warn

Calculating task graph as no cached configuration is available for tasks: fail1Task

> Task :fail1Task
[run] Task executed for project: junit14814233387960710613

1 problem was found storing the configuration cache.
- Task `:fail1Task` of type `ru.vyarus.gradle.plugin.fails.fail1.Fail1Task`: invocation of 'Task.project' at execution time is unsupported.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:use_project_during_execution

See the complete report at file:///tmp/junit14814233387960710613/build/reports/configuration-cache/2n0qomukpcgdka6np2vpry01g/a4zpdprgh0056ayfdj5dwvtkk/configuration-cache-report.html

[Incubating] Problems report is available at: file:///tmp/junit14814233387960710613/build/reports/problems/problems-report.html

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored with 1 problem.

Note: configuration-cache-problems=warn is used to prevent build failure for simpler output (without stacktraces) and to show some additional side effects (in later cases).

To fix this, project object access must be moved to configuration phase. It could be done by storing required data in task property in the constructor (called at configuration time):

public abstract class Fail1FixTask extends DefaultTask {

    private final String projectName;

    public Fail1FixTask() {
        projectName = getProject().getName();
    }

    @TaskAction
    public void run() {
        System.out.println("[run] Task executed for project: " + projectName);
    }
}

Or, with provider (if state resolution must be delayed):

public abstract class Fail1Fix2Task extends DefaultTask {

    private final Provider<String> projectName;

    public Fail1Fix2Task() {
        projectName = getProject().provider(() -> getProject().getName());
    }

    @TaskAction
    public void run() {
        System.out.println("[run] Task executed for project: " + projectName.get());
    }
}

IMPORTANT: Cases with other gradle objects are not shown becuase they are clearly described in the docs.

Project usage in plugin

Project (or other not allowed objects) usage at plugin’s run block also fails. The plugin blow access project in the task’s doLast block (executed at runtime):

public abstract class Fail2Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        System.out.println("[configuration] Project name: " + project.getName());

        project.getTasks().register("fail2Task", task ->  {
            task.doLast(task1 ->
                    System.out.println("[run] Project name: " + project.getName()));
        });
    }
}

Even with cache warnings enabled, task execution will fail
fail2Task --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: fail2Task

> Configure project :
[configuration] Project name: junit16727929338108926619

> Task :fail2Task FAILED

2 problems were found storing the configuration cache.
- Task `:fail2Task` of type `org.gradle.api.DefaultTask`: cannot deserialize object of type 'org.gradle.api.Project' as these are not supported with the configuration cache.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:disallowed_types
- Task `:fail2Task` of type `org.gradle.api.DefaultTask`: cannot serialize object of type 'org.gradle.api.internal.project.DefaultProject', a subtype of 'org.gradle.api.Project', as these are not supported with the configuration cache.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:disallowed_types

See the complete report at file:///tmp/junit16727929338108926619/build/reports/configuration-cache/47ehjfb227oo5kzbg615m5h3q/dghkqx053bip47mmv9kiov6f3/configuration-cache-report.html

[Incubating] Problems report is available at: file:///tmp/junit16727929338108926619/build/reports/problems/problems-report.html

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':fail2Task'.
> Cannot invoke "org.gradle.api.Project.getName()" because "project" is null

* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task ':fail2Task'.
...    
Caused by: java.lang.NullPointerException: Cannot invoke "org.gradle.api.Project.getName()" because "project" is null
...

BUILD FAILED in 3s
1 actionable task: 1 executed
Configuration cache entry stored with 2 problems.

It failed with NullPointerException becuase, even on first run, it serialize and deserialize state, required for runtime blocks (in the separate task case above, the project call was a part of runtime action, not configuration).

Same as with task case, the fix is to store required data in a variable or using provider in configuration phase:

    @Override
    public void apply(Project project) {

        final String projectName = project.getName();
        project.getTasks().register("fail2Fix", task ->  {
            task.doLast(task1 ->
                    System.out.println("[run] Project name: " + projectName));
        });

        final Provider<String> nameProvider = project.provider(() -> {
            System.out.println("[configuration] Provider called");
            return project.getName();
        });
        project.getTasks().register("fail2Fix2", task ->  {
            task.doLast(task1 ->
                    System.out.println("[run] Project name: " + nameProvider.get()));
        });
    }

Running fail2Fix fail2Fix2 --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: fail2Fix fail2Fix2
[configuration] Provider called

> Task :fail2Fix2
[run] Project name: junit17295962152626235093

> Task :fail2Fix
[run] Project name: junit17295962152626235093

BUILD SUCCESSFUL in 3s
2 actionable tasks: 2 executed
Configuration cache entry stored.

(the order of tasks is not determinate as they run in parallel)

Runtime blocks in plugin is the main “problem” for configuration cache: it applies much efforts analyzing them to serialize (only) required configuration state.

Too broad serialization

This is the most annoying problem as gradle can’t hint you about its source. For example, here is an extension with not serializable object (SourceSet):

public class Fail3Extension {

    public Set<SourceSet> sets;
    public String message;

    public Fail3Extension(Project project) {
        this.sets = project.getExtensions().getByType(JavaPluginExtension.class).getSourceSets();
    }
}

Plugin only use string extension property at runtime (and does not call not serializable property!):

public class Fail3Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        Fail3Extension ext = project.getExtensions().create("fail3", Fail3Extension.class, project);

        project.getTasks().register("fail3Task", task ->  {
            task.doLast(task1 ->
                    System.out.println("[run] Message: " + ext.message));
        });
    }
}

But gradle would try to serialize the entire extension here (object, referenced at runtime)
fail3Task --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: fail3Task

> Task :fail3Task
[run] Message: Configured!

2 problems were found storing the configuration cache.
- Task `:fail3Task` of type `org.gradle.api.DefaultTask`: cannot deserialize object of type 'org.gradle.api.tasks.SourceSetContainer' as these are not supported with the configuration cache.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:disallowed_types
- Task `:fail3Task` of type `org.gradle.api.DefaultTask`: cannot serialize object of type 'org.gradle.api.internal.tasks.DefaultSourceSetContainer', a subtype of 'org.gradle.api.tasks.SourceSetContainer', as these are not supported with the configuration cache.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:disallowed_types

See the complete report at file:///tmp/junit10544361871289601409/build/reports/configuration-cache/5tucq48qd6ozznv386suhaql7/9u8dhuyl2ja1knarlvrf25z8q/configuration-cache-report.html

[Incubating] Problems report is available at: file:///tmp/junit10544361871289601409/build/reports/problems/problems-report.html

BUILD SUCCESSFUL in 2s
1 actionable task: 1 executed
Configuration cache entry stored with 2 problems.

You can see here that gradle only points you to a not serializable type and you must analyze all runtime blocks yourself to understand the source of problem.

To fix this particular problem, reduce caches scope by assigninig exact required data to a variable in the configuration phase:

@Override
public void apply(Project project) {
    Fail3Extension ext = project.getExtensions().create("fail3", Fail3Extension.class, project);

    project.getTasks().register("fail3Task", task ->  {
        // reduce serialization scope
        String message = ext.message;
        task.doLast(task1 ->
                System.out.println("[run] Message: " + message));
    });
}

Here variable is assigned in the task’s lazy initialization block (and so user configuration is applied). It is important to not assign variable too early as user configuration may not be applied, like here:

// it would be NULL! Too early
String message = ext.message;
project.getTasks().register("fail3Task", task ->  {
    task.doLast(task1 ->
            System.out.println("[run] Message: " + message));
});

With provider the exact declaration place is not important:

Provider<String> message = project.provider(() -> ext.message);
project.getTasks().register("fail3Task", task ->  {
    task.doLast(task1 ->
            System.out.println("[run] Message: " + message));
});

Local variable, cachable or non-cachable (ValueSource) provider usage is the magic wand for configuration cache compatiblity.

The difference of plugin and task serialization

Tasks and plugins are serialized differently! To show it, we will store not allowed object (SourceSet) in task and plugin fields, but will not use it at runtime.

The task:

public abstract class Fail4Task extends DefaultTask {

    private SourceSet sourceSet;
    private String name;

    public Fail4Task() {
        sourceSet = getProject().getExtensions().getByType(JavaPluginExtension.class).getSourceSets().getByName("main");
        name = sourceSet.getName();
    }

    @TaskAction
    public void run() {
        System.out.println("[run] Task source set: " + name);
    }
}

The plugin:

public class Fail4Plugin implements Plugin<Project> {

    private SourceSet sourceSet;

    @Override
    public void apply(Project project) {
        sourceSet = project.getExtensions().getByType(JavaPluginExtension.class).getSourceSets().getByName("test");

        project.getTasks().register("fail4Task", Fail4Task.class, task ->  {
            String set = sourceSet.getName();
            task.doLast(task1 ->
                    System.out.println("[run] Project source set: " + set));
        });
    }
}

Run task fail4Task --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: fail4Task

> Task :fail4Task
[run] Task source set: main
[run] Project source set: test

2 problems were found storing the configuration cache.
- Task `:fail4Task` of type `ru.vyarus.gradle.plugin.fails.fail4.Fail4Task`: cannot deserialize object of type 'org.gradle.api.tasks.SourceSet' as these are not supported with the configuration cache.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:disallowed_types
- Task `:fail4Task` of type `ru.vyarus.gradle.plugin.fails.fail4.Fail4Task`: cannot serialize object of type 'org.gradle.api.internal.tasks.DefaultSourceSet', a subtype of 'org.gradle.api.tasks.SourceSet', as these are not supported with the configuration cache.
  See https://docs.gradle.org/8.13/userguide/configuration_cache.html#config_cache:requirements:disallowed_types

See the complete report at file:///tmp/junit3909871766538813794/build/reports/configuration-cache/ej5hwigx1x3swf7o2d6u9466r/6lf4x0dgeq19zwf53mjr1wh3t/configuration-cache-report.html

[Incubating] Problems report is available at: file:///tmp/junit3909871766538813794/build/reports/problems/problems-report.html

BUILD SUCCESSFU
1 actionable task: 1 executed
Configuration cache entry stored with 2 problems.

Gradle complains only about the task! So the task is serialized completely, but the plugin is not!

It would be easy to proove, just fixing the task:

public class Fail4FixTask extends DefaultTask {

    private String name;

    public Fail4FixTask() {
        SourceSet sourceSet = getProject().getExtensions()
                .getByType(JavaPluginExtension.class).getSourceSets().getByName("main");
        name = sourceSet.getName();
    }

    @TaskAction
    public void run() {
        System.out.println("[run] Task source set: " + name);
    }
}

Run fail4Fix --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: fail4Fix

> Task :fail4Fix
[run] Task source set: main
[run] Project source set: test

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

No problems! So you can use plugin’s private fields to store any data you need, just don’t reference it in runtime blocks (or wrap access with providers, producing something serializable).

Listening tasks

This is not stricly related to the configuration cache, but it would be important to highlight this behavor before the next chapter, covering build services.

Suppose you need to do somethig after a task execution (always), but you don’t control the task (3rd party plugin’s task). You have 2 (conf.cache - legal) ways: use doLast block and build service as listener.

The catch is: doLast block will not be called if task is not executed. Task is not executed when it’s UP-TO-DATEor FROM-CACHE (when build cache enabled). So the only way to always detect task execution is by using build service.

Lets check. Here is a simple build service, listening for tasks:

public abstract class Service implements BuildService<BuildServiceParameters.None>,
        OperationCompletionListener {

    @Override
    public void onFinish(FinishEvent finishEvent) {
        System.out.println("[run] Finish event: " + finishEvent.getDescriptor().getName());
    }
}

Task with output file (cachable):

public abstract class Sample8Task extends DefaultTask {

    @OutputFile
    public abstract Property<File> getOut();

    @TaskAction
    public void run() throws Exception {
        System.out.println("[run] Task executed");
        File out = getOut().get();

        BufferedWriter writer = new BufferedWriter(new FileWriter(out));
        writer.append("Sample file content");
        writer.close();
    }
}

And plugin, declaring the task and configuring doLast block:

public abstract class Sample8Plugin implements Plugin<Project> {

    @Inject
    public abstract BuildEventsListenerRegistry getEventsListenerRegistry();

    @Override
    public void apply(Project project) {
        // service listen for tasks
        final Provider<Service> service = project.getGradle().getSharedServices().registerIfAbsent(
                "service", Service.class);
        getEventsListenerRegistry().onTaskCompletion(service);

        project.getTasks().register("sample8Task", Sample8Task.class, task -> {
            task.getOut().set(project.getLayout().getBuildDirectory()
                        .dir("sample8/out.txt").get().getAsFile());
            task.doLast(t -> System.out.println("[run] doLast for sample8Task"));
        });
    }
}

Run sample8Task --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: sample8Task

> Task :sample8Task
[run] Task executed
[run] doLast for sample8Task
[run] Finish event: :sample8Task

BUILD SUCCESSFUL in 3s
1 actionable task: 1 executed
Configuration cache entry stored.

Both doLast and build service executed.

Run again sample8Task --configuration-cache --configuration-cache-problems=warn:

Reusing configuration cache.
> Task :sample8Task UP-TO-DATE
Finish event: :sample8Task

BUILD SUCCESSFUL in 80ms
1 actionable task: 1 up-to-date
Configuration cache entry reused.

The tasks is UP-TO-DATE and so doLast was not called, but the build service was notified.

The only problem with build service is that it does not provide you a task instance, only task path. So you may need to store some additional task data, collected at configuration phase.

Caching data in build service

Build service cache parameters state at the time of service creation. Any further paramters modifications would not be serializaed (will be lost after the current tasks execution).

Sample service:

public abstract class Service implements BuildService<Service.Params> {

    public Service() {
        System.out.println("Service created with state: " + getParameters().getValues().get());
    }

    interface Params extends BuildServiceParameters {
        ListProperty<String> getValues();
    }
}

Plugin:

public class Sample7Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        final List<String> values = new ArrayList<>();

        Provider<Service> service = project.getGradle().getSharedServices().registerIfAbsent(
                "service", Service.class, spec -> {
                    // initial "persisted storage" value
                    spec.getParameters().getValues().value(values);
                });

        values.add("val1");
        values.add("val2");

        project.getTasks().register("sample7Task", task ->
                task.doFirst(task1 ->
                        System.out.println("Task see state: " + service.get().getParameters().getValues().get()))
        );
    }
}

Service will initialize only at runtime and so the collected configuration state would be preserved.

First run sample7Task --configuration-cache --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: sample7Task

> Task :sample7Task
Service created with state: [val1, val2]
Task see state: [val1, val2]

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Second run sample7Task --configuration-cache --configuration-cache-problems=warn:

Reusing configuration cache.

> Task :sample7Task
Service created with state: [val1, val2]
Task see state: [val1, val2]

BUILD SUCCESSFUL in 67ms
1 actionable task: 1 executed
Configuration cache entry reused.

State, prepared in plugin during configuration phase was serialized in service parameter.

What is important:

• Required state is collected in plugin field

• The field is used to initialize service parameter (on creation)

• Service is not initializard during configuration phase

In the majority of cases, this trick (almost hack) would not be required becuase you can simply cache the value returned from service instead of re-recovering real service state. For example:

project.getTasks().register("sample7Task", task ->
        // would be cached, because its referenced in run block
        List<String> state = service.get().getParameters().getValues().get()
        task.doFirst(task1 ->
                System.out.println("Task see state: " + state))
);

Here service state would be cached and run from cache will not use the service at all.

The case when such caching is not possible is described below (as a real life example).

The real case

The case I faced updating my quality plugin: the plugin is listening for quality tasks (from 3rd party plugins: pmd, checkstyle, findbugs, etc.) and print detected problems into console, using xml reports (produced by quality trasks). As you have seen above, the only way to always print console report after a task is to use build service (all quality tasks are cachable). But build service will receive just a task path, so information about reportable quality tasks must be collected under configuration phase (and cached).

doLast block is called just after the task whereas build service (as task listener) could be called a bit later and doLast it is better for performing output (to print it just below the task output and inside of output of some other task, executed concurrently).

Using both methods (doLast and service) would lead to duplicate output, and so some “execution marker” must be stored somewhere to avoid duplicates. That’s why it would not be possible to just cache service state in a variable (in this case each task would have its own instance of cache and will not see an “execution marker”). So full service state recovery is required.

Simple service, which must contain the required information about tasks:

public abstract class Service implements BuildService<Service.Params>,
                    OperationCompletionListener {

    @Override
    public void onFinish(FinishEvent finishEvent) {
        if (finishEvent instanceof TaskFinishEvent) {
            // not important for example, just showing for completeness
            TaskFinishEvent taskEvent = (TaskFinishEvent) finishEvent
            String taskPath = taskEvent.descriptor.taskPath;
            TaskDesc desc = getParameters().getValues().get().stream()
                .filter(it -> it.path.equals(taskPath))
                .findFirst().orElse(null)
            // do something, knowing additional task data
             if (desc != null) {
                if (!desc.isCalled()) {
                    System.out.println("Task " + taskPath + " listened by service");
                    desc.setCalled(true);
                } else {
                    System.out.println("Task " + taskPath + " listened, but ignored");
                }
            }
        }
    }

    interface Params extends BuildServiceParameters {
        // will hold all required data, prepared by plugin
        ListProperty<TaskDesc> getValues();
    }
}

TaskDesc is a simpe value class (with properties only):

public class TaskDesc implements Serializable {
    private String name;
    private String path;
    private boolean called;

    public TaskDesc() {
    }

    public TaskDesc(String name, String path) {
        this.name = name;
        this.path = path;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPath() {
        return path;
    }

    public void setPath(String path) {
        this.path = path;
    }

    public boolean isCalled() {
        return called;
    }

    public void setCalled(boolean called) {
        this.called = called;
    }

    @Override
    public String toString() {
        return name;
    }
}

The plugin register task and prepare a collection for caching in service parameter:

public abstract class Sample7Plugin implements Plugin<Project> {

    @Inject
    public abstract BuildEventsListenerRegistry getEventsListenerRegistry();

    // collecting tasks info during configuration phase
    private final List<TaskDesc> tasksInfo = new ArrayList<>();

    @Override
    public void apply(Project project) {
        // service 1 with "state" in a private field
        Provider<Service> service = project.getGradle().getSharedServices()
                .registerIfAbsent("service", Service.class, spec -> 
                    // on first creation, service will cache list value, but it is important
                    // to not create it too early
                    spec.getParameters().getValues().set(tasksInfo));

        getEventsListenerRegistry().onTaskCompletion(service);

        // tasks to demostrate behavior
        project.getTasks().register("task1", TrackedTask.class);
        project.getTasks().register("task2", TrackedTask.class);

        project.getTasks().withType(TrackedTask.class).configureEach(task -> {
                captureTaskInfo(task);
                task.doLast(task1 -> {
                    final TaskDesc desc = service.get().getParameters().getValues().get().stream()
                            .filter(taskDesc -> taskDesc.getPath().equals(task.getPath()))
                            .findAny().orElse(null);
                    if (!desc.isCalled()) {
                        System.out.println("Task " + task1.getName() + " doLast");
                        desc.setCalled(true);
                    }
                });
        });
    }

    private void captureTaskInfo(Task task) {
         System.out.println("Store task descriptor: " + task.getName());
         tasksInfo.add(new TaskDesc(task.getName(), task.getPath()));
    }
}

Creating cache task1, task2, --configuration-cache, --configuration-cache-problems=warn:

Calculating task graph as no cached configuration is available for tasks: task1 task2

> Configure project :
Service configured: []
Store task descriptor: task1
Store task descriptor: task2

> Task :task1
Service created with state: [task1, task2]
Task task1 doLast

> Task :task2
Task task2 doLast
Task :task1 listened, but ignored
Task :task2 listened, but ignored

BUILD SUCCESSFUL in 3s
2 actionable tasks: 2 executed
Configuration cache entry stored.

Run from cache task1, task2, --configuration-cache, --configuration-cache-problems=warn:

Reusing configuration cache.

> Task :task1
Service created with state: [task1, task2]
Task task1 doLast

> Task :task2
Task task2 doLast
Task :task1 listened, but ignored
Task :task2 listened, but ignored

BUILD SUCCESSFUL in 74ms
2 actionable tasks: 2 executed
Configuration cache entry reused.

In this example sample task was not cachable and so here doLast was called, but, as you can see, listener is also called and has access to task data (and so in case of cachable task would work correctly).

For sure, this is an edge case, which you, most likely, would never face. Its here just to show what is possible under configuration cache.

Multi-module builds

Configuration cache may force you to use build services, but it is important to keep in mind that you plugin might be used in a multi-module build.

If the plugin from parameters caching sample would be used in the multi-module build like this:

plugins {
    id 'com.mycompany.myplugin' version '1.0' apply false
}

subprojects {
    apply plugin: 'com.mycompany.myplugin'
}

Then each module would create it’s own plugin instance with it’s own inner state. So the trick like this would not work anymore:

    @Override
    public void apply(Project project) {
        // in multi-module project each module would create this list
        final List<String> values = new ArrayList<>();

        // but the service is global (initiated just once)
        Provider<Service> service = project.getGradle().getSharedServices().registerIfAbsent(
                "service", Service.class, spec -> {
                    spec.getParameters().getValues().value(values);
                });

        ...
    }

The service is global, and so only one configuration will be applied (from one subproject) and, as the result, it would contain the state, collected in one subproject only!

The simple workaround is to use separate service instances per project, by modifying service name:

Provider<Service> service = project.getGradle().getSharedServices().registerIfAbsent(
        "service" + project.getName(), Service.class, spec -> {
             // initial "persisted storage" value
            spec.getParameters().getValues().value(values);
        });

For example, plugin in subproject “sub” would create service “servicesub”.

Note: you may have problems with the global service only in advanced cases when you have to store state in such service (in parameters, using plugin’s variable).

Different classpaths

Another possible multi-module case is if your plugin would be applied independently in submodules:

// pseudo configuration (in real life it would be different config files)

subrojects("sub1") {
    plugins {
        id 'com.mycompany.myplugin' version '1.0'
    }
}

subrojects("sub2") {
    plugins {
        id 'com.mycompany.myplugin' version '1.0'
    }
}

Then plugins would be loaded in different classpaths and so they would not be able to use a global service (there would be “class cannot be cast to class” error becuase service classes would be different in modules).

Just pay attention to this moment - in most cases, project-scoped service is a better way.

Jococo

When running TestKit-based tests with enabled jococo plugin (for coverage), you'll always have an issue:

1 problem was found storing the configuration cache.
- Gradle runtime: support for using a Java agent with TestKit builds is not yet implemented with the configuration cache.
  See https://docs.gradle.org/8.14.3/userguide/configuration_cache.html#config_cache:not_yet_implemented:testkit_build_with_java_agent

But, it's not a critical problem: test must check that it was THE ONLY problem:

BuildResult result = run('someTask', '--configuration-cache', '--configuration-cache-problems=warn');
Assertions.assertThat(result.getOutput()).contains(
                "1 problem was found storing the configuration cache",
                "Gradle runtime: support for using a Java agent with TestKit",
                "Calculating task graph as no cached configuration is available for tasks:"
);

See repository tests for complete configuration cache testing example.

Summary

The summary does not change from part 1.

Just paying additional attention to the “magic wand” for configuration cache compatibilty:

1. Assigning state to a variable (at correct time) could easilly reduce serialization scope

2. Provider could “move” code execution from runtime into configuration phase (so let you call not allowed staff at runtime).

3. ValueSource workarounds caching

In most cases, its simpler to let gradle cache state (with variable or provider), instead of reproducing it under the cache.

it is safier to create build service per plugin instance, instead of global due to potential problems in multi-module projects.

Not allowed gradle projects replacements are perfectly described in the gradle docs.
The only case in my practice that wasn’t described there was project.getAntBuilder() usage in task. In groovy plugin, the solution was to use groovy’s AntBuilder (not gradle builder) directly (new AntBuilder()…).
The runtime objects restrictions mostly driven by configuration state preserved in the disallowed objects, but direct usage of anything (not implicitly aware of gradle state) is completely fine.

Article split into two parts (kind of theory and practice):

Part 1 shows how configuration cache works (by examples). It is the best way to learn it because, almost certainly, it works not like you think (if you never deal with it yourself).

Part 2 shows common problems (with example cases) and potential solutions.

Preprequisites

I prepared a github repository with samples. These samples include all described cases, but not exactly follow article samples (article describes cases separately for simplicity, whereas samples check multiple cases at once). You could clone this repo and experiment with samples yourself!

As with any other cache, the configuration cache could be tested by two runs: the first run prepares cache record and the second run validates execution under the cache.

Repository samples use gradle TestKit to verify cache behaviour:

// projectDir - temprorary directory (created per test)
// build.gradle file is created manually (with required test project configuration)

// run to create cache record
BuildResult result = GradleRunner.create()
        .withProjectDir(projectDir)
        .withArguments(List.of("myTask", "--configuration-cache"))
        .withPluginClasspath()
        .forwardOutput()
        .build();

// validation
result.getOutput().contains("Calculating task graph as no cached configuration is available for tasks");

// run again to check cached behaviour
result = GradleRunner.create()
        .withProjectDir(projectDir)
        .withArguments(List.of("myTask", "--configuration-cache"))
        .withPluginClasspath()
        .forwardOutput()
        .build();

// validation
result.getOutput().contains("Reusing configuration cache");

On first execution gradle inidicates cache recording:

Calculating task graph as no cached configuration is available for tasks: sample1Task
…
Configuration cache entry stored.

On second run, gradle would indicate cache usage:

Reusing configuration cache.
…
Configuration cache entry reused.

The executed code

The Configuration Cache builds on this idea of work avoidance and parallelization. When enabled, the Configuration Cache allows Gradle to skip the configuration phase entirely if nothing that affects the build configuration (such as build scripts) has changed. Additionally, Gradle applies performance optimizations to task execution.

gradle guide

This means that under configuration cache, plugin’s code from configuration phase would not be executed.

public abstract class Sample1Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        System.out.println("[configuration] Plugin applied");

        // register custom task
        project.getTasks().register("sampleTask", task -> {
            System.out.println("[configuration] Task configured");

            // the only line that works also under the configuration cache
            task.doFirst(task1 -> System.out.println("[run] Before task"));
        });

        // afterEvaluate often used by plugins as the first point where user configuration applied
        project.afterEvaluate(p -> System.out.println("[configuration] Project evaluated"));
    }
}

First execution: sampleTask —configuration-cache

Calculating task graph as no cached configuration is available for tasks: sampleTask

> Configure project :
[configuration] Plugin applied
[configuration] Project evaluated
[configuration] Task configured

> Task :sampleTask
[run] Before task

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Run from cache: sampleTask —configuration-cache

Reusing configuration cache.

> Task :sampleTask
[run] Before task

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry reused.

As you can see, the code, related to configuration phase, is not called at all. Paying attention: neither plugin, nor any task constructors would not be called under the cache (there is no configuration phase)!

The state

The configuration cache serialize configuration from the first execution and use it for later executions.

Now we will use a simple extension to access user configuration in task:

public class Sample1Extension {
    public String message = "Default";

    public Sample1Extension() {
        System.out.println("[configuration] Extension created")
    }

    public String getMessage() {
        // no prefix because it could be called in both phases
        System.out.println("Extension get message: " + message);
        return message;
    }
}

The plugin will become:

public abstract class Sample1Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        System.out.println("[configuration] Plugin executed");
        Sample1Extension ext = project.getExtensions()
                    .create("sample1", Sample1Extension.class);

        project.getTasks().register("sampleTask", task -> {
            task.doFirst(task1 -> System.out.println("[run] User message: " + ext.message));
        });
    }
}

Project build.gradle would contain:

sample1 {
    message = "hello user!"
}

First execution: sampleTask —configuration-cache

Calculating task graph as no cached configuration is available for tasks: sampleTask

> Configure project :
[configuration] Plugin executed
[configuration] Extension created

> Task :sampleTask
Extension get message: hello user!
[run] User message: hello user!

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Run from cache: sampleTask —configuration-cache

Reusing configuration cache.

> Task :sampleTask
Extension get message: hello user!
[run] User message: hello user!

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry reused.

Pay attention: on the second run extension constructor was not called, but extension getter was!

What happend: on first execution, gradle tracked that ext.message value is used at runtime and so the entire ext object was serialized. On second run, the state was deserialized and the task used it for execution.

Now, what would happen if user configuration would change? Let’s run task the third time, but with updated build.gradle

sample1 {
    message = "changed message!"
}

Run (configuration cache record already exists): sampleTask —configuration-cache

Calculating task graph as configuration cache cannot be reused because file 'build.gradle' has changed.

> Configure project :
[configuration] Plugin executed
[configuration] Extension created

> Task :sampleTask
Extension get message: changed message!
[run] User message: changed message!

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Cache was invalidated, full configuration performed and a new cache record stored.

Plugin state

Let’s see what would happen with plugin’s own fields:

public abstract class Sample1Plugin implements Plugin<Project> {

    private String pluginField;

    public Sample1Plugin() {
        System.out.println("[configuration] Plugin created");
    }

    @Override
    public void apply(Project project) {
        project.afterEvaluate(p -> {
            pluginField = "assigned value";
            System.out.println("[configuration] Project evaluated");
        });

        project.getTasks().register("sampleTask", task -> {
            task.doFirst(task1 -> System.out.println("[run] Before task: " + pluginField));
        });
    }
}

Run sampleTask —configuration-cache:

Calculating task graph as no cached configuration is available for tasks: sample1Task

> Configure project :
[configuration] Plugin created
[configuration] Project evaluated

> Task :sampleTask
[run] Before task: assigned value

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Run from cache sampleTask —configuration-cache:

Reusing configuration cache.

> Task :sample1Task
[run] Before task: assigned value

BUILD SUCCESSFUL in 61ms
1 actionable task: 1 executed
Configuration cache entry reused.

As you can see, plugin fields are serialized.

Task state

Now, let’s see how task fields survive serialization. Use a separate task class:

public abstract class Sample1Task extends DefaultTask {

    @Input
    abstract Property<String> getMessage();
    @Input
    abstract Property<String> getMessage2();

    public String field;
    private String privateField;

    public Sample1Task() {
        System.out.println("[configuration] Task created");
        privateField = "set";
    }

    @TaskAction
    public void run() {
        System.out.println("[run] Task executed: message=" + getMessage().get()
                + ", message2=" + getMessage2().get()
                + ", public field=" + field
                + ", private field=" + privateField);
    }
}

Here we have 2 gradle properties and private and public fields. Plugin would become:

public abstract class Sample1Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        System.out.println("[configuration] Plugin applied");
        final Sample1Extension ext = project.getExtensions()
                                .create("sample1", Sample1Extension.class);

        // register custom task
        project.getTasks().register("sample1Task", Sample1Task.class, task -> {
            task.getMessage().convention(ext.message);
            task.getMessage2().convention("Default");
            task.field = "assigned value";
        });

        // custom (lazy) task configuration
        project.getTasks().withType(Sample1Task.class).configureEach(task -> {
            task.getMessage2().set("Custom");
        });
    }
}

Plugin:

• Set message to extension value

• Set message2 to “Custom” value (in lazy configuration block)

• Public task field assigned to assigned value

The extension class remains the same as above. Configuration file is:

sample1 {
    message = "hello user!"
}

Run it two times sample1Task —configuration-cache (only run from cache is interesting):

Reusing configuration cache.

> Task :sample1Task
Extension get message: hello user!
[run] Task executed: message=hello user!, message2=Custom, public field=assigned value, private field=set

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry reused.

As you can see:

• Task properties values are correct

• Public and private field values are also preserved

So, it is OK to rely on task properties under the configuration cache.

Broken uniquness

One caveat with state serialization is broken uniquness: same object, used at multiple places would become a different objects after deserialization.

We will use a custom object to share state between tasks:

public class SharedState {

    // show how externally assigned values survive
    public String direct;
    public List<String> list = new ArrayList<>();

    public SharedState() {
        System.out.println("[configuration] Shared state created: " + System.identityHashCode(this));
    }

    @Override
    public String toString() {
        return System.identityHashCode(this) + "@" + list.toString() + ", direct=" + direct;
    }
}

And the plugin:

public abstract class Sample2Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        // some object, common for two tasks
        final SharedState state = new SharedState();
        // some value directly assigned
        state.direct = "Custom";

        project.getTasks().register("task1").configure(task ->
                task.doLast(task1 -> {
                    state.list.add("Task 1");
                    System.out.println("[run] Task 1 shared object: " + state);
                }));

        project.getTasks().register("task2").configure(task ->
                task.doLast(task1 -> {
                    state.list.add("Task 2");
                    System.out.println("[run] Task 2 shared object: " + state);
                }));
    }
}

Now run it without cache first task1 task2:

> Configure project :
[configuration] Shared state created: 1353516483

> Task :task1
[run] Task 1 shared object: 1353516483@[Task 1], direct=Custom

> Task :task2
[run] Task 2 shared object: 1353516483@[Task 1, Task 2], direct=Custom

BUILD SUCCESSFUL
2 actionable tasks: 2 executed

The same SharedState object instance is used in tasks.

Run with cache enabled: task1 task2 —configuration-cache

Calculating task graph as no cached configuration is available for tasks: task1 task2

> Configure project :
[configuration] Shared state created: 1202973804

> Task :task2
[run] Task 2 shared object: 1650372210@[Task 2], direct=Custom

> Task :task1
[run] Task 1 shared object: 724264550@[Task 1], direct=Custom

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
Configuration cache entry stored.

We could already see different instances in tasks (its just cache recording phase, but we already see side effects!): obviously, object was serialized and deserialized (because object constructor was called just once)

Running from cache task1 task2 —configuration-cache:

Reusing configuration cache.

> Task :task1
[run] Task 1 shared object: 1796870189@[Task 1], direct=Custom

> Task :task2
[run] Task 2 shared object: 1139607728@[Task 2], direct=Custom

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
Configuration cache entry reused.

Again, two different instances used.

Paying attention: configuration phase execution with the configuration cache enabled is already different from usual gradle execution. But it’s for good: performing configuration state serialization and deserialization even on the first run, gradle reveals many cache-related problems (which otherwise would happen in the second execution (from cache)).

Build services

The only way to workaround uniquness problem is build services.

Ideally, there should be no need to share any data between tasks (in the majority of cases configuration cache should cache required data). But, sometimes, tasks communication is required at runtime.

We will use a service to keep shared state between tasks:

public abstract class SharedService implements BuildService<SharedService.Params>, AutoCloseable {

    public String extParam;
    // tasks might be executed in parallel (this simply avoids ConcurrentModificationException)
    public List<String> list = new CopyOnWriteArrayList<>();

    public SharedService() {
        // could appear both in configuration and execution time
        System.out.println("Shared service created " + System.identityHashCode(this) + "@");
    }

    public interface Params extends BuildServiceParameters {
        Property<String> getExtParam();
    }

    @Override
    public String toString() {
        return System.identityHashCode(this) + "@" + list.toString()
                + ", param: " + getParameters().getExtParam().getOrNull()
                + ", field: " + extParam;
    }

    // IMPORTANT: gradle could close service at any time and start a new instance!
    @Override
    public void close() throws Exception {
        System.out.println("Shared service closed: " + System.identityHashCode(this));
    }
}

The plugin would declare service and two simple tasks:

public abstract class Sample3Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        // IMPORTANT: service not created at this moment!
        final Provider<SharedService> service = project.getGradle().getSharedServices()
                .registerIfAbsent("service", SharedService.class, spec -> {
                        // configuration value set with parameter
                        spec.getParameters().getExtParam().convention("Default");
                    });

        // configuration value set DIRECTLY (after service creation)
        project.afterEvaluate(p -> {
            service.get().extParam = "Custom";
            System.out.println("[configuration] Project evaluated");
        });

        project.getTasks().register("task1").configure(task ->
                task.doLast(task1 -> {
                    final SharedService sharedService = service.get();
                    sharedService.list.add("Task 1");
                    System.out.println("[run] Task 1 shared object: " + sharedService);
                }));

        project.getTasks().register("task2").configure(task -> {
            // just to disable tasks concurrency (simplier to verify output)
            task.mustRunAfter("task1");

            task.doLast(task1 -> {
                final SharedService sharedService = service.get();
                sharedService.list.add("Task 2");
                System.out.println("[run] Task 2 shared object: " + sharedService);
            });
        });
    }
}

First run without cache task1 task2:

> Configure project :
Shared service created 1202901166@
[configuration] Project evaluated

> Task :task1
[run] Task 1 shared object: 1202901166@[Task 1], param: Default, field: Custom

> Task :task2
[run] Task 2 shared object: 1202901166@[Task 1, Task 2], param: Default, field: Custom
Shared service closed: 1202901166

BUILD SUCCESSFUL
2 actionable tasks: 2 executed

Shared service is created in afterEvaluate block (the first time service.get() was called) where its extParam field set to custom value.

The same service instance is used in both tasks. Service is closed after tasks execution.

Run with enabled cache task1 task2 —configuration-cache:

Calculating task graph as no cached configuration is available for tasks: task1 task2

> Configure project :
Shared service created 644777498@
[configuration] Project evaluated
Shared service closed: 644777498

> Task :task1
Shared service created 1665614489@
[run] Task 1 shared object: 1665614489@[Task 1], param: Default, field: null

> Task :task2
[run] Task 2 shared object: 1665614489@[Task 1, Task 2], param: Default, field: null
Shared service closed: 1665614489

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
Configuration cache entry stored.

Behavior is different:

• Service created in afterEvaluate block where its field is initialied

• After configuration phase service is closed! This is intentional gradle behavior under the cache (gradle advice using services only at runtime)!

• A new service instance is created before the first task execution. Direct field value is lost (service fields are not serialized!). Only parameter value preserved (it would be a value applied in service initialization block)

Overall, uniquness preserved: the service instance is the same between tasks, but it is a different instance from configuration phase.

Run from cache task1 task2 —configuration-cache:

Reusing configuration cache.

> Task :task1
Shared service created 1651282902@
[run] Task 1 shared object: 1651282902@[Task 1], param: Default, field: null

> Task :task2
[run] Task 2 shared object: 1651282902@[Task 1, Task 2], param: Default, field: null
Shared service closed: 1651282902

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
Configuration cache entry reused.

The same service instance used, but directly initialized service field value was lost (same as in previous run).

So under configuration cache, the same service instance would be used in run phase. Service, used on configuration phase, would be closed befor run phase.

Prevent service closing

There is a way to prevent service closing before a run phase: service should implement OperationCompletionListener (pretend it would listen for tasks execution):

public abstract class SharedService implements BuildService<SharedServiceSingleton.Params>, AutoCloseable,
        OperationCompletionListener {

    ...

    @Override
    public void onFinish(FinishEvent finishEvent) {
        System.out.println("Finish event: " + finishEvent.getDescriptor().getName() + " caught on service " + this);
    }
}

(the rest is [the same](#build-services))

Plugin should now register service as a listener:

public abstract class Sample3Plugin implements Plugin<Project> {

    @Inject
    public abstract BuildEventsListenerRegistry getEventsListenerRegistry();

    @Override
    public void apply(Project project) {
        ...
        final Provider<SharedServiceSingleton> service = project.getGradle().getSharedServices().registerIfAbsent(
                "service", SharedServiceSingleton.class, spec -> {
                    spec.getParameters().getExtParam().convention("Default");
                });
        // service listens for tasks completion, which prevents gradle from stopping it in 
        // after configuration phase
        getEventsListenerRegistry().onTaskCompletion(service);

        ...
    }
}

Creating cache record task1 task2 --configuration-cache:

Calculating task graph as no cached configuration is available for tasks: task1 task2

> Configure project :
Shared service created 331815390@
[configuration] Project evaluated

> Task :task1
[run] Task 1 shared object: 331815390@[Task 1], param: Default, field: Custom
Finish event: :task1 caught on service 331815390@[Task 1], param: Default, field: Custom

> Task :task2
[run] Task 2 shared object: 331815390@[Task 1, Task 2], param: Default, field: Custom
Finish event: :task2 caught on service 331815390@[Task 1, Task 2], param: Default, field: Custom
Shared service closed: 331815390

BUILD SUCCESSFUL
2 actionable tasks: 2 executed
Configuration cache entry stored.

This time the service was not closed and the same instance is used in configuration and run phases. As a result, service field value is preserved.

But, when it run from cache task1 task2 --configuration-cache:

Reusing configuration cache.

> Task :task1
Shared service created 1976530883@
[run] Task 1 shared object: 1976530883@[Task 1], param: Default, field: null
Finish event: :task1 caught on service 1976530883@[Task 1], param: Default, field: null

> Task :task2
[run] Task 2 shared object: 1976530883@[Task 1, Task 2], param: Default, field: null
Finish event: :task2 caught on service 1976530883@[Task 1, Task 2], param: Default, field: null
Shared service closed: 1976530883

BUILD SUCCESSFUL in 53ms
2 actionable tasks: 2 executed
Configuration cache entry reused.

Service field will again be null because its value was assigned in plugin under configuration phase, which was missed here.

Usually, there is not much sense to use this trick (forcing singleton) because service state is not serialized, only parameters are. But, it make sense when the same instance as in configuration phase is required at runtime.

Moreover, gradle could close the service during runtime too: it tries to guess when service is not required anymore and close it. In complex cases, gradle could guess incorrectly and close service too early. Using the “listener trick” workarounds such cases.

Method calls

Here we will see if method calls are possible from runtime blocks:

public class Sample4Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        project.getTasks().register("task1").configure(task -> {            
            task.doLast(task1 -> {
                System.out.println("[run] Task exec: " + computeMessage("static"));
            });
        });
    }

    private String computeMessage(String source) {
        System.out.println("called computeMessage('" + source + "')");
        return "computed message " + source;
    }
}

Creating cache entry task1 —configuration-cache:

Calculating task graph as no cached configuration is available for tasks: task1

> Task :task1
called computeMessage('static')
[run] Task exec: computed message static

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Run from cache task1 —configuration-cache:

Reusing configuration cache.

> Task :task1
called computeMessage('static')
[run] Task exec: computed message static

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry reused.

As you can see, the method is called under the cache. Note that method was not static - it is a plugin’s instance method.

I will not show it, but there could problems with calling method in groovy plugins due to its dynamic nature. So in groovy plugins, its better to call public static methods.

Providers

Provider is “a magic wand” for dealing with configuration cache problems: it workarounds runtime objects restriction (we will see it in part 2). Here we will only see how provider being cached.

public class Sample4Plugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        project.getTasks().register("task1").configure(task -> {
            Provider<String> provider = project.provider(() -> {
                String res = String.valueOf(project.findProperty("param"));
                System.out.println("Provider called: " + res);
                return res;
            });
            task.doLast(task1 -> {
                System.out.println("[run] Task exec: " + provider.get());
            });
        });
    }
}

Provider use configuration file property just to show how cache invalidates in this case.

First, run without cache task1 -Pparam=1:

> Task :task1
Provider called: 1
Task exec: 1

BUILD SUCCESSFUL
1 actionable task: 1 executed

As expected, provider was called at runtime.

Run with cache enabled task1 -Pparam=1 —configuration-cache

Calculating task graph as no cached configuration is available for tasks: task1
Provider called: 1

> Task :task1
[run] Task exec: 1

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Pay attention that provider was called at configuration time!

Running from cache: task1 -Pparam=1 —configuration-cache

Reusing configuration cache.

> Task :task1
[run] Task exec: 1

Provider not called! It’s value is already stored in cache. As a consequence, you can use any object inside provider because it is executed under configuration time!

And a bonus, what will happen if property value would change task1 -Pparam=2 —configuration-cache:

Calculating task graph as configuration cache cannot be reused because the set of Gradle properties has changed: the value of 'param' was changed.
Provider called: 2

> Task :task1
[run] Task exec: 2

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

Gradle invalidated the cache.

Note that for system properties and environment variables special providers should be used (gradle would not be able to detect change in this case).

Always called providers

Gradle provides a special kind of providers: ValueSource (it’s mentioned in docs). In contrast to usual providers, value source implementations are always called (even under the cache).

Example source implementation:

public abstract class NonCacheableValue implements ValueSource<String, ValueSourceParameters.None> {

    @Override
    public @Nullable String obtain() {
        String val = System.getProperty("foo");
        System.out.println("NonCacheableValue: " + val);
        return val;
    }
}

The plugin:

public class Sample4ValuePlugin implements Plugin<Project> {

    @Override
    public void apply(Project project) {
        project.getTasks().register("task1").configure(task -> {
            final Provider<String> provider = project.getProviders()
                    .of(NonCacheableValue.class, spec -> {});
            task.doLast(task1 -> {
                System.out.println("[run] Task exec: " + provider.get());
            });
        });
    }
}

Run with enabled cache task1 -Dfoo=1 —configuration-cache:

Calculating task graph as no cached configuration is available for tasks: task1

> Task :task1
NonCacheableValue: 1
[run] Task exec: 1

BUILD SUCCESSFUL
1 actionable task: 1 executed
Configuration cache entry stored.

ValueSource (provider) called at runtime (in contrast to usual providers, which are called under configuration phase when cache is enabled).

Run from cache task1 -Dfoo=1 —configuration-cache:

Reusing configuration cache.

> Task :task1
NonCacheableValue: 1
[run] Task exec: 1

BUILD SUCCESSFUL in 73ms
1 actionable task: 1 executed
Configuration cache entry reused.

ValueSource (provider) is called.

Now changing property value task1 -Dfoo=2 —configuration-cache:

Reusing configuration cache.

> Task :task1
NonCacheableValue: 2
[run] Task exec: 2

BUILD SUCCESSFUL in 46ms
1 actionable task: 1 executed
Configuration cache entry reused.

No invalidation required - provider just provide the correct value.

Putting all together

When configuration cache is enabled, gradle would analyze runtime blocks and serialize related state.

• There are no restrictions at configuration time - all restrictions applied at runtime blocks

• Plugin itself, task objects and any other objects would not be created under cache (required objects are deserialized)

• Task and plugin fields are serialized and so availble on cached executions (see part 2 for more details)

• Values from user configuration would be serialized (and so it does not matter for configuration cache if value was directly assigned or taken from the extension)

• Object uniquness (when the same instance used in multiple places) could be lost due to deserializarion

• Build services:

  • Is the only way to keep unique (shared) data between tasks

  • Not serialized, so field values would be lost between executions

  • Remember only parameter values in time of the first service creation

  • Could be closed at any time

  • If service listen for tasks it would not be closed

• It is safe to call methods from runtime blocks (in groovy plugins better call public static methods)

• Provider is called at configuration time (when cache is enabled) and so could use any gradle objects

• ValueSource objects are never cached

• Gradle tracks state change (like user configuration changes) and invalidate cache (but some edge cases are possible)

Read next the part 2 - problems

• Open plugin project and add “remote” configuration (with defaults - it would be port 5005)

• Run gradle: ./gradlew task -Dorg.gradle.debug=true (it will halt waiting for remote debugger attachment)

• Run remote debug in plugin project

All details are in the gradle docs

Note: in case of “port already in use” error, try to stop deamons first (./gradlew —stop) and, if it will not help, search for other java processes occuping the port (lsof -i :5005).

Suppose you developed a library and related examples in a single repository (e.g. examples stored as a separate project in the examples directory). It would be great to not only run library tests on CI, but also check examples compatibility with the latest snapshot. In theory it’s simple: run library tests, publish snapshot and run examples with a just published snapshot.

Previously, I have tried to use github packages for snapshots publication, but this was far from perfect:

1. Github packages are not accessible without authorization - users have to create their own github tokens in order to access snapshots.

2. Each published snapshot is counted as a separate package and so, after some time, you have to clean up outdated versions manually (becuase storage space is limited)

Recently, sonatype sunset OSSRH publication so I have to update my maven central publications and reviewed my snapshots approach.

Maven central snapshots publication specifics:

1. Snapshot is removed after 90 days (more than enough)

2. No signing is required (and overall publication validation is disabled)

3. Published snapshots are available immediately (in contrast to releases, which are available after ~1h)

4. Users would have to use a custom repository to access snapshots (but without required authorization!)

Sonatype configuration

Important: It is assumed that your namespace was already migrated (migration ended on 30th of June 2025). If you did not perform migration manually, it would be performed automatically (in some time).

First of all, snapshots must be enabled for your namespace:

It is also important to generate a new token. Even if you already have token, generated before June 30th, it’s better to re-generate it (there are many messages on the sonatype forum about 401 problems with the old tokens).

Open https://central.sonatype.com/account and hit “generate token”. Copy generated tokens (user and password tokens) because window will close in 1 minute.

Project configuration

In spite of the fact that OSSRH is shut down, sonatype provides a OSSRH-compatible publication API. With it you can just change target maven repositories and don’t need to search for new plugins.

I use gradle maven-publish plugin. In my case, configuration looks like:

nexusPublishing {
    repositories {
        sonatype {
            nexusUrl = uri("https://ossrh-staging-api.central.sonatype.com/service/local/")
            snapshotRepositoryUrl = uri("https://central.sonatype.com/repository/maven-snapshots/")
            username = findProperty('sonatypeUser')
            password = findProperty('sonatypePassword')
        }
    }
}

Only urls are important here. The plugin configures sonatype maven publication, which is only important for snapshot publication (you can configure maven publication manually - only release would require additinoal actions, handled by this plugin).

Locally, sonatypeUser and sonatypePassword properties could be specified in the global gradle properties file (~/.gradle/gradle.properties). On CI, environment variables would be used (ORG_GRADLE_PROJECT_sonatypeUser and ORG_GRADLE_PROJECT_sonatypePassword).

For the examples project, it is required to configure a custom repository to access snapshots:

repositories {
    mavenLocal()
    mavenCentral()
    maven {
        name = 'Central Portal Snapshots'
        url = 'https://central.sonatype.com/repository/maven-snapshots/'
        mavenContent {
            snapshotsOnly()
            includeGroupAndSubgroups('ru.vyarus')
        }
    }
}

For security reasons, repository should be limited to snapshots and one group (in my case sub groups are aslo included because they are used by library modules).

Github actions

Credentials

Generated sonatype tokens must be declared as a github repositry secrets:

Actions

For simplicity, my script split into 3 files:

(ignore dependencies.yml - it updates project dependencies for github dependency graph)

CI script runs build matrix for multiple java versions: check build, run tests (publish coverage data). Also, CI script runs snapshot publication and examples workflows, if required:

name: CI

on:
  push:
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest
    name: Java ${{ matrix.java }}
    strategy:
      fail-fast: false
      matrix:
        java: [11, 17, 21]
    outputs:
      version: ${{ steps.project.outputs.version }}
    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK ${{ matrix.java }}
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: ${{ matrix.java }}

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v3

      - name: Build
        run: |
          chmod +x gradlew
          ./gradlew assemble --no-daemon

      - name: Test
        run: ./gradlew check --no-daemon

      - name: Extract Project version
        id: 'project'
        run: |
          ver=$(./gradlew :properties --property version --no-daemon --console=plain -q | grep "^version:" | awk '{printf $2}')
          echo "Project version: $ver"
          echo "version=$ver" >> $GITHUB_OUTPUT

  publish:
    if: ${{ github.ref == 'refs/heads/dw-3' && github.event_name != 'pull_request' && endsWith(needs.build.outputs.version, '-SNAPSHOT') }}
    needs: build
    uses: ./.github/workflows/publish-snapshot.yml
    # workflow can't see secrets directly
    secrets:
      sonatype_user: ${{ secrets.SONATYPE_USERNAME }}
      sonatype_password: ${{ secrets.SONATYPE_PASSWORD }}

  examples:
    if: ${{ github.ref == 'refs/heads/dw-3' && github.event_name != 'pull_request' && endsWith(needs.build.outputs.version, '-SNAPSHOT') }}
    needs: [build, publish]
    uses: ./.github/workflows/examples-CI.yml

Snapshot publication must not be performed for pull requests, forks and on release (including release tag).

In order to prevent snapshot publication for release we need to know project version:

      - name: Extract Project version
        id: 'project'
        run: |
          ver=$(./gradlew :properties --property version --no-daemon --console=plain -q | grep "^version:" | awk '{printf $2}')
          echo "Project version: $ver"
          echo "version=$ver" >> $GITHUB_OUTPUT

Note: —property version works starting from Gradle 7.5. For older gradle versions, this part could be removed and still the correct version value would be selected.

(for maven, help:evaluate could be used for version extraction: mvn help:evaluate -Dexpression=project.version -q -DforceStdout)

echo "version=$ver" >> $GITHUB_OUTPUT publish extracted version as a build step output. Note that version is published for each matrix step (it’s almost immediate, so not an issue; just in case, if you want to store separate data from matrix steps, see this post).

In order to use stored version in the separate job, we should declare it as a build job’s output:

    outputs:
      version: ${{ steps.project.outputs.version }}

After successful build, snapshot publication run from the separate file:

  publish:
    if: ${{ github.ref == 'refs/heads/dw-3' && github.event_name != 'pull_request' && endsWith(needs.build.outputs.version, '-SNAPSHOT') }}
    needs: build
    uses: ./.github/workflows/publish-snapshot.yml
    # workflow can't see secrets directly
    secrets:
      sonatype_user: ${{ secrets.SONATYPE_USERNAME }}
      sonatype_password: ${{ secrets.SONATYPE_PASSWORD }}

needs: build would hold this job until build job completion

if would allow snapshot publication only for direct branch commit and only for snapshot versions. Note that it reference build job outputs, referenced from needs (needs.build.outputs.version)

It is important to bypass required secrets here because they would not be availble in a separate worklow (executed under workflow_call). It was also possible to just inherit secrets.

Snapshot publication

publish-snapshot.yml

name: Publish snapshot

on:
  workflow_call:
    secrets:
      sonatype_user:
        required: true
      sonatype_password:
        required: true
jobs:
  publish:
    name: Publish snapshot
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 17

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v3

      - name: Build without tests
        run: |
          chmod +x gradlew
          ./gradlew build -x check --no-daemon

      - name: Publish
        env:
          ORG_GRADLE_PROJECT_sonatypeUser: ${{ secrets.sonatype_user }}
          ORG_GRADLE_PROJECT_sonatypePassword: ${{ secrets.sonatype_password }}
        run: ./gradlew publishToSonatype

This workflow is triggered by the main script and can’t access secrets (github actions restriction) and so required secrets must be declared:

on:
  workflow_call:
    secrets:
      sonatype_user:
        required: true
      sonatype_password:
        required: true

As it is a seprate workflow, we have to checkout and build project again (but without tests now):

      - name: Build without tests
        run: |
          chmod +x gradlew
          ./gradlew build -x check --no-daemon

And, finally, we need to call publishToSonatype task to publish snapshot:

      - name: Publish
        env:
          ORG_GRADLE_PROJECT_sonatypeUser: ${{ secrets.sonatype_user }}
          ORG_GRADLE_PROJECT_sonatypePassword: ${{ secrets.sonatype_password }}
        run: ./gradlew publishToSonatype

Note that required credentials passed as environment variables (ORG_GRADLE_PROJECT_sonatypeUser), which gradle would apply as a project properties value.

After successful snapshot publication, examples could be run

Examples run

examples-CI.yml

name: Examples CI

on:
  workflow_call:

jobs:
  build:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: examples
    name: Java ${{ matrix.java }}
    strategy:
      matrix:
        java: [11, 17]

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK ${{ matrix.java }}
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: ${{ matrix.java }}

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v3

      - name: Build and Check
        run: |
          chmod +x gradlew
          ./gradlew build --no-daemon

Again, as we have a separate workflow, project must be cheked out again.

Default directory changed to examples where separate gradle project is stored:

    defaults:
      run:
        working-directory: examples

Correct snapshot version and required maven repository is configured in the examples project.

Dynamic library version

Scripts, descibed above, assume that actual library snapshot version is specified in the examples project. But we already extracted an actual project version, so it is possible to use for the examples project run (to avoid manual version changes after each release).

Declare custom input for examples workflow (examples-CI.yml):

on:
  workflow_call:
    inputs:
      version:
        required: false
        type: string

And assign provided input to the environment variable:

- name: Build and Check
  env:
    ORG_GRADLE_PROJECT_guiceyBom: ${{ inputs.version }}
  run: |
    chmod +x gradlew
    ./gradlew build --no-daemon

The main CI workflow (CI.yml) must specify library version for examples workflow:

examples:
  if: ${{ github.ref == 'refs/heads/dw-3' && github.event_name != 'pull_request' && endsWith(needs.build.outputs.version, '-SNAPSHOT') }}
  needs: [build, publish]
  uses: ./.github/workflows/examples-CI.yml
  with:
    version: ${{ needs.build.outputs.version }}

In my case, required library version was declared explicitly in build.gradle:

ext {
    guiceyBom = '6.3.2'
    dwVersion = '3.0.14'
}

But this would override the environment variable (ORG_GRADLE_PROJECT_guiceyBom) value. To workaround it, assigning default only if value is not already set:

ext {
    guiceyBom = findProperty('guiceyBom') ?: '6.3.2'
    dwVersion = '3.0.14'
}

This way, it will use environment variable on CI and the default value for local runs.

Summary

Action execution would look like this:

Publication waits build copletion (in case of build error - no need to publish snapshot). And examples wait for snapshot publication (and so will not run if publication fails).

Full scripts (with dynamic library version for examples run) could be found here

More details could be found in this blog post, which helped me a lot.

Yes, I know, there is a super simple jitpack for this, but it can’t be used in some cases because instead of using your build output it searches for packages with some euristic. Moreover, jitpack generates its own BOM, overwriting your own. So for multi-module (or projects with more complex build) projects jitpack is not an option.

The biggest advantage of github packages is its simple integration with github actions (super simple publication). This covers one important CI use case: test commit - publish new snapshot - use snapshot to run tests.

Using already published package

Create access token

On any github page, in the upper top corner, click on your profile icon and select Settings

On the left bar click Developer setting

Click Tokens (classic) under Personal access tokens section

Choose Generate new token (classic) in the Generate new token dropdown

Most likely, github would ask you to confirm authentication here.

Set token description. Set token to never expire because this token will only grant a read right on github packages (moreover, you’ll be able to use the same token to access any github packages repository)

Select ONLY read:packages permission.

Of course, token with any other rights added will also work, but if you do so consider setting token expiration (as such token stealing might be sensitive).

IMPORTANT Github will show you token just once

Gradle project configuration

Add github packages repository either in build.gradle :

repositories {
    mavenCentral()
    maven {
        url  = 'https://maven.pkg.github.com/user/project'
        credentials {
            username = findProperty('gpr.user') ?: System.getenv("USERNAME")
            password = findProperty('gpr.key') ?: System.getenv("TOKEN")
        }
    }
}

OR in settings.gradle

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        maven {
            url  = 'https://maven.pkg.github.com/user/project'
            credentials {
                username = settings.ext.find('gpr.user') ?: System.getenv("USERNAME")
                password = settings.ext.find('gpr.key') ?: System.getenv("TOKEN")
            }
        }
    }
}

Note: System.getenv part will be used if you’re goinf to run this project on github actions to consume credentials directly from environment variables. If you don’t plan to run project on CI, you can remove this section (see complete description at the bottom).

Put you access token in the global gradle configuration: ~/.gradle/gradle.properties

gpr.user=<your github user name>
gpr.key=<your github classic token>

Maven project configuration

Add credentials into ~/.m2/settings.xml

<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settings-1.0.0.xsd">            

    <servers>
        <server>
            <id>github</id>
            <username>USERNAME</username>
            <password>TOKEN</password>
        </server>
    </servers>
</settings>

Add github packages repository (directly in project or in profile inside settings.xml)

<repositories>    
  <repository>
        <id>github</id>
        <url>https://maven.pkg.github.com/user/project</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>

IMPORTANT: repository id must be the same as server id in settings.xml (to apply configured authentication)

Publishing package in github action

Will show publishing only for gradle project. No special repository configuration is required - just publish new package.

In build.gradle add github packages repository:

 // https://docs.github.com/en/actions/use-cases-and-examples/publishing-packages/publishing-java-packages-with-gradle#publishing-packages-to-github-packages
publishing {
    repositories {
        maven {
            name = "GitHub"
            url = "https://maven.pkg.github.com/user/project"
            credentials {
                username = System.getenv("GITHUB_ACTOR")
                password = System.getenv("GITHUB_TOKEN")
            }
    }
}

GITHUB_ACTOR and GITHUB_TOKEN are provided automatically (no configuration required)

In “https://maven.pkg.github.com/user/project” user - github user name, project - github project name (same as in github project url)

CI script:

name: Publish snapshot

on:
  push:

jobs:
  publish:
    name: Publish snapshot
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

    steps:
      - uses: actions/checkout@v4

      - name: Set up JDK
        uses: actions/setup-java@v4
        with:
          distribution: 'zulu'
          java-version: 17

      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v3

      - name: Build without tests
        run: |
          chmod +x gradlew
          ./gradlew build -x test -x check --no-daemon

      - name: Publish
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          SNAPSHOT: true
        run: ./gradlew publishAllPublicationsToGitHubRepository --no-daemon

Here on each commit project would be built without tests and new snapshot package published.

Real project with packages publication

In my project, I use a series of connected workflows:

1. CI - run and test project

2. If test success, publish new package

3. Run examples project build with just published package

Use github package repo on gtihub actions

On github actions you don’t need an additional token to access githubg packages because GITHUB_TOKEN is already provided.

Gradle project

Just add repository, as it was shown in the first chapter.

repositories {
    maven {
        url  = 'https://maven.pkg.github.com/user/project'
        credentials {
            username = findProperty('gpr.user') ?: System.getenv("USERNAME")
            password = findProperty('gpr.key') ?: System.getenv("TOKEN")
        }
    }
}

This time, token would not be configured in global gradle properties, but, instead, would be provided in the environment variables.

Mapping these variables in the CI scipt:

jobs:
  build:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: examples
    name: Examples run
    env:
      USERNAME: ${{ github.actor }}
      TOKEN: ${{ secrets.GITHUB_TOKEN }}

Note that

    defaults:
      run:
        working-directory: examples

Required only in my case, because examples project is in github repository subfolder (examples).

Maven project

For maven project, credentials must be inside settings file. Custom settings file could reference environemnt variables maven-settings.xml:

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0 http://maven.apache.org/xsd/settings-1.0.0.xsd">
    <activeProfiles>
        <activeProfile>github</activeProfile>
    </activeProfiles>
    <profiles>
        <profile>
            <id>github</id>
            <repositories>
                <repository>
                    <id>central</id>
                    <url>https://repo1.maven.org/maven2</url>
                </repository>
                <repository>
                    <id>github</id>
                    <url>https://maven.pkg.github.com/user/project</url>
                    <snapshots>
                        <enabled>true</enabled>
                    </snapshots>
                </repository>
            </repositories>
        </profile>
    </profiles>

    <servers>
        <server>
            <id>github</id>
            <username>${env.USERNAME}</username>
            <password>${env.TOKEN}</password>
        </server>
    </servers>

</settings>

In my case, I run maven projects from gradle, using maven-exec-plugin and so could simply specify custom settings file:

tasks.register('maven-test', MavenExec) {
    goals 'test'
    options {
        settings = rootProject.file('maven-settings.xml')
    }
}

But for pure maven project, you could simply override existing settings.xml with a custom file with an additional CI job step.

Gradle plugin snapshots and github package

If you develop gradle plugin, you know that it requires two publications:

1. Plugin itself

2. Redirection pom for gradle plugins syntax

Publication method above will correctly publish both into github packages repository.

In order to use such snapshot, repositorty must be specified in settings.gradle’s pluginManagement section:

pluginManagement {
    repositories {
        mavenLocal()
        gradlePluginPortal()
        maven {
            url  = 'https://maven.pkg.github.com/user/project'
            credentials {
                username = settings.ext.find('gpr.user') ?: System.getenv("USERNAME")
                password = settings.ext.find('gpr.key') ?: System.getenv("TOKEN")
            }
        }
    }
}

For kotlin syntax (settings.gradle.kts):

pluginManagement {
    repositories {
        mavenCentral()
        gradlePluginPortal()
        maven {
            url  = uri("https://maven.pkg.github.com/user/project")
            credentials {
                username = extra.has("gpr.user").let { if (it) extra["gpr.user"] as String else System.getenv("USERNAME")}
                password = extra.has("gpr.key").let { if (it) extra["gpr.key"] as String else System.getenv("TOKEN")}
            }
        }
    }
}

Example project with “test - publish - run tests” cyle for gradle plugin

My animalsniffer gradle plugin targets java 8 (keeps minimum compatiblity):

java {
    sourceCompatibility = 1.8
}

Now, in order to add android support, I want to add an optional dependency for android plugin:

dependencies {
    compileOnly 'com.android.tools.build:gradle:8.4.0'
}

But, this will not work:

> Could not resolve all files for configuration ':compileClasspath'.
   > Could not resolve com.android.tools.build:gradle:8.4.0.
     Required by:
         project :
      > No matching variant of com.android.tools.build:gradle:8.4.0 was found. The consumer was configured to find a library for use during compile-time, compatible with Java 8, preferably not packaged as a jar, preferably optimized for standard JVMs, and its dependencies declared externally, as well as attribute 'org.gradle.plugin.api-version' with value '8.6' but:
          - Variant 'apiElements' capability com.android.tools.build:gradle:8.4.0 declares a library for use during compile-time, packaged as a jar, preferably optimized for standard JVMs, and its dependencies declared externally:
              - Incompatible because this component declares a component, compatible with Java 11 and the consumer needed a component, compatible with Java 8
              - Other compatible attribute:
                  - Doesn't say anything about org.gradle.plugin.api-version (required '8.6')
          - Variant 'javadocElements' capability com.android.tools.build:gradle:8.4.0 declares a component for use during runtime, and its dependencies declared externally:
              - Incompatible because this component declares documentation and the consumer needed a library
              - Other compatible attributes:
                  - Doesn't say anything about its target Java environment (preferred optimized for standard JVMs)
                  - Doesn't say anything about its target Java version (required compatibility with Java 8)
                  - Doesn't say anything about its elements (required them preferably not packaged as a jar)
                  - Doesn't say anything about org.gradle.plugin.api-version (required '8.6')
          - Variant 'runtimeElements' capability com.android.tools.build:gradle:8.4.0 declares a library for use during runtime, packaged as a jar, preferably optimized for standard JVMs, and its dependencies declared externally:
              - Incompatible because this component declares a component, compatible with Java 11 and the consumer needed a component, compatible with Java 8
              - Other compatible attribute:
                  - Doesn't say anything about org.gradle.plugin.api-version (required '8.6')
          - Variant 'sourcesElements' capability com.android.tools.build:gradle:8.4.0 declares a component for use during runtime, and its dependencies declared externally:
              - Incompatible because this component declares documentation and the consumer needed a library
              - Other compatible attributes:
                  - Doesn't say anything about its target Java environment (preferred optimized for standard JVMs)
                  - Doesn't say anything about its target Java version (required compatibility with Java 8)
                  - Doesn't say anything about its elements (required them preferably not packaged as a jar)
                  - Doesn't say anything about org.gradle.plugin.api-version (required '8.6')

The main problem:

Incompatible because this component declares a component, compatible with Java 11 and the consumer needed a component, compatible with Java 8

No matter what JDK I actually use for this build (17), gradle complains that dependency is not compatible with declared targetCompatibility\=1.8 (not a mistake, by default targetCompatibility == sourceCompatibility)

But, I assume this dependency to be an optional: android project would use java 11 (17) in any case, but my plugin should also work for pure java projects under java 8.

To workaround this moment, I have to manually declare (override) target jvm attribute for configuration (in build.gradle):

import org.gradle.api.attributes.java.TargetJvmVersion

configurations.compileClasspath.attributes
    .attribute(TargetJvmVersion.TARGET_JVM_VERSION_ATTRIBUTE, 11)

And now java 8 target does not cause problem anymore.

Helpful links:

1. Gradle attributes doc

2. Attributes definition example

What is binary release

First, what I mean by binary release: native binaries generated (with graalvm native image) from java application and attached on github release page:

1. attached jar on screenshot is all-in-one jar (with included dependencies), which is not published to maven central

2. I will explain why linux binary size differ later

It is not possible to build such binary release on local machine because each binary must be build on target os (linux, windows, mac). That’s why github actions required.

Overall release process consists of two parts:

1. Release project into maven central and release tag creation (gradle release plugin scope)

2. Github release creation (in my case manual, but it could be automated too) which trigger binraty action execution. Action attaches created binaries to the just created github release.

Native binary requirements

What java application could be converted to native binary?
In fact, alomost any java application (even “hello world”) with the main method (entry point required).

In my case, it was a CLI utility, generated with picocly (ideal candidate for native binary).

Project requirements

My project use gradle, but it is not important and you can easilly reuse this workflow for maven project (with minimal changes). The most important part is github action logic itself.

There are maven and gradle plugins maintained by graalvm.

Set up gradle plugin (groovy):

plugins {
    id 'org.graalvm.buildtools.native' version '0.10.3'
}

graalvmNative { 
    binaries { 
        main { 
            imageName = project.name 
            mainClass = 'ru.vyarus.yaml.updater.cli.UpdateConfigCli' 
        } 
        all { 
            resources.autodetect() 
        } 
    } 
}

Plugin needs to know only target main class.

Note that it is possible to avoid plugin usage, but then you’ll have to write native image command manually. Plugin makes life a bit simplier.

IMPORTANT: Plugin requires java 11! In my case, I keep java 8 compatibility and so have to use old plugins syntax and actiavate it ONLY when native compilation is required.

Local test

First of all, you may need to install some additional packages: see prerequisites.

Then custom JDK is required: see installation. On linux I use sdkman:

sdk install java 21.0.2-graalce

You don’t need to set it as default. Just activate it before running your project build:

sdk use java 21.0.2-graalce 
./gradlew :nativeCompile

If build successful, your native binary could be found in folder:

build/native/nativeCompile

Github action

My action additionally publish docker image into github repository, but I will not describe this step here - it is very easy to add (just copy this part from my action, if required).

Workflow:

1. Step selects target tag (will describe later)

2. 3 steps build 3 binaries on 3 OS and upload them as action artifacts

3. Final step attach binaries to github release

OS-specific steps did not publish directly on github page for proper debug and consistency:

1. In case of debug run, final publish step simply not called (but all artifacts attached to action and so could be exemined)

2. Last step will not run if any OS-specific step will fail (all or nothing)

Code

name: Publish native binaries

on:
  # for manual debug run (and optional re-release)
  workflow_dispatch:
    inputs:
      # when set, binaries would be uploaded to provided release tag (re-release)
      tag:
        description: 'Target tag (leave empty for test build)'
        required: false
        default: ''
        type: string
  release:
    types: [published]

jobs:
  selectTag:
    name: Select target tag
    runs-on: ubuntu-latest
    outputs:
      TAG_NAME: ${{ steps.select.outputs.TAG_NAME }}
    steps:
      - id: select
        name: Select tag name
        run: |
          if [ -n "${{ inputs.tag }}" ]; then
            tagName=${{ inputs.tag }}
          else
            tagName=${{ github.event.release.tag_name }}
          fi
          echo "Selected tag: $tagName"
          echo "TAG_NAME=$tagName" >> $GITHUB_OUTPUT          


  build:
    name: Build ${{ matrix.artifact }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - artifact: yaml-updater.exe
            os: windows-2022
            ext: .exe
            # due to windows defender false detections
            upx: false

          - artifact: yaml-updater-mac-amd64
            os: macos-latest
            # https://github.com/upx/upx/issues/612
            upx: false

          - artifact: yaml-updater-linux-amd64
            os: ubuntu-latest
            upx: true
            shadowJar: true

    runs-on: ${{ matrix.os }}
    continue-on-error: ${{ false }}
    needs: [selectTag]
    steps:
      - run: |
          echo "Selected tag: ${{ needs.selectTag.outputs.TAG_NAME }}"
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.selectTag.outputs.TAG_NAME }}

      - uses: graalvm/setup-graalvm@v1
        with:
          java-version: '22'
          distribution: 'liberica'
          github-token: ${{ secrets.GITHUB_TOKEN }}
          cache: gradle
      - name: Verify GraalVM
        run: |
          echo "GRAALVM_HOME: $GRAALVM_HOME"
          echo "JAVA_HOME: $JAVA_HOME"
          java --version
          native-image --version

        # cache
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v3

      - name: Build
        id: build
        shell: bash
        run: |
          if [ -n "${{ matrix.shadowJar }}" ]; then
            BUILD_TARGET=":yaml-config-updater-cli:shadowJar :yaml-config-updater-cli:nativeCompile"
          else
            BUILD_TARGET=":yaml-config-updater-cli:nativeCompile"
          fi
          chmod +x gradlew
          ./gradlew ${BUILD_TARGET} --no-daemon
          ## Rename files
          mkdir upload
          cp yaml-config-updater-cli/build/native/nativeCompile/yaml-config-updater-cli${{ matrix.ext }} upload/${{ matrix.artifact }}
          echo "binary=upload/${{ matrix.artifact }}" >> $GITHUB_OUTPUT
          if [ -n "${{ matrix.shadowJar }}" ]; then
            cp yaml-config-updater-cli/build/libs/*-all.jar upload/yaml-updater.jar
            echo "jarFile=upload/yaml-updater.jar" >> $GITHUB_OUTPUT
          fi

      - name: Run UPX
        uses: svenstaro/upx-action@v2
        if: ${{ matrix.upx }}
        continue-on-error: true
        with:
          file: ${{ steps.build.outputs.binary }}
          args: "-9"

      - name: Publish ${{ matrix.artifact }}
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.artifact }}
          path: ${{ steps.build.outputs.binary }}

      - name: Publish JAR
        uses: actions/upload-artifact@v4
        if: matrix.shadowJar
        with:
          name: yaml-updater.jar
          path: ${{ steps.build.outputs.jarFile }}

      - name: Quick Test
        run: ./${{ steps.build.outputs.binary }} --version


  publish:
    runs-on: ubuntu-latest
    if: ${{ needs.selectTag.outputs.TAG_NAME }}
    strategy:
      fail-fast: false
      matrix:
        artifact:
          - yaml-updater.exe
          - yaml-updater-mac-amd64
          - yaml-updater-linux-amd64
          - yaml-updater.jar
    needs: [build, selectTag]
    steps:
      - run: mkdir -p tmp
      - name: Download artifact ${{ matrix.artifact }}
        uses: actions/download-artifact@v4
        with:
          name: ${{ matrix.artifact }}
          path: tmp

      - name: Upload ${{ matrix.artifact }}
        if: ${{ needs.selectTag.outputs.TAG_NAME }}
        uses: svenstaro/upload-release-action@v2
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: tmp/${{ matrix.artifact }}
          tag: ${{ needs.selectTag.outputs.TAG_NAME }}
          overwrite: true

Run modes

As I mention before, action will run as soon as new github release would be published (manually or automatically).

on:
  .....
  release:
    types: [published]

There are also 2 manual executions:

on:
  # for manual debug run (and optional re-release)
  workflow_dispatch:
    inputs:
      # when set, binaries would be uploaded to provided release tag (re-release)
      tag:
        description: 'Target tag (leave empty for test build)'
        required: false
        default: ''
        type: string

If “target tag” input would be empty - debug execution would be started. It will only run 3 native builds without final step. Build artifacts would be available on action build summary page:

(showing build with error on purpose - it was one of many debug runs).

Pay attention that attached files are zipped here: so it is not the real size! On release page files would be attached as-is.

The third run option is manual re-release. By default, github action would use the same commit as current action itself, so you can’t fix action yaml and re-perform release on tag.

The third mode exactly workarounds this default behaviour: you can run actual github action, but build and release sources from exact tag (and binaries would be attached to an appropriate release page).

Tag selection job

In order to make all this work, additional (first) step is required:

  selectTag:
    name: Select target tag
    runs-on: ubuntu-latest
    outputs:
      TAG_NAME: ${{ steps.select.outputs.TAG_NAME }}
    steps:
      - id: select
        name: Select tag name
        run: |
          if [ -n "${{ inputs.tag }}" ]; then
            tagName=${{ inputs.tag }}
          else
            tagName=${{ github.event.release.tag_name }}
          fi
          echo "Selected tag: $tagName"
          echo "TAG_NAME=$tagName" >> $GITHUB_OUTPUT

It will look if tag name provided as input or it was a release event and will take release tag from event. In case of manual debug run (without tag name), tag name will remain empty.

Result is written into declared job output:

outputs:
      TAG_NAME: ${{ steps.select.outputs.TAG_NAME }}
    ....
    echo "TAG_NAME=$tagName" >> $GITHUB_OUTPUT

Other jobs declare dependency on first job and so could reference its output values:

needs: [selectTag]
....
if: ${{ needs.selectTag.outputs.TAG_NAME }}

In the above example, “if” would prevent job execution when TAG_NAME not set (in debug mode).

Binary build jobs

The main build use matrix to run on three different OS:

  build:
    name: Build ${{ matrix.artifact }}
    strategy:
      fail-fast: false
      matrix:
        include:
          - artifact: yaml-updater.exe
            os: windows-2022
            ext: .exe
            # due to windows defender false detections
            upx: false

          - artifact: yaml-updater-mac-amd64
            os: macos-latest
            # https://github.com/upx/upx/issues/612
            upx: false

          - artifact: yaml-updater-linux-amd64
            os: ubuntu-latest
            upx: true
            shadowJar: true

Checkout

First step would checkout correct version:

 steps:
      - run: |
          echo "Selected tag: ${{ needs.selectTag.outputs.TAG_NAME }}"
      - uses: actions/checkout@v4
        with:
          ref: ${{ needs.selectTag.outputs.TAG_NAME }}

Note that in case of debug build (manual run without tag name), TAG_NAME would be empty and so action would checkout current branch head (the same as if ref option would not be declared at all). But in case of manual run with tag, it would checkout tag sources (which is important for re-releasing binaries).

Setup graal and gradle

      - uses: graalvm/setup-graalvm@v1
        with:
          java-version: '22'
          distribution: 'liberica'
          github-token: ${{ secrets.GITHUB_TOKEN }}
          cache: gradle
      - name: Verify GraalVM
        run: |
          echo "GRAALVM_HOME: $GRAALVM_HOME"
          echo "JAVA_HOME: $JAVA_HOME"
          java --version
          native-image --version

        # cache
      - name: Setup Gradle
        uses: gradle/actions/setup-gradle@v3

Graalvm setup action is also provided by graalvm team and that’s wonderful! Before, you have to manually install additional pre-requisites on windows and now its just a one simple step!

See action docs for options description.

Build itself

      - name: Build
        id: build
        shell: bash
        run: |
          if [ -n "${{ matrix.shadowJar }}" ]; then
            BUILD_TARGET=":yaml-config-updater-cli:shadowJar :yaml-config-updater-cli:nativeCompile"
          else
            BUILD_TARGET=":yaml-config-updater-cli:nativeCompile"
          fi
          chmod +x gradlew
          ./gradlew ${BUILD_TARGET} --no-daemon
          ## Rename files
          mkdir upload
          cp yaml-config-updater-cli/build/native/nativeCompile/yaml-config-updater-cli${{ matrix.ext }} upload/${{ matrix.artifact }}
          echo "binary=upload/${{ matrix.artifact }}" >> $GITHUB_OUTPUT
          if [ -n "${{ matrix.shadowJar }}" ]; then
            cp yaml-config-updater-cli/build/libs/*-all.jar upload/yaml-updater.jar
            echo "jarFile=upload/yaml-updater.jar" >> $GITHUB_OUTPUT
          fi

This is the only step that depends on build tool.

As my application requires 3rd party jars, I want to also build an all-in-one jar (which is simpier to use, in case if binary can’t be used). There is an shadowJar matrix option to build complete jar only once on linux (and so on linux :shadowJar task must be called to build it).

Next, copying generated files into upload folder in order to properly re-name generated files (and simplify paths).

Note that undeclared outputs declared here:

        echo "binary=upload/${{ matrix.artifact }}" >> $GITHUB_OUTPUT
         echo "jarFile=upload/yaml-updater.jar" >> $GITHUB_OUTPUT

To reference them in further steps as: ${{ steps.build.outputs.binary }}

UPX

As you may note, resulted binaries are quite big (~20mb in my case). It is possible to shrink it with graalvm but with a lot of efforts (mainly by getting rid of reflection), but it is not possible in my case.

Instead, upx tool could shrink binary size (in my case from 20mb into 6mb).

      - name: Run UPX
        uses: svenstaro/upx-action@v2
        if: ${{ matrix.upx }}
        continue-on-error: true
        with:
          file: ${{ steps.build.outputs.binary }}
          args: "-9"

But, currently upx is not compatible with mac (homebrew would even not allow you to install it).

On windows, compressed binaries are quite often being detected as infected by windows defender. It is strange, because in theory any antivirus could unupx (upx -d binary) it and check correctly. I didn’t find a way to workaround this.

So upx would be applied only for linux (and that’s why linux binary on screen at page head is the smallest one).

if: ${{ matrix.upx }}

Store generated binary as action artifact

      - name: Publish ${{ matrix.artifact }}
        uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.artifact }}
          path: ${{ steps.build.outputs.binary }}

      - name: Publish JAR
        uses: actions/upload-artifact@v4
        if: matrix.shadowJar
        with:
          name: yaml-updater.jar
          path: ${{ steps.build.outputs.jarFile }}

      - name: Quick Test
        run: ./${{ steps.build.outputs.binary }} --version

This is important for debug run, because we could download generated binary and test/investigate it locally. Also, uploading all-in-one jar (generated only on linux).

Quick test is required just to reveal potentially incorrect binary. For example, on mac, it detected upx-compressed binary incompatibility. It is important to test after upload to be able to download and check binary after error.

Publish job

publish:
    runs-on: ubuntu-latest
    if: ${{ needs.selectTag.outputs.TAG_NAME }}
    strategy:
      fail-fast: false
      matrix:
        artifact:
          - yaml-updater.exe
          - yaml-updater-mac-amd64
          - yaml-updater-linux-amd64
          - yaml-updater.jar
    needs: [build, selectTag]
    steps:
      - run: mkdir -p tmp
      - name: Download artifact ${{ matrix.artifact }}
        uses: actions/download-artifact@v4
        with:
          name: ${{ matrix.artifact }}
          path: tmp

      - name: Upload ${{ matrix.artifact }}
        if: ${{ needs.selectTag.outputs.TAG_NAME }}
        uses: svenstaro/upload-release-action@v2
        with:
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          file: tmp/${{ matrix.artifact }}
          tag: ${{ needs.selectTag.outputs.TAG_NAME }}
          overwrite: true

Publish job starts only if target tag declared (release event or manual re-release):

    if: ${{ needs.selectTag.outputs.TAG_NAME }}

And if previous steps were successfull:

    needs: [build, selectTag]

Then downloading artifacts from action artifacts storage (uploaded by build jobs) and attaching them to github release.

But, it appears, that using these shortcuts is officially a bad practice.

Quote from gradle forum thread:

1. Consider switching from Groovy DSL to Kotlin DSL. This is by now the recommended default DSL, it immediately gives you type-safe build scripts, it gives you actually helpful error messages if you mess up the syntax, and you get amazingly better IDE support when using a proper IDE like IntelliJ IDEA.

2. Do not use allprojects { ... }, subprojects { ... }, project(...) { ... } or similar. Those are bad practice and immediately introduce project coupling by doing cross-project configuration. This disturbs more sophisticated Gradle features and even prevents some upcoming features to work properly. Instead you should use convention plugins, for example in buildSrc or and included build, for example implemented as precompiled script plugins. Those you can then targetedly apply to the projects where their effect should be present, so that you for example only apply Java conventions to projects that are actually Java projects.

Disclaimer: I put this on top to point to official incorectness of such way of configuration. Still, I consider it as the most understandable and easy to use.

Below you'll find one of hard to debug problems appeared after configuring common staff in the root project with groovy DSL (which, eventually, lead me to the above insight).

The problem

My problem appeared with pom configuration (using my pom plugin) inside multi-module project: as all modules share the same core pom information (developer, license, scm etc.), it would be logical to apply it in allprojects section:

plugins {
    id 'java-platform'
    id 'ru.vyarus.pom'
}

allprojects {
    maven.pom {
          developers {
              developer {
                  id = 'johnd'
                  name = 'John Doe'
                  email = 'johnd@somemail.com'
              }
         }
    }
}

subprojects {
    apply plugin: 'java'
    apply plugin: 'ru.vyarus.pom'
}

Root project is a BOM, but I omit related configurations to clearly show the problem.

This should put developer section in all poms, including root BOM (allprojects). But java plugin must be applied only for sub-modules because root project does not have sources. Looks logical.

But actual behaviour would be: BOM (root pom) would contain many duplicated developer tags and sub-modules would not contain any!

What happend: When allprojects is applied for sub-module, ru.vyarus.pom plugin is not applied yet and gradle goes to the root project, trying to find referenced extension (maven), and successfully finds it (so root pom being configured multiple times with the same chunk).

If we try to move subprojects section above the allprojects - it would work as planned. But it might be much harder to spot in the real build file.

Note that simply moving pom plugin activation (apply plugin: 'ru.vyarus.pom') into allprojects section would not work, becuase plugin is activated only after java (or java-platform) plugin activation.

Debugging

Mentioned gradle forum topic provides a nice way to debug such things:

println("ROOT: ${System.identityHashCode(maven)}")

allprojects {
    println("$name: ${System.identityHashCode(maven)}")
    maven.pom {
        ...
    }
}

Here we print identity of the maven extension object, which would be equal if root project extension is used in sub-modules.

I didn't use it in my case (becuase pom plugin supports debug mode, showing all xml modifications), but need to mention it as a very nice alternative.

Solution

Suppose we can't move subprojects, then the simplest solution would be in delaying this configuration (afterEvaluate usage was highly not recommended in thread):

allprojects {
    afterEvaluate {
        maven.pom {
            ...
        }
    }
}

But, it might not be enoght if extension values are used in afterEvaluate in plugin, which is a common practice (and so your afterEvaluate block would execute after extension values were used, and would be ignored).

The best way would be to wait for required (or related) plugin activation:

allprojects {
    plugins.withId('java') {
        maven.pom {
            ...
        }
    }
}

(or pluginManager.withPlugin("java-base") as suggested in thread, but this version is shorter).

Side note: when groovy closure was used in pom plugin for xml configuration, it was possible to resolve closure declaration project and detect such mis-use automatically. But, unfortunately, it is impossible with pure Action or direct model object access.

Mitmproxy is ideal for such things. It's a small and handy reverse proxy, but with ability to modify requests and responses and supporting https.

Usage

mitmproxy --mode reverse:https://some.url

This would start proxy UI on port 8080. So https://localhost:8080/ calls would be redirected into https://some.url (and so in application configuration proxy url must be used instead of direct url)

To use custom port:

mitmproxy --mode reverse:https://some.url -p 4000

Now https://localhost:4000/ would lead to https://some.url

UI

Root screen shows all intercepted requests:

You'll need to use keyboard:

• Arrows (up/down) - select request

• Enter - open request info

• q - back (from request info or any other screen; remember!)

• Shift+O - options (useful to modify options on started instance instead of changing parameters)

All other keys could be seen in the bottom bar.

GET request details example (after enter hit on any request line) :

Response modification

In my (keycloak) case it was important to rewrite original url in configuration response into proxy url.

You can do it with modify_body option:

mitmproxy --mode reverse:https://some.url -p 4000 --modify-body "#https://keycloak-url#https://localhost:4000"

Important moment: first symbol of --modify-body value declares parts separator! In this example # used as separation symbol. https://keycloak-url would be replaced with https://localhost:4000 in all responses (first part is a regexp, but in simple cases, just strings would work).

Note that you can always modify this value through options (shift+O): just find modify_body option and hit enter 2 times to get into edit mode. After edition esc to exit editor and 2 times q to get back to the main screen

Proxying kecloak

It would not be helpful for anyone, but just to remember for me. Proxied keycloak would not produce valid tokens, becuase they would be issued with a "wrong" host. In order to overcome this, keycloak must be configured with proxy url as frontend:

WARNIG: After that your main keycloak url would stop working (for the same reason)! So don't forget to clear this value after using proxy (to clear value use proxy url to access keycloak).

And, if you, by mistake, put an http url and your keycloak is under https, then to access keycloak you'll have to allow mixed content in chrome:

1. Click the lock (caution) icon, then click Site settings.

2. Scroll to Insecure content, then use the drop-down list to change “Block (default)” to “Allow.”

3. Reload the VEC page.

Did not help

I tried the most common advises:

• Remove caches by removing ~/.cache/JetBrains/IntelliJIdea2022.3/ folder

• Disable embedded chrome (for markdown rendering): ide.browser.jcef.enabled=false in idea.properties (Help/Edit custom properties)
  After all I enabled it back.

But it didn't help. Moreover, other apps like chrome and docker start failing too.

Solution

It appears that the problem was in swap file size (even having 64gb of memory, swap is still used). By default, swap file is 2g in ununtu.

To enlarge it into 4gb:

swapoff -a
fallocate -l 4G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile

Another advice was to encrease swappiness to avoid going anything into swap:

echo vm.swappiness=100 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

And, the last thing is the new systemd-oomd ubuntu service watching applications for memory and swap consuption and killing them to prevent kernel out of memory.

You can see its log with: journalctl -u systemd-oomd

As I understand, it works sometimes not as well as it was planned, and so, having enough memory, it makes sense to switch it off to avoid redundant checks:

systemctl is-enabled systemd-oomd
systemctl mask systemd-oomd

(masking to prevent other services to start it)

I suspect the last step wasn't required, but still did it. Overall, I observe much better system performance. IDEA craches are all gone!

Several years ago I was searching for a simple (but pretty) documentation tool for my open source projects. Eventually, I stopped on mkdocs with material theme:

But, it is a python tool and I need to use it in gradle. I liked the tool so much that decided to build a gradle plugin for it. I thought, It would be logical to implement basic python support in a separate plugin, just in case if I would decide to do a plugin for some other python module later. That's how plugins were born:

• Use-python plugin
• Mkdocs plugin

(going a bit forward, splitting plugin was a right move - python plugin appears to be even more popular then specialized mkdocs plugin)

The basic idea was to use python the same way as we use java: install it once manually and allow plugin to automate dependencies management. There is a virtualenv module in python, allowing creation of isolated environments where we can install project-specific modules without affecting global python installation (very like global/local npm modules).

Eventually, there appears to be many-many python-related problems with os-specific execution, differences between python versions (and even the way it was installed), but this article is not about it (maybe next time).

Once, I was asked if it is possible to avoid local python installation and use docker container instead. First, I thought "no, no-no-no, no way" and wasn't going to do anything, but, as usual, then I got curious "why not?" (besides, python provides official python images).

Why testcontainers

Initially, I thought to use docker-java, but it is a low-level api almost without documentation. To speed up prototyping phase (I wasn't ready for complete plugin rewrite and so must be sure that it is possible to introduce docker in relatively simple way), I used testcontainers instead (which, actually, build above docker-java).

If you have never heard about it: testcontainers is a testing library (with junit, spock etc. integrations) providing easy container management in tests (starting fresh database, redis or anything else). I've been using it for several years already and it's a real life saver for integration tests. And that's why I thought about it (and, by the way, I know about mkdocs exactly because testcontainers use mkdocs for documentation).

Testcontainers provide really simple api for starting a container:

new GenericContainer(DockerImageName.parse("python:3.10.8-alpine3.15"))
    .withCommand("python", "--verson")
    .withStartupTimeout(Duration.ofSeconds(1))
    .start()

This code will download python image (~40mb) start python --version and exit.

It quickly appears that my need is pretty much the same as in integration test: start docker, do something and make sure it will be stopped after. Docker-java is too generic (I would have to implement many things proveded in testcontainers out of the box).

One important aspect is that testcontainers use additional specialized container (ryuk) which would guarantee proper shutdown for started containers. This might not be obvious, but stale containers are a pain, especially if they use port bindings and so would prevent consequent runs and require users to do manual investigations and cleanups. In the case of gradle, crashes are possible. Moreover, tasks may run infinite python processes (like mkdocs dev server) which might only be stopped forcefully and without proper container cleanup this would be a problem.

This also implies stateless containers usage: you can't expect container state to be preserved between restarts. Not a big problem in my case, as I can simply store environment inside mapped directory (the same for commands output). From the other side, stateful containers would also become a problem: possible damaged state, requiring additional user actions to flush that state.

A little downside of using testcontainers is that you'll have to keep junit dependency in classpath - testcontainers is a test tool at first hand, and wasn't supposed to be used outside of tests.

Container OS

After looking at official python image page and seeing windows-based images (like 3.10.8-windowsservercore-1809) I was hoping to be able to run windows containers on linux (naive me). Of course, it's not possible.

In general, you can run linux containers on linux (and macos) and windows containers on windows. But, actually, docker client on windows is installed with WSL2 support by default and so all linux containers work on windows (of course, linux containers were working before WSL, but with WSL it works on all windows versions).

In order to use windows containers, you'll need windows PRO (Home does not support this!) and in the tray docker icon switch to "Use windows containers". Since that moment only windows containers would work.

On linux, windows containers would not work (in theory, it could work with windows virtualization (like windows do to run linux containers), but it will quickly face windows license problem, so not sure it would ever happen).

As you can see, you can target only linux containers and it would work everywhere! Windows containers are too exotic.

And, going back to testcontainers, they are limited to linux containers only because ryuk (special container used for proper shutdown) does not provide windows version and so testcontainers would not be able to run with windows containers (but it might someday).

Looking through the prism of the gradle plugin, a single OS is a plus, because you don't have to support different commands (everything is obviously different for windows and linux). I added theoretical windows support in my plugin for the future, but not sure this would ever be useful (I know about windows specifics too late).

CI

Need to mention one testcontainers limitation: they are not working currently on windows CI servers like Appveyour. The problem is that such servers are based on Windows Servers which is not supported by testcontainers.

The only known compatible windows CI is azure pipelines. But its free plan is very limited.

On linux CI there are no problems. For example, github actions do not even require any additional configurations.

File sharing

Another important aspect is file sharing. In case of gradle plugin, I simply mount entire project folder into container (and automatically rewrite python command to match correct paths):

new GenericContainer(DockerImageName.parse("python:3.10.8-alpine3.15"))
  .withFileSystemBind("/local/path/project-name", "/usr/src/project-name", BindMode.READ_WRITE)
  ...

But there is a problem: container works with a root user and so creates all files as root. On windows and macos, docker volumes are implemented using network mount and so files created inside container (inside volume) with root user are correctly remapped into current user.

On linux - files created inside container would preserve root and so you'll need to use sudo to do anything with them. As an example, if your command, executed inside a container, would write anything inside the project build directory then gradlew clean would fail to execute (due to not enough rights).

To workaround this problem, I execute chown inside the container just after python execution to correct rights for all created files. Note that target user does not need to exist inside the container when performing chown with uid.

To avoid current user uid resolution, I used uid (and gid) from project root folder (which certainly must be good enough):

Path projectDir = project.rootProject.rootDir.toPath()
int uid = (int) Files.getAttribute(projectDir, "unix:uid", LinkOption.NOFOLLOW_LINKS)
int gid = (int) Files.getAttribute(projectDir, "unix:gid", LinkOption.NOFOLLOW_LINKS)

dockerExec(new String[]{"chown", "-Rh", uid+":"+gid, dir.toAbsolutePath()})

As python plugin is generic, I have to add public dockerChown(path) method directly to python task, so it would be possible to use it in doLast hook:

task sample(type: PythonTask) {
    command = '-c "with open(\'build/temp.txt\', \'w+\') as f: pass"'
    doLast {
        dockerChown 'build/temp.txt'
    }
}

Also note that on windows operations on mounted files would perform slower. This is a known WSL2 limitation. It is not a big problem for a few files used, but a serious problem for hundreds or thousands of files. If you have windows PRO, you can try to disable WSL2 support in settings, switching to pure Hyper-V which should be much better.

Execution

There are two possible ways of command execution.

Container command

Command could be specified as container command:

try {
  GenericContainer container = new GenericContainer(...)
      .withStartupTimeout(Duration.ofSeconds(1))
      .withCommand("python", "--verson")
      .withLogConsumer(...)   
      .start()
} catch (Exception ex) {
    // if command execution failed it would mean container startup fail and so exception would
    // be thrown. But also, testcontainers would log error and entire output 
}

In this case, the container would execute command immediately after start and would be shut down after command execution.

Note that .start() would not wait when command execution finished, so you'll have to manually wait for container stopping:

while (container.isRunning() && !Thread.currentThread().isInterrupted()) {
    sleep(300)
}

(in case of gradle, you can't let task finish execution until docker command would be finished)

The downside is that we will have to lose some time starting and stopping containers (~300ms). Another downside is losing container state: for example, python plugin requires virtualenv module installed in order to create a virtual environment, but this also means that both commands (installation and env creation) must be executed in the same container (so, in my case, it was simply impossible to always use fresh containers).

The advantage of this approach is that we can receive command logs immediately (withLogConsumer). This is important for long running (or endless) processes, like mkdocs dev server. So I have to provide such an option for python tasks. In my experiments, it takes about 10 seconds for ryuk (shutdown container) to properly remove all started containers after emergency gradle stop (IDE stop or ctrl+d in console).

Testcontainers has many options to detect container readiness, but in my case the simplest timeout was enough (just wait and assume container is running): withStartupTimeout(Duration.ofSeconds(1)).

It is also possible to know the exact exit code for executed command, but in a complex way:

int exitCode = container
  .getDockerClient()
  .inspectContainerCmd(container.getContainerId())
  .exec()
  .getState()
  .getExitCode();

In-container command

Another approach is starting container with infinite command and execute commands inside it:

GenericContainer container = new GenericContainer(...)
    .withCommand('tail', '-f', '/dev/null')
    .withStartupTimeout(Duration.ofSeconds(1))  

container.start()
try {
    Container.ExecResult res = container.execInContainer(StandardCharsets.UTF_8, 
                         new String[]{"python", "--version"})
} finally {
  container.stop()
}

The downside is that we can obtain command output only after its execution:

res.getStdout().toString();
res.getStderr().toString();

In python plugin, pip installation tasks are usually long enough to feel discomfort of logs absence, but it is the only way.

In my case, in-container execution was a preferred way for running commands as I have many short-lived python commands and savings on not restarting the container for each command were significant.

It is important to note that you can configure container (working dir, environment variables and port bindings) only during container startup:

new GenericContainer(...)
  .withWorkingDirectory(workDir)
  .addEnv("SOME_ENV", "value")
  .withExposedPorts(8080)               // more on this below

For example, when you need a different working directory, you'll have to restart the container. In case of a python plugin, each python task could declare its own directory, environment and ports and so, to properly support this I have to validate current container parameters with the upcoming command requirements and restart container automatically when necessary.

That caused unavoidable restart for mkdocs plugin: python environment tasks use root project dir as working directory, but all mkdocs tasks use mkdocs sources directory as home and so in any case container have to be restarted (but single restart is not a problem).

Custom container

Most likely, you'll have to create your custom container class because:

• It is the only way to do static port bindings
• It is the only way to hide container errors in logs

class CustomContainer extends GenericContainer<CustomContainer> {

    PythonContainer(String image) {
        super(DockerImageName.parse(image))
    }
}

Startup errors logging

If container startup fails, testcontainers will throw an exception and log it together with recorded output. This is very handy in the test environment, but not desired in the plugin because it would duplicate the plugin's own logs (besides, in case of python plugin, python command failure might not be a problem at all).

The only way to hide these logs is to override logger creation in custom container class:

    @Override
    protected Logger logger() {
        // avoid direct logging of errors (prevent duplicates in log)
        return NOPLoggerFactory.newInstance().getLogger(CustomContainer.name)
    }

Note: without the --stacktrace option, gradle would show only the top-most exception message in the console (as a reason for failure). Testcontainers exceptions are hierarchical: for example, Container error -> Container failed to start -> Port 8080 already in use. In order to bring more clarity for the end used, it is better to collect all errors in the hierarchy and put it the top-most exception.

try {
  container.start()
} catch (Exception ex) {
    String msg = // collect all messages through hierarchy
    throw new GradleException("Container startup failed: \n" + msg);
}

Port bindings

By default, testcontainers use random port numbers: when you expose port with .withExposedPorts(8080) it would be actually bound to a random and free host port. You can obtain the actual assigned port using container.getMappedPort(8080).

This is perfect for tests, but in case of gradle plugin, fixed port bindings are required.

Testcontainers provide FixedHostPortGenericContainer to allow using fixed mappings, but it is deprecated (because it's not recommended). If we look into implementation we'll see that GenericContainer already contains protected method withFixedExposedPort, and so we can simply add a public method in our custom container class and use it:

  CustomContainer withFixedExposedPort(int hostPort, int containerPort){
        super.addFixedExposedPort(hostPort, containerPort, InternetProtocol.TCP)
        return self()
    }

And now ports binding would look like:

new CustomContainer(...)
  .withFixedExposedPort(8080, 8080)  // container 8080 to host 8080
  .withFixedExposedPort(9000, 9090)  // container 9090 to host 9000

Putting it all together

For python plugin requirements appear to be:

• As plugin execute a lot of python commands, one container should be used for all of them
• There must be an ability to run command in "exclusive" container for long-running tasks (for live logs)
• Fixed ports bindings required (much simpler to use in plugin then random ports)
• Containers are stateless - they must be destroyed after execution (some "caches" might be stored in project directory (like virtualenv))
• Project directory mapped into container
  • Root user rights fix required
  • Automatic path conversions required (in case of plugin it might be used directly with installed python and with docker). This also assumes OS specific corrections (linux containers could be started from windows).

Simple wrapper could easily abstract all docker-related staff:

public class ContainerManager {
    private String image;
    private CustomContainer container;

    public ContainerManager(String image) {
      this.image = image;
    }

    public void start() {
      if (container == null) {
          (container = createContainer())
              // container with infinite command
              .withCommand('tail', '-f', '/dev/null')
              .start();
      }
    }

    public void stop() {
      if (container != null) {
          container.stop();
          container = null;
      }
    }

    public void exec(OutputStream out, String[] command) {
         // note: command might need paths re-mapping (to convert native paths to docker paths)
         Container.ExecResult res = container.execInContainer(StandardCharsets.UTF_8, command);
         // delayed output
         if (res.stdout != null ) out.write(res.stdout.getBytes(StandardCharsets.UTF_8))
         if (res.stderr != null ) out.write(res.stdout.getBytes(StandardCharsets.UTF_8))
         // check correctness
         if (res.exitCode != 0) {
              throw new IllegalStateException("Execution failed")
         }
    } 

    public void execExclusive(OutputStream out, String[] command) {
         // simply starting new container exclusively for one command
         CustomContainer cont = createContainer()
         try {
              cont.withCommand(command)
                  // immediate logs streaming
                  .withLogConsumer { OutputFrame frame -> out.write(frame.bytes == null ? new byte[0]:  frame.bytes) }
                  .start()

              // wait for execution to finish (interruption check detect gradle task interruption)
              while (cont.isRunning() && !Thread.currentThread().isInterrupted()) {
                    sleep(300)
               }
         } catch (Exception ex) {
               // hide error
         } finally {
               cont.stop(); // for emergency ending (e.g. after ctrl + d)
         }

        // in case if you need exact exit code, otherwise exception above will always mean error
        int exitCode = container.getDockerClient().inspectContainerCmd(container.getContainerId())  
            .exec().getState().getExitCode(); 

        if (exitCode != 0) {
              throw new IllegalStateException("Execution failed")
         }
    }

    private CustomContainer createContainer() {
        return new CustomContainer(image)
            .withStartupTimeout(Duration.ofSeconds(1))
            // just an examples (variables declarations omitted)
            .withFileSystemBind(projectRootPath, projectDockerPath, BindMode.READ_WRITE)
            .withWorkingDirectory(projectDockerPath)
            .addEnv("SOME_ENV", "12")
            .withFixedExposedPort(8080, 8080)
    }
}

Note that this is not a working solution - just highlighting of the main moments (in real case, you'll have to take synchronization into account and properly implement container configuration).

My intention was only to show the main paths and pitfalls of how testcontainers could be used to relatively easily implement docker executions.

If you would need to do a gradle plugin for python module, you can use python plugin directly and get docker support out of the box (see mkdocs plugin implementation as reference).

Or see python plugin implementation for more implementation details.

We looked at adding a jupiter extension support module, but quickly dismissed it and decided to focus on finishing Spock 2.0, since we would have to emulate a large chunk of Jupiters internals to make it work.

It is a problem for two (obvious) reasons:

1. JUnit is much more popular and there is a great chance to find existing JUnit 5 extension, but almost no chance to find a Spock one.
2. For developer, maintaining two similar extensions for JUnit and Spock is a problem too: in JUnit 4 times Spock extensions model allows building much nicer extensions, but JUnit 5 abilities are almost equivalent.

I faced the later situation with dropwizard-guicey: currently it provides separate implementations for JUnit 4, JUnit 5 and Spock 1 and all guicey tests using Spock 1. But Spock 1 can't run on jdk16 or above which makes impossible for me to test guicey itself with jdk16 or 17.

Instead of implementing separate Spock 2 extensions, I decided to try implementing JUnit 5 extensions support and here it is: spock-junit5.

With it, alsmost any JUnit 5 extension could be used in Spock test (including custom annotations, parameters injection etc):

@ExtendWith(JunitExt)
class Test extends Specification {

   def "Check something"() {
       when: "do something"
       ...
       then: "some condition is correct"
       ...
   }
}

This post is not a user guide: you can always find all usage details in the project home page. Instead, It will highlight the motivation and some technical details.

Why Spock

If JUnit 5 is so much better then JUnit 4 maybe it's time to get rid of Spock? No, Spock is still way ahead of JUnit in terms of writing tests:

1. Spock tests are more structured and self-descriptive
2. Groovy allows writing much more compact and better-redable tests
3. Spock errors reporting is wonderful
4. Parametrized tests in Spock are compact and easy to read

Small example:

class TypesCompatibilityTest extends Specification {

    def "Check types compatibility"() {

        expect: 
        TypeUtils.isCompatible(type1, type2) == res

        where:
        type1                          | type2                       | res
        String                         | Integer                     | true
        Object                         | Integer                     | true
        String                         | Object                      | true 
    }
}

And in case of error:

Condition not satisfied:

TypeUtils.isCompatible(type1, type2) == res
|         |            |      |      |  |
|         false        |      |      |  true
|                      |      |      false
|                      |      class java.lang.Integer
|                      class java.lang.String
class ru.vyarus.java.generics.resolver.util.TypeUtils

Nice, isn't it? And no way to get anything near like this in JUnit.

Have to admit that sometimes (rare!) it cause additional problems: groovy compiler is not a java compiler and (in very! rare cases) there might be unexpected compilation problems with groovy classes (not tests, but additional classes, required for test). But you can always convert such classes to java (in IDEA there is an action for it) and everything will work. Besides, groovy 3 and 4 get much closer to java native compilation behaviour.

Using Spock (heavily) for years I have never faced cases I couldn't workaround.

Extension models

Spock and JUnit 5 extension models are both driven by annotations: you must put an annotation somewhere in test to activate extension (global extensions also possible, but almost never used).

But extension implementation approaches are different.

Spock extension

In Spock your extension must implement IAnnotationDrivenExtension where you must override one of its methods. It is already a bit confusing because you need to implement methods based on annotation target (different for class, field and test method annotations).

Inside this method you can apply an interceptor. This is very flexible, as you can hook in almost any lifecycle stage, but requires some knowledge (what to intercept and how to register interceptor properly).

For example, suppose extension annotation would be used on test class and extension would intercept test method execution:

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@ExtensionAnnotation(MyExtImpl)
@interface MyExt { }

class MyExtImpl implements IAnnotationDrivenExtension<MyExt> {
    @Override
    void visitSpecAnnotation(MyExt annotation, SpecInfo spec) {
        spec.allFeatures*.featureMethod*.addInterceptor { invocation ->

            // do something before test method

            invocation.proceed()

            // do something after test
        }

   }
}

Here interceptor implicitly implements IMethodInterceptor (note that invocation.proceed() is required).

But often it is required to hook into multiple places and here you can use AbstractMethodInterceptor with pre-defined lifecycle methods. The only problem would be to properly register such intercepter in all required places (Spock docs highlight all possible places).

Same example, but extension hooks around test methods and setup test stage:

class MyExtImpl implements IAnnotationDrivenExtension<MyExt> {
    @Override
    void visitSpecAnnotation(MyExt annotation, SpecInfo spec) {
        MyInterceptor interceptor = new MyIntrerceptor()

        spec.addSetupInterceptor interceptor
        spec.allFeatures*.featureMethod*.addInterceptor interceptor
   }
}

class MyInterceptor extends AbstractMethodInterceptor {

    @Override
    void interceptSetupMethod(final IMethodInvocation invocation) {
          // do something
          invocation.proceed()
     }

     @Override
     void interceptFeatureMethod(final IMethodInvocation invocation) {
          // do something
          invocation.proceed()
     }
}

As you can see, very flexible, but not very easy to understand model. And, by the way, it might not be obvious, but Spock extensions does not require groovy and could be written in java (Spock itself is written in java).

(More details in Spock extensions guide)

Junit 5 extension

In JUnit 5 there is a set of extension interfaces:

• ExecutionCondition
• BeforeAllCallback
• AfterAllCallback
• BeforeEachCallback
• AfterEachCallback
• BeforeTestExecutionCallback
• AfterTestExecutionCallback
• ParameterResolver
• TestInstancePostProcessor
• TestInstancePreDestroyCallback
• TestExecutionExceptionHandler
• (and a few more)

All of them extends base Extension class.

Actual extension implement required interfaces. And extension from Spock example would look like:

public class MyExtension implements BeforeEachCallback, 
                                    BeforeTestExecutionCallback,
                                    AfterTestExecutionCallback {
    @Override
    public void beforeEach(ExtensionContext context) throws Exception {
        // do something
    }

    @Override
    public void beforeTestExecution(ExtensionContext context) throws Exception {
        // do something
    }

    @Override
    public void afterTestExecution(ExtensionContext context) throws Exception {
        // do something
    }
}

Extension activation:

@ExtenWith(MyExtensions.class)
public class MyTest { ... }

Or you can make a custom annotation:

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@ExtendWith(MyExtensions.class)
public @interface MyExt {}

(More details in JUnit extension guide)

As you can see, JUnit extensions are very easy to write and understand. They are a bit less powerful then Spock extensions, but, to be honest, I doubt it would be a problem in the majority of cases.

So JUnit extensions are ideal for writing test integrations.

Lifecycles compatibility

JUnit and Spock share pretty much the same lifecycle (I did a comparison table).

Differences:

1. Spock owns test instance creation and so it is impossible to simulate JUnit test instance factory
2. Spock does not allow constructors (and so parameter injection in constructor is impossible)
3. Spock has a shared fields concept (more on it below)

In Spock, "shared fields" is a core feature, but it is implemented with an additional test instance: shared instance contains all shared fields and a new test instance created for each test method. When you accessing shared fields from test method it is "magically" routed to different (shared) instance.

There are two initialization hooks in Spock (each with different test instance):

• specInfo.addSharedInitializerInterceptor
• specInfo.addInitializerInterceptor

In JUnit, shared fields could be simulated with @TestInstance(LifeCycle.PER_CLASS). With it we will have a single test instance for all tests (by default, there are different instances for each test method).

JUnit extensions always receive a context object (as a parameter). It could be class-level context or method-level context containing test instance reference (there are other types, but in general these are the most important). If I would try to support shared fields, I'll have to call some JUnit extensions (like BeforeEach) two times, which may break extensions internal state. So it is not possible to support Spock shared fields for JUnit extensions (only one instance could be used in context).

Shared fields would be "invisible" for JUnit extensions: even if JUnit extension tried to initialize Spock shared field with reflection (it's just a field) - it would do it on "test" instance, but Spock magic would make this value invisible as every access to shared field is routed to a different instance.

Anyway, it should not be a problem because shared fields are not used often.

Copy paste

Here I should quote again Spock maintainers:

We looked at adding a jupiter extension support module, but quickly dismissed it and decided to focus on finishing Spock 2.0, since we would have to emulate a large chunk of Jupiters internals to make it work.

That is so true! I have to copy-paste a lot from junit-jupiter-engine (to grant the same behaviour).

Jupiter is a complete test engine and so it contains all the code required for test execution (fixture method calls, test method calls, exception handling etc.). As a result, it has some additional abstractions, which are not required in context of spock.

The root jupiter concept is descriptor (internal). There are multiple context levels: root with global extensions and configurations, test level, method level etc. Each descriptor contains (among other staff) extension resolution and execution) logic. For example, class level context - class level extensions resolution and before/after all calls. Method level context - method level extension resolution and before/after each calls (and others ofc.).

It was the most complex part: in context of spock, tests execution code is obviously not required and so only extension-related logic must be copy-pasted (and highly adapted) in order to preserve the same extensions behaviour. Extension registration logic was collected (from various places) into ExtensionUtils and all execution logic (extensions processing) into JupiterApiExecutor.

It was important to preserve the same extensions order and even exceptions behaviour (that's why copy-pasting was important).

As was already mentioned, JUnit extensions require context objects. JUnit use ~5 context implementations, but in terms of integration only 2 are important: class context and method context. It was also impossible to simply copy-paste existing jupiter implementations as they are too tied to internal contexts.

Contexts were re-implemented (they are quite simple). In context of spock many abilities are not used at all and so many context methods simply return empty objects.

Thankfully, there are shared utilities in JUnit which might be used without copy-pasting. For example, annotations search logic could be re-used through org.junit.platform.commons.util.AnnotationUtils class (not the official API, but also available).

And these missing parts were copied almost as-is:

• Value storage implementation (ExtensionValuesStore) - exact copy
• Condition evaluation (ConditionEvaluator) - exact copy
• ParameterContext implementation for parameter resolver extensions (DefaultParameterContext) - exact copy
• Extensions registry (ExtensionRegistry) - with simplifications because in JUnit there are extension tiers which are not needed in context of integration

Integration

JUnit extensions integration was implemented as global Spock extension. So you don't need to use any additional annotations to activate it: JUnit extensions registration will work exactly the same way as in JUnit.

Overall algorithm is pretty simple:

1. Try to find class-level extensions for each test. Here class-level JUnit context is created (without test instance)
2. Register required interceptors to be able to call JUnit extensions in correct Spock lifecycle stages (see this table for merged lifecycle)
3. On test method initialization (when test instance created for test method) create method-level context (containing test instance reference)

I have to hardcode two lists of extension types: supported and not supported. If not supported extension appear I could warn user about it in log (but not crash because it might be not important and everything would work without it).

If no known extension types recognized in registered extension - execution would would fail because nothing could be done in this case: all extension types have to be supported manually (at exact point extension method must be called manually for all registered extensions) and so unknown extensions couldn't do anything.

Probably not very obvious is conditional JUnit extensions support: for example, JUnit @Disabled could skip Spock test.

Before that project I was sure that Spock does not support parameter injections for test or fixture methods (never read guide that far), but it can! In fact, it keeps a marked list of parameters and all parameters Spock is not aware of are marked as MethodInfo.MISSING_ARGUMENT. So all I need is to call JUnit extensions for unknown parameters.

Important moment here is to not throw error when parameter not matched (as JUnit did) because there might be other Spock extensions responsible for injection (which could execute after global extension).

Maturity

So the project is almost completely built on copy-pasted code from jupiter engine. Ok, it will work, for now. But what about the future, when JUnit evolve (and it will)?

First of all, there are a lot of comments refencing original code source. So it would be possible to track and apply changes.

Secondly, there are two sets of tests: first set validates JUnit extensions behavior (with jupiter engine) and the second one validates that Spock behaves the same. So if some JUnit behaviour will change - I will know it from the first group of tests and correct Spock behaviour accordingly.

Previously, I wrote separate articles about how these tests were implemented using jupiter TestKit:

• Testing JUnit 5 extensions
• Testing Spock 2 extensions

Like JUnit's Jupiter, Spock 2 is implemented as JUnit platform engine and so TestKit might be used for running Spock tests too. But there are a few differences.

First of all, Spock already provides a shortcut for TestKit tests: spock.util.EmbeddedSpecRunner.

As with JUnit, suppose we want to check extension test method fail handling (and extension should stop this exception type):

@MySpockExtension
class extends Specification {

    void "test method fail"() {

        when:
        throw new IllegalStateException("Ups")

        then:
        true
    }
}

def specRunner = new EmbeddedSpecRunner()
specRunner.throwFailure = false
specRunner.runClass(FailingTestCase)
          .testEvents()
          .debug() // optional 
          .assertStatistics(stats -> stats.failed(1));

By default, EmbeddedSpecRunner re-throws exceptions which is not desirable (have to disable it for the same behavior as in pure JUnit kit tests).

Also, runner supports direct test compilation so the test itself could be described as a string instead of a separate class:

def specRunner = new EmbeddedSpecRunner()
specRunner.throwFailure = false
specRunner.run '''
package com.foo

import spock.lang.Specification
import spock.util.EmbeddedSpecRunner

@MySpockExtension
class extends Specification {

    void "test method fail"() {

        when:
        throw new IllegalStateException("Ups")

        then:
        true
    }
}
'''
          .testEvents()
          .debug() // optional 
          .assertStatistics(stats -> stats.failed(1));

This may look weird, but, probably, could be useful in some cases. At least, this solves the "failing tests problem" because the test in a string would never be recognized and executed directly. Still, I think separate test classes usage is handier.

You can find more EmbeddedSpecRunner usage examples in spock sources.

Failing tests problem

As with JUnit tests, failing test cases (used for TestKit tests) would be found and executed directly and fail the build. Spock does not support JUnit constraints and so @Disabled can't be used to skip "test scenarios" from separate execution. Spock @Ignore extension does not provide a way to disable for TestKit execution and that's why I have to use the following hack:

static Boolean ACTIVE = false with @Requires spock extension:

@Requires({ AbstractTest.ACTIVE })
class TestCase extends Specification { ...

Where AbstractTest.ACTIVE is set to true before each TestKit test (full source below) and reverted to false after.

You can evolve this approach for your case if required.

Testing parallel execution

As in JUnit, concurrent execution of test methods might be configured with @Execution(ExecutionMode.CONCURRENT) class annotation. IMPORTANT this is Spock annotation, not JUnit one (classes are the same just in different packages).

Executing several tests in parallel:

def specRunner = new EmbeddedSpecRunner()
specRunner.throwFailure = false
specRunner.configurationScript {
         runner {
             parallel {
                 enabled true
                 defaultExecutionMode ExecutionMode.CONCURRENT
                 defaultSpecificationExecutionMode ExecutionMode.CONCURRENT
             }
         }
}
specRunner.runClasses([Test1, Test2, Test3, Test4])
      .testEvents()
      .debug() // optional
      .assertStatistics(stats -> stats.succeeded(4));

WARNING: there should not be variables called the same as sections inside configurationScript (for example, runner, parallel, etc.) otherwise you'll see very non-intuitive errors.

In the example above both specs and spec methods would run in parallel, but you can configure differently. Also, note that for data-driven tests (with where section) each iteration is a different execution and so iterations could run in parallel too.

Simple testing technique

The base test from JUnit article would look like this for Spock:

abstract class AbstractTest extends Specification {

    // used for activating tests only for TestKit run
    static Boolean ACTIVE = false

    List<String> runTest(Class test) {
        ActionHolder.cleanup()
        ACTIVE = true
        try {
            def specRunner = new EmbeddedSpecRunner()
            // do not rethrow exception - all errors will remain in holder
            specRunner.throwFailure = false
            specRunner.runClass(test)
                    .allEvents().failed().stream()
                    // exceptions appended to events log
                    .forEach(event -> {
                        Throwable err = event.getPayload(TestExecutionResult.class).get().getThrowable().get();
                        ActionHolder.add("Error: (" + err.getClass().getSimpleName() + ") " + err.getMessage())
                    })
            return ActionHolder.getState()
        } finally {
            ACTIVE = false
            ActionHolder.cleanup()
        }
    }
}

Here, as in JUnit example, all execution errors are collected as string messages, so when anything goes wrong the list of the resulting strings would be different.

Complete example case for testing parameters injection (assuming extension injects required parameter):

@Requires({ AbstractTest.ACTIVE })
@MySpockExtension
class ExceptionCase extends Specification {

    def "Sample test"(Integer arg) {

        when:
        ActionHolder.add("test.body $arg")
        throw new IllegalStateException('Ups')

        then:
        true
    }
}

And the main TestKit test:

class SpockTest extends AbstractTest {

    def "Check parameter"() {

        expect: 'test fails'
        runTest(ExceptionCase) == [
                                  "test.body 11",
                                  "Error: (IllegalStateException) Ups"]
    }
}

TestKit dependency will be required: org.junit.platform:junit-platform-testkit

All required dependencies (gradle example):

testImplementation 'org.junit.jupiter:junit-jupiter-api:5.8.2'
testImplementation 'org.junit.platform:junit-platform-testkit:5.8.2'
testRuntimeOnly 'org.junit.jupiter:junit-jupiter:5.8.2'

Suppose we want to test situation when test throws an exception (because our extension implements TestExecutionExceptionHandler and we need to test its behaviour).

Writing test implementing required scenario:

@ExtendWith(MyExtension.class)
public class FailingTestCase {

    @Test
    public void test() {
        throw new IllegalStateException("Ups");
    }
}

And now the main (TestKit) test:

import static org.junit.platform.engine.discovery.DiscoverySelectors.selectClass;

public class MyExtensionFailureBypassTest {

    @Test
    public void testExceptionBypass() {
       EngineTestKit
             .engine("junit-jupiter")
             .selectors(selectClass(FailingTestCase.class))
             .execute()
             .testEvents()
             .debug() // optional 
             .assertStatistics(stats -> stats.failed(1));
    }
}

Here we test that exception was thrown (suppose extension should not handle this type of exceptions). More assertion technics could be found in junit docs - I just want to show the base idea here.

Note that there are different scopes of events: .testEvents(), .containerEvents() and .allEvents().

Failing tests problem

There is one problem: test scenario is also a valid junit test and so it would be found and executed during all tests execution. To avoid it annotating test case as disabled:

@Disabled
public class FailingTestCase { ...

And in TestKit test ignoring this annotation:

EngineTestKit
       .engine("junit-jupiter")
       .configurationParameter("junit.jupiter.conditions.deactivate", "org.junit.*DisabledCondition")

Now only TestKit tests will be executed and all "scenario" tests would be ignored.

Testing parallel execution

Parallel execution for several tests could be configured only on engine level so all tests execution is either parallel or not (on test class level parallel methods execution could be activated with @Execution(ExecutionMode.CONCURRENT) annotation). With TestKit you can run just a few tests in parallel and validate behavior:

EngineTestKit
      .engine("junit-jupiter")
      .configurationParameter("junit.jupiter.conditions.deactivate", "org.junit.*DisabledCondition")
       // enable parallel execution
      .configurationParameter("junit.jupiter.execution.parallel.enabled", "true")
      .configurationParameter("junit.jupiter.execution.parallel.mode.default", "concurrent")
       // use 4 tests to run in parallel
      .selectors(selectClass(Test1.class),
          selectClass(Test2.class),
          selectClass(Test3.class),
          selectClass(Test4.class))
      .execute()
      .testEvents()
      .debug()
      .assertStatistics(stats -> stats.succeeded(4));

Simple testing technique

OK/KO situations testing is often not enough: often you need to keep some state from the test in order to validate it in the TestKit test. The simplest way is to introduce shared thread local state:

public class ActionHolder {

    private static ThreadLocal<List<String>> STATE = new ThreadLocal<>();

    public static void cleanup() {
        STATE.remove();
    }

    public static void add(String state) {
        List<String> st = STATE.get();
        if (st == null) {
            st = new ArrayList<>();
            STATE.set(st);
        }
        st.add(state);
    }

    public static List<String> getState() {
        return STATE.get() == null ? Collections.emptyList() : new ArrayList<>(STATE.get());
    }
}

During the test, we would add strings to it and after TestKit execution would verify the results.

Such storage requires careful management, so it's better to move all test boilerplate into base test:

public abstract class AbstractTest {

    public List<String> runTest(Class test) {
        ActionHolder.cleanup();
        try {
            EngineTestKit
                  .engine("junit-jupiter")
                  .configurationParameter("junit.jupiter.conditions.deactivate", "org.junit.*DisabledCondition")
                  .selectors(selectClass(test))
                  .execute()
                  .allEvents().failed().stream()
                  // exceptions appended to events log
                  .forEach(event -> {
                      Throwable err = event.getPayload(TestExecutionResult.class).get().getThrowable().get();
                      ActionHolder.add("Error: (" + err.getClass().getSimpleName() + ") " + err.getMessage());
                  });
            return ActionHolder.getState();
        } finally {
            ActionHolder.cleanup();
        }
    }
}

Note that all exceptions are also added to the holder after execution, so if something goes wrong you'll know about it (no false-positive tests).

Let's take the initial case and assume that it also implements ParameterResolver and so we need to check the correctness of injected parameters:

@Disabled
@ExtendWith(MyExtension.class)
public class FailingTestCase {

    @Test
    public void test(Integer arg) {
        ActionHolder.add("test.arg: " + arg)
        throw new IllegalStateException("Ups")
    }
}

TestKit test:

public class StateTest extends AbstractTest {
    @Test
    public void testParams() {
        Assertions.assertEquals(Arrays.asList(
                "test.arg: 11",
                "Error: (IllegalStateException) Ups"

                ), runTest(FailingTestCase.class))
    }
}

Here we can validate that correct parameter value was injected and the exception. Note that in any case, all errors would be at the end of the list.

Such tests would be safe to execute in parallel because the state is managed under a single test method only.

As an example, I used this technique to validate (confirm) junit lifecycle sequence.

Follow up: How to do the same in Spock 2

Here is the way for updating YAML configs preserving comments and all current values.

Preparing the tool

The tool could be used in different ways, but I'll show the most universal command line usage.

Download yaml-config-updater-cli-1.2.0-all.jar from maven central.

wget https://repo1.maven.org/maven2/ru/vyarus/yaml-config-updater-cli/1.2.0/yaml-config-updater-cli-1.2.0-all.jar

Java 8 or above must be installed in the target environment.

Adding missed properties

Suppose your config is:

section:
    # Important description
    # Value was manually updated (must be preserved)
    prop1: 12

In the new version, new property was added:

section:
    # Important description
    prop1:  # value must be put manually after installation

    # New description
    prop2: 10

Performing migration:

java -jar yaml-config-updater-cli-1.2.0-all.jar config.yml update.yml

Output report:

Updating configuration: /home/user/test/config.yml

Configuration: /home/user/test/config.yml (105 bytes, 5 lines)
Updated from source of 137 bytes, 6 lines
Resulted in 93 bytes, 7 lines

    Added from new file:
        section/prop2                            6  | prop2: 10

    Backup created: config.yml.20210911140958

As a result, the new property would be added to the current config:

section:
    # Important description
    prop1: 12

    # New description
    prop2: 10

Note that the prop1 comment was also changed, as comment from updating file may contain important information updates. Only in-line comments (after value) survive merging.

If you don't trust the report you can easily build diff with the created backup file (original config):

diff config.yml.20210911140958 config.yml
5a6,8
>     # New description
>     prop2: 10
>

The trust

Good question: why should you trust the tool?
The tool is very young and most likely there are still bugs and uncovered cases.

And still, I can guarantee that the resulted file would be correct:

• Internally, time-prooved snakeyaml parser used for all files validation. This way "comments" parser can be sure to always work with the correct YAML.
• But that's not all. Parsed trees from comments and snakeyaml parsers are compared to eagerly detect incorrect parsing (self-validation)
• Merge result is read by snakeyaml to make sure the file is correct.
• Merged file values are carefully checked: all old values must be preserved and all new values added (using snakyaml trees to operate exact values).

So you can be sure that the resulted config would be correct. If anything goes wrong, the configuration file would not be touched at all.

Removing values

Adding new properties is not the only case: some properties might be removed in the actual configuration.

By default, the tool would not remove properties, so the merged file would still contain them. In order to remove a property, you must explicitly specify it.

For example, suppose in config:

prop1: 1

sub:
    foo: 2
    bar: 3

prop1 and foo are no longer needed.

java -jar yaml-config-updater-cli-1.2.0-all.jar config.yml update.yml -d prop1 sub.foo

Updating configuration: /home/user/test/config.yml

Configuration: /home/user/test/config.yml (36 bytes, 6 lines)
Updated from source of 11 bytes, 2 lines
Resulted in 18 bytes, 4 lines

    Removed from old file:
        prop1                                    1  | prop1: 1
        sub/foo                                  4  | foo: 2

    Backup created: config.yml.20210911144139

This may be also used for replacing values: removed property would be replaced with a property from updating config with the default value.

You can remove entire sub-trees this way.

Config-template

Another common need is configuration "adoption" for the target environment. In this case, updating configuration become "a template" with placeholders to replace by environment-specific values:

prop1: #{one}
prop2: #{two}
prop3: #{three}

java -jar yaml-config-updater-cli-1.2.0-all.jar config.yml update.yml -e one=1 two=2

Also, this time, updating configuration does not exist yet (first installation case).

Updating configuration: /home/user/test/config.yml 

Not exising configuration: /home/user/test/config.yml 
Updated from source of 33 bytes, 3 lines
Resulted in 34 bytes, 3 lines

    Applied variables:
        two                       = 2
        one                       = 1

    New configuration copied as-is

The resulted config would be:

prop1: 1
prop2: 2
prop3: #{three}

Note that the third variable was not processed (as the value was not specified), but it is not a problem as any YAML parser would treat this placeholder as an in-line comment.

Environment variables might also be specified in a property file (and multiple files could be specified). By default, system environment variables are all provided (use -i option to see the list of all available variables during processing).

Links

This was just a brief introduction. More info could be found in github repository:

• Project root
• API module
• CLI tool
• Dropwizard module

• 2.0.1 for hiberante-validator 6.x
• 3.0.1 for hiberante-validator 7.x

Both versions depend on guice 5 now, but are still compatible with guice 4 (just exclude transitive dep to downgrade).

The main reason for the release was a bug leading to manually specified Default group ignoring in strict groups mode:

new ValidationModule().strictGroupsDeclaration()

For example,

public class Service {
    public void method(@NotNull(groups = CustomGroup.class) String arg1, 
                                        @NotNull String arg2 {
         ....
    }
}

When user manually specify Default group, e.g. like this:

@Inject ValidationContext context;
@Inject Service service;

context.doWithGroups(() -> {            
                service.method("foo", null);
        }, Default.class, CustomGroup.class);

It was ignored and the call did not fail with a validation error (only in strict groups mode!).

I doubt anyone was ever affected by this, but just in case.

Caused by: java.lang.reflect.InaccessibleObjectException: Unable to make protected final java.lang.Class java.lang.ClassLoader.defineClass(java.lang.String,byte[],int,int,java.security.ProtectionDomain) throws java.lang.ClassFormatError accessible: module java.base does not "opens java.lang" to unnamed module @270421f5
    at java.base/java.lang.reflect.AccessibleObject.checkCanSetAccessible(AccessibleObject.java:357)

Of course, you can simply revert the previous behavior with the VM argument: --illegal-access=permit, but this option will be removed in JDK 17.

The solution could be found in javassits issue: you must not use CtClass#toClass() or toClass(classloader) anymore, instead use toClass(neighborClass).

BUT this method will only work for java >= 9, so if you need to support java 8, you'll have to use both methods:

// some class from classpath (neighbor) to inherit classloader and domain permissions from
Class<?> baseClass = ...;
boolean isJava8 = System.getProperty("java.version").startsWith("1.8");

CtClass generated = ...;
Class<?> result = isJava8 
         // java 8 only
         ? generated.toClass(baseClass.getClassLoader(), baseClass.getProtectionDomain())
         // java 9 and above
         : generated.toClass(baseClass);

The minimal required javassist is 3.24.